Inbound call & SMS webhook

​

Where to set the inbound webhook URL

1. Open the Retell dashboard and go to the Phone Numbers page.
2. Click the number you want to configure.
3. In the number’s settings, set the Inbound Webhook URL field to your endpoint.
4. Save the changes.

​

Use cases

• Filter and reject unwanted inbound calls / SMS
• Add context (dynamic variables, metadata) to inbound calls / SMS
• Override agent id / version / specific agent settings for inbound calls / SMS
• Pause the call / SMS to pick it up with some delay
• Internal system records of the inbound call / SMS

​

Webhook spec

​

Request payload

• agent_id: if the number has inbound agent id set, you will see it in payload
• agent_version: if the number has inbound agent version set, you will see it in payload
• from_number: this will always show up in payload, helps you identify the caller and process the call / SMS accordingly
• to_number: this will always show up in payload, helps you identify the receiver and process the call / SMS accordingly
• custom_sip_headers (inbound call only): an object containing custom SIP headers extracted from the inbound INVITE. Only headers whose name starts with X- (case-insensitive), plus the allowlisted headers User-to-User, Diversion, History-Info, and P-Asserted-Identity, are forwarded. Header names are emitted in lowercase. The object may be empty or omitted when no qualifying headers are present, so treat it as optional. Use this to pass per-call context from your SIP trunk into the webhook (for example, to programmatically manage sessions).

{
  "event": "call_inbound",
  "event_timestamp": 1780012672105,
  "call_inbound": {
    "agent_id": "agent_12345",
    "agent_version": 1,
    "from_number": "+12137771234",
    "to_number": "+12137771235",
    "custom_sip_headers": {
      "x-my-header": "my-value",
      "user-to-user": "616263;encoding=hex"
    }
  }
}

{
  "event": "chat_inbound",
  "chat_inbound": {
    "agent_id": "agent_12345",
    "agent_version": 1,
    "from_number": "+12137771234",
    "to_number": "+12137771235"
  }
}

​

Response

• reject: set to true to decline this inbound call / SMS. See Reject an inbound call or SMS below.
• override_agent_id: if you want to override the agent id, you can set it here
• override_agent_version: if you want to override the agent version, you can set it here
• dynamic_variables: if you want to set dynamic variables for this inbound call, you can set it here
• metadata: if you want to set metadata for this inbound call, you can set it here
• agent_override: if you want to override the agent settings.

​

Agent override

• agent: Partial Agent settings (voice agents). Useful fields include voice_id, voice_model, fallback_voice_ids, voice_temperature, voice_speed, volume, language, pronunciation_dictionary, boosted_keywords, stt_mode, vocab_specialization, denoising_mode, responsiveness, interruption_sensitivity, enable_backchannel, backchannel_frequency, backchannel_words, end_call_after_silence_ms, max_call_duration_ms, begin_message_delay_ms, ring_duration_ms, reminder_trigger_ms, reminder_max_count, ambient_sound, ambient_sound_volume, allow_user_dtmf, user_dtmf_options, voicemail_option, webhook_url, webhook_timeout_ms, data_storage_setting, opt_in_signed_url, pii_config, post_call_analysis_data, post_call_analysis_model.
• retell_llm: Partial Retell LLM settings. Supported keys include model, s2s_model, model_temperature, knowledge_base_ids, kb_config, start_speaker, begin_after_user_silence_ms, begin_message.
• conversation_flow: Partial Conversation Flow settings. Supported keys include model_choice, model_temperature, knowledge_base_ids, kb_config, start_speaker, begin_after_user_silence_ms, begin_message.

• If both override_agent_id/override_agent_version and agent_override are provided, we first resolve the target agent by id/version, then apply agent_override on top for this call.
• Overrides must satisfy the same validation rules as agent creation (e.g. voice/language compatibility, value ranges). Invalid overrides may cause the call to be rejected.
• Overrides do not persist back to the saved agent.

{
  "call_inbound": {
    "override_agent_id": "agent_12345",
    "override_agent_version": 1,
    "agent_override": {
      "agent": {
        "voice_id": "11labs-Adrian",
        "voice_temperature": 0.6,
        "interruption_sensitivity": 0.8,
        "max_call_duration_ms": 1800000
      },
      "retell_llm": {
        "model": "gpt-4o-mini",
        "model_temperature": 0.2,
        "knowledge_base_ids": ["kb_abc123"],
        "start_speaker": "agent",
        "begin_message": "Hi {{customer_name}}, thanks for calling."
      }
    },
    "dynamic_variables": {
        "customer_name": "John Doe"
    },
    "metadata": {
        "random_id": "12345"
    }
  }
}

​

Reject an inbound call or SMS

{
  "call_inbound": {
    "reject": true
  }
}

• Only the boolean true rejects. Any other value (including the strings "true" / "false", 1, or omitting the field) is ignored and the call / SMS proceeds as normal.
• Rejecting takes priority over agent selection — override_agent_id and agent_override are ignored when reject is true. We recommend returning only { "reject": true } when declining: other fields such as dynamic_variables and metadata are still validated, and an invalid value there is treated as a bad response, in which case reject is not applied.
• For calls, Retell hangs up before any agent or voice setup. No call object is created.
• For SMS, Retell drops the message without replying. No chat object is created.

​

FAQ