Skip to main content
Purpose: run a side effect automatically as soon as a call connects or a capability or pathway node is entered. The stored function type is exactly on_connected. It is a custom lifecycle function, not a predefined function such as transfer, end, or booking. Key points:
  • A global On-Connected function runs once after the call connects.
  • A capability- or node-scoped On-Connected function runs when that capability or node is entered.
  • The runtime invokes it automatically. The voice agent does not select it, and no customer intent or function description triggers it.
  • Its return value is ignored. Use it for side effects, not for information that the conversation needs to consume.
  • It receives call metadata, including the same metadata variables available to the call.
Common uses: log that a call connected, notify an external service, initialize a session in another system, warm up data, or record entry into a specific capability or pathway node.
Adding instructions to the opening script is not equivalent to an On-Connected function. Script instructions guide what the agent says or does; on_connected executes a runtime integration automatically.

​
Supported agent version types

On-Connected functions are supported by every voice-agent version type. If the same behavior is needed globally and in a capability or node, create a separate function entry in each scope.

​
Basic vs Advanced On-Connected

The function mode is independent of the agent version type. For example, a Basic agent version can use an Advanced On-Connected function.

​
Basic On-Connected

Use Basic mode for a direct HTTP request. Configure:
  • function name and description
  • API URL
  • method: GET, POST, PUT, or DELETE
  • request parameters
  • headers

​
Advanced On-Connected

Use Advanced mode for custom Python side effects, including logging, conditional logic, or multiple API operations. The function must use this signature:
Use ctx.room, ctx.proc.userdata, or ctx.api when runtime context is required. ctx.session, ctx.userdata, and RunContext are not available. Use saved secret references such as x_secrets["crm-api-key"] instead of hardcoded credentials.
Keep connection-time work short and failure-tolerant so it does not delay call setup. Use a Pre-Call function when data must modify the prompt, an In-Call function when the agent needs the result during conversation, and a Post-Call function for work after hangup.