Lifecycle hooks

Three agent fields attach a tool that runs at a fixed moment rather than when the model calls it. Each is one tool reference (tool_id, or an inline tool) or null. A stored tool must be published before you attach it, and publishing the agent pins its version (see versions).

curl -X PATCH https://api.talqing.com/v1/agents/6f2b0f4c-2f3d-4c7a-9c1e-1d2a8f0b41c7 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "on_enter": { "tool_id": "3d7c1f88-4a2e-4b16-9b52-0f3a1c4d5e60" },
      "on_exit": { "tool_id": "9a1e2b74-6c33-4f0a-8b12-77c5d9e0aa31" }
    }
  }'

await talqing.agents.update({
  agent_id: "6f2b0f4c-2f3d-4c7a-9c1e-1d2a8f0b41c7",
  updateAgentRequest: {
    config: {
      on_enter: { tool_id: "3d7c1f88-4a2e-4b16-9b52-0f3a1c4d5e60" },
      on_exit: { tool_id: "9a1e2b74-6c33-4f0a-8b12-77c5d9e0aa31" },
    },
  },
});

talqing.agents.update(
    "6f2b0f4c-2f3d-4c7a-9c1e-1d2a8f0b41c7",
    config={
        "on_enter": {"tool_id": "3d7c1f88-4a2e-4b16-9b52-0f3a1c4d5e60"},
        "on_exit": {"tool_id": "9a1e2b74-6c33-4f0a-8b12-77c5d9e0aa31"},
    },
)

An explicit null detaches a hook. Publish the agent for calls to pick it up.

When each fires

Hook	Voice and video	Text	Arguments
`on_enter`	Session start or handoff in, before the greeting	When the chat’s first message arrives (once per chat)	None
`on_exit`	Call end, or a handoff away from this agent	When the chat ends (`end_call` or `POST /v1/chats/{chat_id}/end`), or a handoff away	None
`on_user_turn_completed`	After each spoken turn, before the model replies	After each inbound message, before the model replies	`{{args.user_message}}` (text only; attached images are not included)

on_enter

The hook runs to completion before the greeting, so the greeting and prompt can read {{userdata.…}} values it just published. Its latency delays the agent’s first word — open the tree with a say if the lookup is slow. After the hook, the agent speaks its greeting; an agent reached by a handoff with no greeting generates an opening line (using the handoff’s instructions) unless the hook already ran generate_reply. If the hook hands off or hangs up, no opening line is spoken.

on_exit

For logging outcomes, posting leads, writing CRM notes. A failure is logged and never affects the caller. On text, what the hook says is saved to the chat (and sent on Telegram or WhatsApp); a chat nobody ends never runs it.

on_user_turn_completed

Runs between the caller finishing and the agent replying — keep it fast. Ending the call or handing off inside it suppresses this agent’s reply (the target answers instead). A hook that fails is logged and the turn continues. With screen share on, the newest frame is already in context when it runs.

Where hooks are refused

Refusal	Why	Fix
`on_user_turn_completed` on a realtime agent	The model detects turns itself; the hook would never run	Remove it, or use the cascade
A hook tool containing a `transfer` operation: `the 'on_enter' hook cannot use tool '…': it contains a transfer`	A hook runs outside a turn	Attach it as a normal tool
A hook tool reading `{{args.x}}` it is not given (anything on `on_enter`/`on_exit`; anything but `user_message` on `on_user_turn_completed`)	No model fills a hook’s arguments	Read `{{userdata.…}}`, `{{vars.…}}` or `{{system_vars.…}}`

All other operations work in hooks. A keypad entry does not fire on_user_turn_completed.

Example: load a CRM record on enter

{
  "name": "load_customer",
  "description": "Look up the caller in the CRM before the agent greets them.",
  "json_schema": {},
  "operations": [
    {
      "kind": "http",
      "config": {
        "method": "GET",
        "url": "https://crm.example.com/customers/by-phone",
        "query": { "phone": "{{system_vars.human_phone_number}}" },
        "headers": { "Authorization": "Bearer {{secrets.CRM_TOKEN}}" },
        "timeout": 5
      },
      "on_error": "continue",
      "publish_fields": [
        { "path": "customer.name", "key": "name", "store": "userdata" },
        { "path": "customer.plan", "key": "tier", "store": "userdata" }
      ]
    }
  ]
}

on_error: "continue" leaves a thinner prompt instead of a failed call when the CRM is down. Tell the prompt to ask rather than guess when a field is blank, and keep fields the lookup might miss out of the greeting (see userdata). For on_user_turn_completed, the tool’s own json_schema must declare user_message as a string parameter, or the tool will not publish.

Operation tree

What a hook tool’s tree can contain.

Userdata

What a hook publishes and who reads it.

Get started

Build

Guides

Lifecycle hooks

When each fires

on_enter

on_exit

on_user_turn_completed

Where hooks are refused

Example: load a CRM record on enter

Next

Operation tree

Userdata

​When each fires

​on_enter

​on_exit

​on_user_turn_completed

​Where hooks are refused

​Example: load a CRM record on enter

​Next

Operation tree

Userdata

When each fires

on_enter

on_exit

on_user_turn_completed

Where hooks are refused

Example: load a CRM record on enter

Next