> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callkaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 2. On-Connected Functions

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

<Warning>
  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.
</Warning>

## Supported agent version types

On-Connected functions are supported by every voice-agent version type.

| **Agent version type**    | **Supported scope and timing**                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| **Basic (Type 0)**        | Top-level `functions[]`; runs once after the call connects.                                 |
| **Advanced (Type 1)**     | Top-level `functions[]`; runs once after the call connects.                                 |
| **Multi Prompt (Type 2)** | Top-level for call connection, or inside a capability's `functions[]` for capability entry. |
| **Pathway (Type 3)**      | Top-level for call connection, or inside a node's `functions[]` for node entry.             |

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:

```python theme={null}
async def function_name(ctx: JobContext, metadata: dict):
    # Perform a connection-time side effect.
    pass
```

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.

<Tip>
  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.
</Tip>