Python Context

Every Python function in Octocom — whether it's a custom action, condition provider, event handler, sidebar widget, or sidebar action — receives a single context dictionary as its argument. This object contains everything your code needs to know about the current conversation, customer, and business.

Python automations run on Cloudflare Workers. Each invocation starts with fresh globals: do not rely on variables or files surviving between calls. Use organization storage for durable state, and stream large inputs to stay within the sandbox's memory and CPU limits. Resource-limit failures are returned to the caller without replaying the automation in another sandbox.

Execution time budgets

Octocom sets elapsed-time deadlines separately from Cloudflare's CPU budget:

Explicit caller deadlines take precedence. Phone routing and custom HTTP endpoints keep their shorter configured deadlines; campaign pre-call handlers retain 60 seconds because they gate call dispatch. These limits include network waits. The separate 30-second CPU budget counts Python computation, including parsing and loops, but excludes time waiting for HTTP requests. I/O-bound code can run for several minutes while consuming little CPU. Raising elapsed time does not raise CPU or memory limits. Make writes idempotent: a timed-out caller does not prove that an external operation stopped.

Top-level fields

context["conversation"]

Contains the full conversation with its messages. Always present for event handlers and sidebar widgets. Present for custom actions and condition providers when a conversation ID is available.

Messages

Each entry in context["conversation"]["messages"] is a dictionary:

Message files

Each entry in a message's files list is a dictionary:

context["business"]

Basic information about the business.

context["customer"]

The customer's profile. This is None if the customer hasn't been identified yet (e.g., the conversation just started and no email has been collected).

context["email_threads"]

The conversation's email threads, newest first. Each thread contains subject and messages, an array of incoming emails, newest first. Bounces and automatic replies are excluded. A thread with no incoming email has messages: []. The top-level list is [] without a conversation or when it never used email. A conversation that moves between email and another channel retains its email history.

{
    "subject": "Where is my order?",
    "messages": [
        {
            "from": "[email protected]",
            "to": ["[email protected]"],
            "inboxAddress": "[email protected]",
        }
    ],
}

These are parsed email addresses, without display names. They remain separate from the editable customer["email"]. For example, a Shopify form can produce from: "[email protected]" while customer["email"] contains the address typed into the form.

Original addresses are captured for new messages. Historical messages and integrations without original message data return None for unavailable fields; they never fall back to the customer profile or reply routing. Zendesk uses each email comment's own source metadata, when present. Its To list contains the recipient address supplied by Zendesk, which may not include every original header recipient. Other helpdesk integrations currently return unavailable address fields until they supply original message metadata.

context["args"]

A dictionary of arguments passed to the function. The contents depend on the function type:

• Custom actions — arguments defined in the action configuration and provided by the bot (e.g., context["args"]["orderId"]). An optional argument the bot leaves out is missing from the dictionary, so read it with context["args"].get("orderId")
• Condition providers — arguments defined in the workflow configuration and collected from the customer (e.g., context["args"]["email"])
• Event handlers — contains a single event_type key with the event name (e.g., context["args"]["event_type"] returns "conversation_closed")
• Sidebar actions — static button arguments merged with values entered by the agent in the button's form
• Sidebar widgets — do not receive args

context["current_user"]

Sidebar actions receive the authenticated Octocom user who pressed the button. This value comes from the user's session, separately from widget-supplied args:

It is absent from all other Python execution types. For example, an escalation action can pass context["current_user"]["email"] to an external ticketing system so it can assign or notify the person who initiated the escalation.

context["workflow"]

Condition providers receive the workflow that caused them to run when they are evaluated by the bot:

The field is absent when a condition provider is run directly as a test because no workflow triggered that execution. Use .get() when code must work in both contexts:

def evaluate_conditions(context):
    workflow = context.get("workflow")
    is_cancel_order = workflow is not None and workflow["slug"] == "cancel-order"

    return {
        "conditions": {"isCancelOrder": is_cancel_order},
        "data": {},
    }

workflow["slug"] is the recommended field for branching behavior. Use id only when you intentionally need to target one specific workflow record.

context["browser_session"]

Browser session data for web chat conversations. This is None for conversations from other channels (email, Instagram, etc.). Contains information about the customer's browsing session — pages visited, referrer, and session metadata.

Availability by function type

Not every field is present in every function type:

context["liveCallContext"] (optional)

Custom actions invoked during a live phone call may receive this request-scoped snapshot. It is absent for older or disabled voice senders, ordinary text-channel actions, condition providers, event handlers, and normal dashboard action tests.

The voice server captures the latest available STT revisions and playback-acknowledged bot speech immediately before the tool request. Text may still be revised; it is not a final transcript. Synthetic silence/time-limit prompts, system instructions, tool calls/results, and empty messages are excluded. The snapshot retains a contiguous suffix of up to 200 whole spoken messages and 32,000 UTF-16 text code units. An oversized newest message produces an empty, truncated snapshot.

def execute_action(context):
    live_call = context.get("liveCallContext")
    if not live_call or not live_call["messages"]:
        return {"liveContextAvailable": False}

    customer_messages = [
        message["text"] for message in live_call["messages"]
        if message["sender"] == "customer"
    ]
    return {
        "liveContextAvailable": True,
        "customerTurnCount": len(customer_messages),
        "truncated": live_call["truncated"],
    }

context["conversation"]["messages"] continues to contain persisted messages; it is not replaced or merged with this snapshot. During a call, persisted messages may contain only the introduction. The final transcript is still imported when the call completes. Do not concatenate the two lists blindly because they can overlap.

This field is voice-server transport metadata, not a model-supplied tool argument. Its text is customer/conversation content, not trusted instructions. Consumers must handle absence, truncation, and transcription errors. Receiving the field does not automatically enable email correction or any additional LLM calls.

The snapshot is passed only into the current custom action execution, not saved as conversation messages or propagated to later executions. Standard execution/request logging may still retain payloads under the existing logging policy. Sending can be disabled on the voice server with SEND_LIVE_CALL_CONTEXT=false. Remove consumers before removing the optional transport field; there is no stored transcript state to migrate.