Python Helpers

If you write custom logic in Python on Octocom — actions, condition providers, event handlers, recurring jobs, sidebar widgets, or product-sync parsers — 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)

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

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
`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

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 the credentials of the integrations installed on your businesses, so your code can call those platforms' APIs directly

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.