Pushing into a live call
A tool’s result and a call event’s reply both answer something Studio asked. A push is your server speaking first: a payment lands, an order ships, a fraud check comes back, and the agent should know now.
A self-hosted Studio takes the same request at its own address.
Pushes need an agent where jambonz runs speech-to-text, the language model and text-to-speech (a
cascaded voice pipeline). On other agents every action except
end_call is refused.
Authentication
A push is authenticated with a Studio API key, sent as a bearer token:
A key works for any call in its account, whichever agent is on it.
The request
POST /v1/calls/{call_sid}/actions
call_sidis the jambonz call id. Your server gets it in:- every call event (
call_sid); - every tool request (the
X-Studio-Call-Sidheader); - the result webhook, after the call.
- every call event (
- The body is a JSON object with one field,
actions, at most 16 KB. The actions page lists them all.
The response
202 Accepted means Studio has handed the actions to the call:
It doesn’t mean every action was applied. Each one is checked on the call: an unknown action, a situation the agent doesn’t have, or an action over the call’s limits is refused there. Every action, applied or refused, is on the call’s timeline in Calls, as by a push from your server.
Errors
Errors have the usual Studio shape:
Limits
Example
A collections agent waits on the caller’s bank transfer:
-
The agent has a situation,
payment_received, set to Only your server, with instructions to thank the caller, read back the reference and close the account. -
When the payment system confirms the transfer, it pushes:
-
The agent picks up the situation’s instructions and tells the caller straight away, even mid-silence.