Python Helpers
Built-in helper functions for custom actions, condition providers, event handlers, recurring jobs, and sidebar widgets.
If you write custom logic in Python on Octocom — actions, condition providers, event handlers, recurring jobs, or sidebar widgets — these built-in helpers let you read conversation data, persist organization state, classify text, and reach the integrations you've connected, without installing or importing anything.
Python-based features in Octocom share a built-in helper library. Whether you're writing a custom action, a condition provider, an event handler, a recurring job, or a sidebar widget, helpers are available without imports. A few mutating helpers are limited to safe execution contexts; each helper page lists any restriction.
Click any function name for full documentation with parameters, return types, and examples.
Conversation data
| Helper | What it does |
|---|---|
get_conversation_metadata(context, key) | Read a metadata value from the conversation |
set_conversation_metadata(context, key, value) | Write a metadata value to the conversation |
delete_conversation_metadata(context, key) | Delete a metadata key from the conversation |
set_data_collection_result(context, key, value) | Store a collected data result for analytics and campaign KPIs |
add_conversation_tag(context, tag) | Add a tag to the conversation |
remove_conversation_tag(context, tag) | Remove a tag from the conversation |
add_conversation_note(context, text) | Add an internal note, visible to agents only |
get_conversation_notes(context) | Read the internal notes already on the conversation |
add_conversation_event(context, event) | Record an event in the conversation timeline |
send_bot_message(context, text, idempotency_key, conversation_id=None) | Send a fixed message through an existing conversation |
close_conversation(context, reason=None, conversation_id=None) | Close a conversation through the normal close pipeline |
hand_off_conversation(context, reason=None) | Hand off the conversation to a human agent |
octocom_agents_available(context) | Check whether any help desk agent is currently available |
set_message_sending_delay(context, delay_min) | Control how long the AI waits before sending its replies (email only) |
Chat display
Show the customer something richer than text under the bot's reply. Rendered by the experimental V2 web chat widget; every other channel ignores it, so keep returning the facts for the bot to answer with.
| Helper | What it does |
|---|---|
show_card(context, title, fields=None, subtitle=None, image_url=None, buttons=None) | Show a card with label/value rows and up to three buttons |
ask_confirmation(context, title, confirm_label, cancel_label, description=None, destructive=False) | Ask the customer to confirm with two buttons before the bot acts |
Human decisions
Ask a teammate for a decision while the bot retains the conversation. See Human-in-the-Loop Decisions for the complete two-action setup and workflow instructions.
| Helper | What it does |
|---|---|
request_human_decision(context, key, summary, decisions, info=None) | Create a decision card or return the existing request for the same key |
get_human_decision_result(context, key) | Read the pending or resolved outcome for a request |
LLM classification
| Helper | What it does |
|---|---|
llm_classify_binary(prompt, input, fallback=None) | Classify input as True or False using an LLM |
llm_classify_category(prompt, input, options, fallback=None) | Classify input into one of the provided categories |
llm_summarize(context, prompt, input=None, max_words=None) | Summarize the conversation, or any text |
Experimentation
| Helper | What it does |
|---|---|
get_ab_test_variant(context, test_name, possible_variants) | Get a sticky A/B test variant for this conversation |
Organization state
| Helper | What it does |
|---|---|
organization_store_create(namespace, key, value) | Create a durable organization-scoped JSON entry |
organization_store_get(namespace, key) | Read an organization store entry |
organization_store_upsert(namespace, key, value, if_revision=None) | Create or replace an entry, optionally at an expected revision |
organization_store_compare_and_set(namespace, key, value, if_revision) | Win one atomic state transition among competing executions |
organization_store_delete(namespace, key, if_revision=None) | Delete an entry, optionally at an expected revision |
organization_store_list(namespace, ...) | List a bounded, cursor-paginated page |
organization_store_search(namespace, filter, ...) | Search values using exact JSON containment |
Phone campaigns
| Helper | What it does |
|---|---|
add_campaign_recipients(campaign_id, recipients) | Add people to a continuous phone campaign's calling queue |
Utilities
| Helper | What it does |
|---|---|
add_google_sheets_row(sheet_id, data, sheet_name=None) | Append a row to a Google Sheet, optionally to a named tab |
list_google_sheets_rows(sheet_id, ...) | List or find rows with bounded cursor pagination |
update_google_sheets_row(sheet_id, data, ...) | Conditionally patch one uniquely identified row |
list_google_sheets_tabs(sheet_id) | List ordered tabs, visibility and grid dimensions |
read_google_sheets_range(sheet_id, range, sheet_name=None) | Read positional cells, hyperlinks, formulas, notes and merges without headers |
write_google_sheets_range(sheet_id, range, values, ...) | Overwrite a bounded rectangle; literal values by default |
clear_google_sheets_range(sheet_id, range, sheet_name=None) | Clear values/formulas while preserving formatting and row positions |
send_slack_notification(webhook_url, text) | Send a notification to a Slack channel via webhook |
is_holiday(country, state=None, region=None, check_date=None) | Check if a date is a public holiday |
send_outbound_email(context, params) | Send an outbound email creating a new handed-off conversation |
proxy_request(method, url, **kwargs) | Make an HTTP request through Octocom's stable egress IP — for APIs that allowlist by IP |
proxy_session(headers=None) | A requests.Session pre-routed through the stable egress IP, for multi-call API clients |
transcribe_pdf(url) | Extract text from a public PDF URL, including OCR for scanned pages |
Browser automation
| Helper | What it does |
|---|---|
open_browser(connection_id, purpose) | Open a guarded, audited browser session from a saved mutable automation; use a context manager to close it |
Explore a website with Copilot or MCP browser tools, then save and test the verified sequence as a Python action. Browser helpers run in the Cloudflare Python sandbox and use the same semantic selectors and guards as the browser tools. They are unavailable in read-only execution contexts and unsaved snippets.
Secrets
| Helper | What it does |
|---|---|
get_secret(name, default=None) | Read an API key or token from your secret vault |
Integration credentials
| Helper | What it does |
|---|---|
get_integration_credentials(context) | Get installed integration credentials to call platform APIs. For Magento, read the action playbook. |
This is how you talk to the platforms you've connected. Rather than shipping a thin wrapper per platform per operation, Octocom hands you the credentials and gets out of the way — so your action isn't limited to whatever we thought to wrap, only to what that platform's API allows.
Ask Copilot or an agent on the Octocom MCP to build the action for you: describe the outcome you want, and it writes the code, creates the action, and tests it. See Shopify Custom Actions for a full worked playbook.
All Python functions receive a context dictionary with conversation data, customer profile, and more. See Python Context for the full reference.
For signatures, examples, access and timeout recovery, see Google Sheets: tables, ranges and reliability.