Run a tool on call events

Use system invocation when a tool must run because an event occurred, not because the model decided to call it. You configure invocation on the attachment, so one tool can remain model-invoked elsewhere.

Model invocation and system invocation

Mode	Decision maker	Typical use
`model`	The large language model selects the tool from its instructions and arguments	Lookups and actions requested during the conversation
`system`	The call runtime matches a configured event	Logging, notifications, and deterministic follow-up work

Use system invocation for lifecycle work that must happen consistently. The model does not participate in the decision.

Supported events

Event	Runs when	Available for
`call_start`	The call session starts	API Request, Custom Code, Current date and time, User phone number
`first_user_message`	The first caller message is available	API Request, Custom Code, Current date and time, User phone number
`call_end`	The call ends	API Request, Current date and time, User phone number
`tool_succeeded`	A selected source attachment succeeds	API Request, Custom Code, Current date and time, User phone number
`tool_failed`	A selected source attachment fails	API Request, Custom Code, Current date and time, User phone number

Custom Code cannot run on call_end. MCP, Send SMS, and call-control tools do not support system invocation.

Configure the attachment

Select system invocation

On the tool attachment, select Run automatically in the Dashboard or set invocation to system in the API.

Choose the triggers

Add at least one event. For tool_succeeded or tool_failed, also select the source attachment. The API requires its attachment_id as source_attachment_id.

Map the arguments

Map each tool argument from a constant, a template, transcript messages, transcript text, or call context. Mark it required only when the tool cannot run without that value.

Test the event

Save the agent and place a test call that reaches the trigger. Confirm the execution status and arguments in the call details.

System attachment

{
  "attachment_id": "6c944f13-42dc-47e0-a11e-d55cf44ee633",
  "tool_id": "c5d52e6f-96a7-4f04-a99d-65562b9c9d52",
  "version": 2,
  "description": "Store the transcript when the call ends.",
  "invocation": "system",
  "system": {
    "triggers": [
      {
        "event": "call_end"
      }
    ],
    "arguments": [
      {
        "name": "transcript",
        "type": "transcript_text",
        "required": true,
        "description": "The complete call transcript as text.",
        "source": {
          "type": "transcript_text",
          "max_messages": 200
        }
      },
      {
        "name": "call_id",
        "type": "string",
        "required": true,
        "description": "The SLNG call identifier.",
        "source": {
          "type": "call_id"
        }
      }
    ]
  },
  "argument_overrides": {}
}

Add this object to tool_refs with the safe partial-update procedure in Attach a tool to an agent.

Available argument sources

Source	Value
Constant	A fixed JSON value
Template	Text built from inputs, runtime memory, or call context
Transcript messages	Structured transcript messages, optionally limited by count
Transcript text	Plain transcript text, optionally limited by count
Call context	`call_id`, `room_name`, `job_id`, `agent_id`, `agent_name`, `phone_number`, `first_user_message`, `trigger_event`, or `call_end_reason`

first_user_message is unavailable at call_start. call_end_reason is only available at call_end. phone_number is unavailable for web calls. Runtime memory is not populated for call_start or first_user_message.

Handle results and failures

The call record shows each system tool execution as succeeded, failed, or timed out. Use tool_succeeded and tool_failed triggers when one tool should start after a specific source attachment finishes. This creates an explicit chain and avoids relying on the model to coordinate the tools. If the source attachment fails, only a matching tool_failed trigger runs. Review the execution error and mapped arguments in the call details before retrying the workflow.

Get started

Regions

Execution layer

Agent Builder

Models

Integrate

Model invocation and system invocation

Supported events

Configure the attachment

Available argument sources

Handle results and failures

​Model invocation and system invocation

​Supported events

​Configure the attachment

​Available argument sources

​Handle results and failures

Model invocation and system invocation

Supported events

Configure the attachment

Available argument sources

Handle results and failures