Bulk Solutions / Retell AI - Inbound IP Based, Outbound Registration

How the integration works

Retell calls the two directions origination and termination. Each one is set up in a different place.

Shared SIP settings

Values to collect before you start

Have these ready from both portals. Replace the examples with your own numbers and agent.

Retell IP blocks

Retell publishes these ranges for its SIP traffic. You do not need to add them to Bulk for this setup, but they help when you read logs or set up a firewall.

Inbound setup (IP based)

Send calls that arrive on your Bulk DID to your Retell agent.

1. Point the Bulk DID at Retell

   In the Bulk Solutions portal:

   1. Interconnection → Host → Add the Retell SIP host: sip.retellai.com, port 5060. Use the hostname, not one resolved IP, because Retell's addresses can change.
   2. If your portal screen only accepts IPv4, contact Bulk support so we can attach the FQDN for you.
   3. Interconnection → Trunk Group → Add and assign that host to the trunk group.
   4. Inbound → DIDs → Manage and set your telephone number to that trunk group.
   5. Wait 2–3 minutes for the host and trunk group to reach all Bulk SBC nodes.

   Inbound calls are sent from one of our signaling IPs (see Portal -> Interconnection -> Interconnection Instructions) to sip.retellai.com with request URI 1NXXNXXXXXX (example 13105551000).

   Do not assign a Retell DID to a SIP registration trunk group. A registration trunk only delivers inbound calls to the IP that last registered, and Retell never registers.

2. Import the number into Retell

   Retell only answers calls for numbers it knows about. Do the import in the outbound steps below; one import covers both directions. Pick your agent under the inbound setting so calls are answered.

Outbound setup (registration credentials)

Give Retell the Bulk registration trunk username and password. Retell sends its INVITE to sip.bulkvs.com and answers our digest challenge. No REGISTER is sent, and no Retell IP addresses need to be added to your Bulk account.

1. Create a Bulk registration trunk group

   In the Bulk portal go to Interconnection → Trunk Group - Manage → SIP Registration Trunk Group → Create.

2. Copy the Bulk credentials

   Go to Interconnection → Trunk Group - Manage and open the registration trunk group. Copy the username and password. Keep them private; they authorize calls on your account.

3. Import the number in the Retell dashboard

   In Retell open Phone Numbers, click +, then Connect to your number via SIP trunking. Fill in the form like this:

   Retell field	What to enter
   Phone Number	+13105551000 (E.164: plus, country code, then the number with no spaces)
   Termination URI	sip.bulkvs.com
   Outbound Transport	UDP or TCP
   SIP Trunk User Name	YOUR_BULK_TRUNK_USERNAME
   SIP Trunk Password	YOUR_BULK_TRUNK_PASSWORD
   Nickname	Anything that helps you remember it

   Click Test SIP Connection. Retell sends a SIP OPTIONS to sip.bulkvs.com without placing a call. A 2xx answer means our proxy is reachable. Then click Save and bind your agent for inbound and outbound calls.

   When Bulk replies to an INVITE with a 401 or 407 challenge, Retell resends it with the username and password you entered.

4. Add the X-Challenge SIP header

   BulkVS needs every outbound INVITE from Retell to carry a custom SIP header named X-Challenge with the value 1. This header tells our switch to send the 401/407 digest challenge, so Retell can answer it with your trunk username and password. Without it, the call may be rejected before Retell ever gets asked for the password.

   In the dashboard, open Make Outbound Call on your imported number. Under Custom SIP Headers, click + Add, type X-Challenge in the X-Header-Name box and 1 in the Value box, then click Call.

   From the API, add the header to the call request with Retell's custom_sip_headers field (shown in the next step). Retell only allows outbound header names that start with X-, and X-Challenge follows that rule. See Retell's guide: Set custom SIP headers.

   Add the header on every outbound call you start, from the dashboard or the API.

5. Place a call from Retell

   Start a test call from the dashboard, or use Retell's create phone call API with your imported number as the caller. Save this as call.json; it already includes the X-Challenge header:

   Copy{
     "from_number": "+13105551000",
     "to_number": "+13105551212",
     "custom_sip_headers": {
       "X-Challenge": "1"
     }
   }

   Then send it to Retell:

   Copycurl -X POST https://api.retellai.com/v2/create-phone-call \
     -H "Authorization: Bearer YOUR_RETELL_API_KEY" \
     -H "Content-Type: application/json" \
     -d @call.json

   Bulk accepts destinations as 1NXXNXXXXXX@sip.bulkvs.com or NXXNXXXXXX@sip.bulkvs.com, and Retell's E.164 format works too.

Caller ID rules

The from number must be a number on your Bulk account in one of these formats. Any other caller ID format is rejected:

Import with the Retell API (optional)

The dashboard steps above do the same thing. Use this if you set numbers up from code.

Save this as import.json. The trunk fields go at the top level of the body:

Copy{
  "phone_number": "+13105551000",
  "termination_uri": "sip.bulkvs.com",
  "sip_trunk_auth_username": "YOUR_BULK_TRUNK_USERNAME",
  "sip_trunk_auth_password": "YOUR_BULK_TRUNK_PASSWORD",
  "transport": "UDP",
  "nickname": "Bulk Solutions main line",
  "inbound_agents": [
    { "agent_id": "YOUR_RETELL_AGENT_ID", "weight": 1 }
  ],
  "outbound_agents": [
    { "agent_id": "YOUR_RETELL_AGENT_ID", "weight": 1 }
  ]
}

Then send it to Retell:

Copycurl -X POST https://api.retellai.com/import-phone-number \
  -H "Authorization: Bearer YOUR_RETELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @import.json

phone_number and termination_uri are required. transport can be TCP, UDP, or TLS and defaults to TCP. Retell never shows the password again after you save it.

Test plan

Troubleshooting

Need help?

If you get stuck on either side, send us the DID, trunk group name, approximate call time, and a Call-ID. We can pull the SIP ladder from our network.

Related guide: LiveKit + BulkVS · BulkVS SIP trunking
Retell documentation for custom telephony: docs.retellai.com/deploy/custom-telephony · Retell custom SIP headers