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 (e.g. {} with no agent assignment), the call will be disconnected.
• If you return override_model_id as an empty string (""), the call continues with the agent that received the call (no reroute, no disconnect).
• 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 to another agent; use "" to keep the default 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
}