About inbound call webhooks

You can intercept, reroute and decline every incoming call with inbound call webhooks.

You will receive a JSON payload (event: "call_inbound") within 10 seconds after a call was initiated. Your endpoint will need to respond with an updated call_inbound object to assign an agent to the call or update the metadata.

What to expect

  • If your endpoint responds with an empty call_inbound object, the call will be disconnected.
  • If your endpoint doesn’t respond within timeout, the call is put on hold. Up to 3 more requests will be sent. If all these attempts fail, the call will be rerouted to the default_agent you specified. If you did not specify a default_agent, the call will be disconnected.

Requests

Every inbound call will generate and send a JSON in this format:

1{
2 "event": "call_inbound",
3 "call_inbound": {
4 "model_id": "optional_agent_id", // the default agent, if preconfigured by you
5 "from_number": "+12137771234", // the caller
6 "to_number": "+12137771235" // the receiving number
7 }
8}

Responses

Your endpoint needs to respond with an updated call_inbound object.

1{
2 "call_inbound": {
3 "override_model_id": "agent_67890", // reroute the call to a different agent
4 "custom_variables": { // context and data for further call flow
5 "customer_name": "John Doe"
6 },
7 "metadata": { // metadata for post-call analysis
8 "session_id": "abc123"
9 }
10 }
11}