https://retellai.com/?utm_source=discord&utm_medium=seo logo
Powered by
can you advise what we need to to do set up inboun...
# ❓・ai-evy-support
c
@AI Evy can you advise what we need to to do set up inbound calls in our app? im gonna provide a few question first
a
Thanks for tagging me @Client Nexus. I'll look through relevant sources and get back to you shortly.
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
​ To learn more, see the sources I considered: [[1] Inbound webhook](https://docs.retellai.com/features/inbound-call-webhook) [[2] Register Phone Call](https://docs.retellai.com/api-references/register-phone-call) ​
### Answer To set up inbound calls in your app, here's what you need: 1. Phone Number Configuration - Purchase or import a phone number through Retell with inbound capability [(1) ]() - Set an Inbound Call Agent on the phone number 2. Optional: Inbound Webhook If you want to customize behavior per call (use different agents, inject dynamic variables, filter calls) , you can enable an inbound webhook on your number. The webhook receives a 
POST
with payload like:
Copy code
json
{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": "agent_12345",
    "from_number": "+12137771234",
    "to_number": "+12137771235"
  }
}
Your server responds with options like 
override_agent_id
, 
dynamic_variables
, or 
metadata
. *3. Custom Telephony (SIP Trunking) * If using your own telephony provider, you'll need to register the call via the API using `registerPhoneCall`: [(2) ]()
Copy code
javascript
import Retell from 'retell-sdk';
const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
}) ;
const phoneCallResponse = await client.call.registerPhoneCall({
  agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
}) ;
Go ahead and share your questions—happy to help with specifics!
c
@AI Evy CURRENT SETUP: - Phone Numbers: Purchased via Retell API with retell_phone_number_id, stored in DB with assigned_agent_id, subaccount_id. Types: ai_only (Retell), manual (Twilio). - Agents: Synced to Retell with retell_agent_id, retell_llm_id. Webhook: retell-webhook-handler for tool calls. - Webhooks: retell-call-webhook (call lifecycle events), webhook-twilio (Twilio events, AI routing). - Campaigns table: has config JSON with callMode (ai_inbound, ai_outbound, human_outbound), phone_numbers array, agent_id. GOAL: Implement AI inbound campaigns where: 1. Phone number is assigned to campaign (1 number = 1 campaign at a time, or routing by time) 2. When call comes in, route to campaign's AI agent 3. Two time-based steps: Business Hours (Agent A) + After Hours (Agent B) 4. Create/update contact from caller phone, track in campaign_leads table 5. Metrics: calls received, pickup rate, goal achieved QUESTIONS: 1. How do we configure a Retell phone number to route inbound calls to specific agents based on time of day? 2. Does Retell support scheduling/business hours routing natively, or do we handle this in our webhook? 3. When inbound call arrives, what webhook/endpoint does Retell call? Can we pass campaign context? 4. Can we dynamically change which agent handles a phone number, or must we use our webhook to route? 5. For caller ID lookup before call connects, can we inject contact data into agent context via dynamic variables?
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer Here are answers to your questions: 1. Time-based routing to specific agents Retell does not natively support scheduling/business hours routing. You handle this in your inbound webhook. [(1) ]() When a call arrives, your webhook receives the payload, and you return 
override_agent_id
based on your own time-of-day logic. 2. Business hours routing You define your business hours in your own system and configure routing rules in your webhook handler. [(2) ]() The inbound webhook lets you return different 
override_agent_id
values (Agent A vs Agent B) based on the current time. [(1) ]() 3. Webhook endpoint and campaign context When an inbound call arrives, Retell `POST`s to the inbound webhook URL configured on your phone number. The payload includes:
Copy code
json
{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": "agent_12345",
    "from_number": "+12137771234",
    "to_number": "+12137771235"
  }
}
You can pass campaign context by returning 
metadata
in your webhook response—this is stored with the call for your tracking purposes. 4. Dynamically changing which agent handles a number Yes. Your webhook response can include 
override_agent_id
to route to any agent dynamically per-call, without changing the phone number's default inbound agent. 5. Injecting contact data via dynamic variables Yes. Before the call connects, your webhook can look up the caller by 
from_number
, then return 
dynamic_variables
in your response to inject contact data (e.g., 
{{customer_name}}
) into the agent's prompt. Example webhook response:
Copy code
json
{
  "call_inbound": {
    "override_agent_id": "agent_after_hours",
    "dynamic_variables": {
      "customer_name": "John Doe"
    },
    "metadata": {
      "campaign_id": "camp_123"
    }
  }
}
​ To learn more, see the sources I considered: [[1] Inbound webhook](https://docs.retellai.com/features/inbound-call-webhook) [[2] Call Routing & Overflow Management with AI | Retell AI](https://www.retellai.com/blog/managing-overflow-calls-and-after-hours-routing-with-retell) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy SPECIFIC IMPLEMENTATION QUESTIONS: ROUTING: - We want Campaign A (phone +1234567890) → Agent X during 9am-5pm, Agent Y after hours - Is this best handled via: (a) Retell native config, (b) our webhook deciding agent, (c) updating retell_agent_id on phone number dynamically? CALLER CONTEXT: - When call starts, we need to lookup caller phone in our DB - If existing contact: inject their name, notes, previous calls into agent context - How do we pass this dynamic data? Via begin_call webhook response? Dynamic variables? WEBHOOK FLOW: - What's the exact webhook sequence for inbound call? - Can we intercept before call connects to decide agent and pass context? LEAD CREATION: - We create contact from caller phone number on call start - Track call in campaign_leads with campaign_id - This happens in our webhook - just confirming this is correct approach CURRENT WEBHOOK: retell-call-webhook handles: call_started, call_ended, call_analyzed We also have retell-webhook-handler for agent tool calls during conversation.
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer --- ### ROUTING Best approach: (b) Your webhook deciding agent. [(1) ]() Retell does not have native time-based routing. Use the inbound webhook to implement your business hours logic. When a call arrives, your webhook receives 
from_number
and 
to_number
, and you return 
override_agent_id
based on current time. Option (c) —updating the phone number's 
inbound_agent_id
dynamically via API—would work but adds latency and complexity compared to simply returning 
override_agent_id
per call. [(2) ]() --- ### CALLER CONTEXT Pass dynamic data via the inbound webhook response using 
dynamic_variables
. [(1) ]() When your webhook receives the inbound call payload, look up the caller by 
from_number
in your DB, then return:
Copy code
json
{
  "call_inbound": {
    "override_agent_id": "agent_12345",
    "dynamic_variables": {
      "customer_name": "John Doe"
    },
    "metadata": {
      "campaign_id": "camp_123"
    }
  }
}
The 
dynamic_variables
inject into your agent's prompt (e.g., 
{{customer_name}}
) , and 
metadata
is stored with the call for your tracking. --- ### WEBHOOK FLOW Exact sequence for inbound calls: 1. Call arrives at your Retell phone number 2. Retell `POST`s to your inbound webhook URL (configured on the phone number) with payload:
Copy code
json
{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": "agent_12345",
    "agent_version": 1,
    "from_number": "+12137771234",
    "to_number": "+12137771235"
  }
}
3. Your webhook responds with 
override_agent_id
, 
dynamic_variables
, 
metadata
, etc. 4. Call connects to the specified agent 5. Your existing 
call_started
, 
call_ended
, 
call_analyzed
webhooks fire at those lifecycle points [(3) ]() **Yes, you can intercept before the call connects**—the inbound webhook fires before connection, giving you time to decide the agent and pass context. [(1) ]() While waiting for your webhook response, the call stays in ringing state. --- ### LEAD CREATION Your approach is correct. Use the inbound webhook to: , [(4) ]() 1. Look up caller by 
from_number
2. Create/update contact in your DB 3. Return 
metadata
with 
campaign_id
for tracking 4. Track the call in 
campaign_leads
using data from 
call_ended
or 
call_analyzed
webhooks This pattern is commonly used—fetch caller info from your CRM using the inbound webhook, inject as variables, and track via metadata. ---
​ To learn more, see the sources I considered: [[1] Inbound webhook](https://docs.retellai.com/features/inbound-call-webhook) [[2] Update Phone Number](https://docs.retellai.com/api-references/update-phone-number) [[3] Receive calls](https://docs.retellai.com/deploy/inbound-call) [[4] Discord message from @katecardenas_67927 on 2025-09-17](https://discord.com/channels/1186424376300679209/1186462578310910112/1417939440860528783) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
c
@AI Evy Is the webhook URL configured on the phone number or in Retell dashboard? Currently we're setting VoiceUrl on Twilio phone number → but Retell phone numbers have their own inbound_webhook_url setting. We need to confirm which one is used. Do Retell phone numbers automatically call webhooks or does Twilio forward to Retell? If using Retell's phone number infrastructure, the webhook URL should be set via Retell API, not Twilio.
a
### Answer ### Answer For Retell-managed phone numbers (
retell-twilio
or 
retell-telnyx
) : The webhook URL is configured on the phone number via Retell's API, not through Twilio directly. [(1) ]() When you create or update a phone number through Retell, you set the 
inbound_webhook_url
field:
Copy code
javascript
inbound_webhook_url: "<https://example.com/inbound-webhook%22>
, [(2) ]() This is the URL Retell will 
POST
to when an inbound call arrives. [(1) ]() How it works: - Retell phone numbers automatically handle the telephony layer—Retell receives the call and triggers your 
inbound_webhook_url
before connecting. - You do not configure Twilio's 
VoiceUrl
for Retell-managed numbers. Retell handles that routing internally. For custom telephony (your own Twilio SIP trunk) : If you imported a phone number via custom telephony, you configure the 
termination_uri
and optionally 
inbound_webhook_url
through Retell's Import Phone Number API. [(3) ]() Summary: - Retell phone numbers → set 
inbound_webhook_url
via Retell API [(1) ]() - Retell handles the call routing; Twilio's 
VoiceUrl
is not used for Retell-managed numbers
​ To learn more, see the sources I considered: [[1] Update Phone Number](https://docs.retellai.com/api-references/update-phone-number) [[2] Create Phone Number](https://docs.retellai.com/api-references/create-phone-number) [[3] Import Phone Number](https://docs.retellai.com/api-references/import-phone-number) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
c
@AI Evy 1. Inbound Webhook URL Setup: When we set inbound_webhook_url via PATCH /update-phone-number/{phone_number_id}, does Retell call this webhook before connecting the call (giving us time to return override_agent_id and dynamic_variables)? 2. Response Format Verification: Is this the correct response format? { "call_inbound": { "override_agent_id": "retell_agent_abc123", "dynamic_variables": { "customer_name": "John Doe", "previous_calls_count": "3" }, "metadata": { "campaign_id": "uuid", "contact_id": "uuid" } } } 3. Agent Override vs Override Agent ID: We're using override_agent_id to switch between business hours and after-hours agents. Is this the correct approach, or should we use agent_override.retell_llm.begin_message to customize the greeting instead? 4. Metadata Persistence: The metadata we return in the webhook response - is it automatically included in the call_ended webhook event so we can track which campaign/contact the call was for? 5. Webhook Timeout: What is the timeout for the inbound webhook response? Our webhook does database lookups which typically take 200-500ms.
a
Thanks for the follow-up, @Client Nexus. I'll get back to you soon.
### Answer ### 1. Inbound Webhook URL Setup Yes. When you set 
inbound_webhook_url
via the Update Phone Number API, Retell calls this webhook before connecting the call. [(1) ]() The call stays in ringing state while waiting for your webhook response, giving you time to return 
override_agent_id
and 
dynamic_variables
. ### 2. Response Format Verification Yes, your format is correct. Here's the documented structure:
Copy code
json
{
  "call_inbound": {
    "override_agent_id": "agent_12345",
    "override_agent_version": 1,
    "dynamic_variables": {
      "customer_name": "John Doe"
    },
    "metadata": {
      "random_id": "12345"
    }
  }
}
All fields are optional. ### 3. Agent Override vs Override Agent ID Both approaches are valid for different use cases: - **`override_agent_id`**: Use this to switch between entirely different agents (e.g., business hours Agent A vs after-hours Agent B) . This is the correct approach for your time-based routing. - **`agent_override`**: Use this to modify specific settings of the current agent without switching agents entirely—for example, changing 
begin_message
, 
voice_id
, or 
model_temperature
for a single call. If your business hours and after-hours agents have different prompts, voices, or tools, use 
override_agent_id
. If they're the same agent with just a different greeting, you could use 
agent_override.retell_llm.begin_message
. ### 4. Metadata Persistence The 
metadata
field is stored with the call object for your tracking purposes. You can retrieve it later via the Get Call API. ### 5. Webhook Timeout The webhook has a timeout of 10 seconds. If no success status (2xx) is received within 10 seconds, the webhook will be retried up to 3 times. Your 200-500ms database lookups are well within this limit.
​ To learn more, see the sources I considered: [[1] Inbound webhook](https://docs.retellai.com/features/inbound-call-webhook) ​
Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.
PreviousNext
Powered by