Python Context

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

Top-level fields

Field	Type	Description
`conversation`	`dict` or `None`	The current conversation — messages, IDs, subject, and channel info
`business`	`dict`	The business this conversation belongs to
`customer`	`dict` or `None`	The customer's profile — `None` if the customer hasn't been identified
`args`	`dict`	Arguments passed to the function (custom actions, condition providers, and event handlers)
`workflow`	`dict`	The workflow being evaluated — only present when the bot runs a condition provider
`browser_session`	`dict` or `None`	Browser session data — only present for web chat conversations

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

Field	Type	Description
`id`	`str`	Internal conversation UUID
`publicId`	`str`	Short public ID shown in the dashboard (e.g., "A1B2C3")
`url`	`str`	Direct link to this conversation in the Octocom dashboard
`subject`	`str`	Conversation subject line
`businessSlug`	`str`	Slug of the business this conversation belongs to
`isHandedOff`	`bool`	Whether the conversation has been handed off to a human agent
`isPlayground`	`bool`	Whether this is a dashboard playground conversation rather than a real customer one. Use it to relax checks that would otherwise block testing (e.g. consultant working hours)
`initialChannel`	`str` or `None`	Channel of the first message (e.g., `"web"`, `"email"`, `"instagram"`)
`latestChannel`	`str` or `None`	Channel of the most recent message
`inboxAddress`	`str` or `None`	Business mailbox used by the latest email thread. `None` for conversations without a resolvable email inbox
`assignee`	`dict` or `None`	The agent currently assigned to the conversation — `{"id": str, "name": str, "email": str}`, or `None` when unassigned
`tags`	`list`	Titles of the tags currently on the conversation, e.g. `["contact-form", "vip"]`. Empty when untagged
`metadata`	`dict`	Conversation metadata as `{key: value}`, including the `chat-widget:*` keys the web chat writes. Read it from here instead of calling `get_conversation_metadata()` when you only need current values — no HTTP round-trip
`messages`	`list`	Array of message objects (see below)

Messages

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

Field	Type	Description
`sender`	`str`	Who sent the message — `"customer"`, `"bot"`, or `"agent"`
`timestamp`	`str`	When the message was sent (ISO 8601 format)
`content`	`str`	The message text
`channel`	`str`	The channel the message was sent on
`agentName`	`str` or `None`	Name of the agent who sent the message — set on agent-sent messages, `None` otherwise
`agentEmail`	`str` or `None`	Email of the agent who sent the message — set on agent-sent messages, `None` otherwise
`files`	`list`	Files attached to the message (see below). Empty if none

Message files

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

Field	Type	Description
`id`	`str`	File unique identifier
`name`	`str`	Original filename
`contentType`	`str`	MIME type of the file (e.g., `"image/jpeg"`, `"application/pdf"`)
`url`	`str`	Public URL to download the file
`isSafe`	`bool`	Whether the file passed malware scanning. Avoid forwarding files where this is `False`

`context["business"]`

Basic information about the business.

Field	Type	Description
`name`	`str`	The business name
`slug`	`str`	The business slug

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

Field	Type	Description
`id`	`str`	Internal customer UUID
`email`	`str` or `None`	Customer email address
`name`	`str` or `None`	Customer name
`phone`	`str` or `None`	Customer phone number
`instagramUsername`	`str` or `None`	Customer's Instagram handle

`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"])
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 widgets — do not receive args

`context["workflow"]`

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

Field	Type	Description
`id`	`str`	Internal workflow UUID
`slug`	`str`	Stable workflow slug
`title`	`str`	Workflow display title

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:

Field	Custom Actions	Condition Providers	Event Handlers	Sidebar Widgets
`conversation`	If available	If available	Always	Always
`business`	Always	Always	Always	Always
`customer`	If available	If available	If available	If available
`args`	Always	Always	Always	Not present
`workflow`	Not present	Bot execution only	Not present	Not present
`browser_session`	Web chat only	Web chat only	Web chat only	Web chat only

Python Context

On this page