Tool call

When a voice agent uses one of its tools, we send a POST to the tool’s endpoint.

POST /agent/orders HTTP/1.1
Host: api.acme.com
Content-Type: application/json
Authorization: Bearer your-endpoint-token
webhook-id: msg_2b7f9c1e-…
webhook-timestamp: 1793010428
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"tool":"get_order_status","arguments":{"order_number":"A1234"},"call":{"id":"8b0c6c5e-…","agentId":"3f1e2d4a-…"}}

Headers

Header	Description
`Content-Type`	`application/json`
Your tool’s headers	The headers you set on the tool, such as `Authorization`
`webhook-id`	A unique ID for this request
`webhook-timestamp`	When it was sent, in seconds since the epoch
`webhook-signature`	`v1,` followed by the signature. See Verify signatures.

Headers you set that start with webhook- are dropped, so they can’t stand in for the signature.

Body

string

required

The tool’s function name.

object

required

The arguments the agent collected, shaped by the tool’s JSON Schema. If the model’s arguments aren’t valid JSON, this is the raw string.

object

required

Show properties

string

The call’s ID. The same as call.id in the post-call webhook, and the Call ID in the dashboard.

string

The voice agent’s ID.

Your response

Reply within 10 seconds, with any content type. The body is what the agent learns:

Response	The agent gets
`2xx` with a body	The body, up to its first 8,000 characters
`2xx` with an empty body	`Done.`
`4xx` or `5xx`	`{"error": "The tool failed (HTTP <status>).", "response": "<your body>"}`
Timeout or network error	An error telling it to say it can’t do that right now

The agent may call several tools at once; each is a separate request.

Overview

Realtime avatar API

Private agent links

Requests we send you

Headers

Body

Your response

​Headers

​Body

​Your response

Headers

Body

Your response