Call events to your server
An agent can post chosen events to your server while each call runs: the call starting, what the caller says, what the agent replies, a tool’s result, situations starting and ending, the call ending. Your server can answer any event with actions: start a situation, add context, change the agent’s instructions, make it speak, transfer or end the call.
Studio never waits for your answer. The call carries on, and your reply’s actions are applied when it arrives.
Call events need an agent where jambonz runs speech-to-text, the language model and text-to-speech (a cascaded voice pipeline). An agent with any other engine can’t publish with call events chosen.
Turning them on
In the agent builder, open Situations. Under Call events to your server:
- URL: your server’s endpoint, a public
httpsURL. - Events: the events to post. Nothing is posted until you choose at least one.
An agent with events chosen and no URL won’t publish. Test calls from the builder post events too.
The events
user_transcript and llm_response post once per turn and send the conversation’s text to your server. Choose them
only if your server needs it.
The request
Each event is a POST with a JSON body:
Headers:
Verifying the signature
Events are signed exactly as the result webhook is, with the agent’s
same signing secret (starting whsec_):
Verify the raw body exactly as received, and reject a request whose t is more than a few minutes from your clock.
The result webhook page has the code, and shows where to reveal and
rotate the secret. Studio creates the secret when you publish the agent, or start a test call, with events chosen.
Your reply
Answer within 3 seconds with a 2xx status. The body can be:
- empty: nothing happens;
- a JSON object with
actions: Studio applies them to the call;
- any other JSON: ignored.
Replies are applied in the order they arrive. The actions page lists every action, and the per-call limits on actions from replies.
Keep your handler fast. The agent doesn’t wait for you, so a slow reply lands later in the conversation than the event it answers: by the time a reply to Caller speaks arrives, the agent may already be answering the caller.
Delivery
- No retries. An event is posted once. A retried event would arrive too late to be useful.
- 3-second timeout. No answer within 3 seconds is a failed delivery.
- No redirects. A
3xxanswer is a failed delivery. - At most 8 deliveries at a time per call. An event over that is not sent, and is recorded as failed.
- Replies up to 64 KB.
- Paused after 3 failures in a row. The call stops posting events for the rest of the call. A successful delivery resets the count. The next call starts again.
Studio doesn’t post to private network addresses, or to names that resolve to them.
When a delivery fails
Each failure is on the call’s timeline in Calls as Event webhook failed, with the event and the reason:
When the call stops posting, the timeline shows Event webhook paused.
Example
A billing agent tells the caller when their payment lands, using knowledge the model can’t have:
-
Choose Caller speaks and Call ends.
-
On
user_transcript, look the caller up bycall_sid. If they ask about a payment and it has arrived, reply: -
On
call_end, stop watching for the call’s payments.
If the payment arrives later in the call, push the same actions when it does.
Next
- Actions: everything a reply can do
- Pushing into a live call: acting on a call without waiting for an event