Skip to navigation

Pushing into a live call

Send actions into a call when your system knows something the agent should act on, without waiting for the model or the caller.

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.

curl -X POST https://studio.jambonz.org/v1/calls/CALL_SID/actions \
-H "Authorization: Bearer stk_..." \
-H "Content-Type: application/json" \
-d '{"actions": {"situation": "payment_received", "generate_reply": true}}'

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:

Authorization: Bearer stk_...

A key works for any call in its account, whichever agent is on it.

The request

POST /v1/calls/{call_sid}/actions

  • call_sid is the jambonz call id. Your server gets it in:
  • The body is a JSON object with one field, actions, at most 16 KB. The actions page lists them all.
{
"actions": {
"situation": "payment_received",
"inject_context": "Payment of $240.00 received at 14:02, reference PAY-8812.",
"generate_reply": "Tell the caller their payment has arrived."
}
}

The response

202 Accepted means Studio has handed the actions to the call:

{ "accepted": true, "call_sid": "b2a9f6c1-4d0e-4a55-9a5e-2f1c0e7d8a31" }

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:

{ "error": { "code": "CALL_NOT_LIVE", "message": "The call has ended" } }
StatuscodeMeans
400VALIDATION_FAILEDthe body isn’t { "actions": { … } }
401API_KEY_INVALIDno key, a malformed key, or a key that doesn’t exist or has been revoked
404CALL_NOT_FOUNDno call with that id in the key’s account. A call in another account gets the same answer
409CALL_NOT_LIVEthe call has ended
413ACTIONS_TOO_LARGEactions is over 16 KB
429RATE_LIMITEDover a rate limit; details.retry_after_s says when to try again

Limits

Limit
requests per key60 a minute
requests per IP address120 a minute
actions per call, from pushes and call-event replies togethersee Actions › Limits

Example

A collections agent waits on the caller’s bank transfer:

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

  2. When the payment system confirms the transfer, it pushes:

    {
    "actions": {
    "situation": "payment_received",
    "inject_context": "Payment of $1,240.50 received, reference PAY-8812.",
    "generate_reply": true
    }
    }
  3. The agent picks up the situation’s instructions and tells the caller straight away, even mid-silence.

Next