Connecting a Twilio Number (+ Fixing Error 22105)

Connecting a Twilio number to your Shopbell agent takes about five minutes — you create a telephony configuration, paste your Twilio Account SID and Auth Token, attach a phone number, and Shopbell pushes the inbound webhook URL to Twilio automatically. But on self-hosted deployments, Twilio sometimes rejects the webhook URL with error 22105. This guide walks through setup and the fix.

Step 1 — Get your Twilio credentials

Sign in to twilio.com. Click Console. On the top right, you will see your Account SID (starts with AC) and Auth Token (click show to reveal). Copy both. Treat the Auth Token like a password — anyone who has it can use your Twilio account.

Your Twilio account needs to be funded. New accounts get a small trial balance. When you are ready for production, add at least $20 in credits and upgrade from trial. Trial accounts add an automated 'this is a Twilio trial' message to every call — that disappears when you upgrade.

Step 2 — Create a Shopbell telephony configuration

In the Shopbell dashboard, click Telephony Configurations in the sidebar. Click New Configuration. Name it 'Sales Line' or whatever fits. Pick Twilio as the provider. Paste your Account SID and Auth Token. Click Save. The configuration is created with status Active.

Step 3 — Attach a phone number

Click the configuration you just created. Click Add Phone Number. You have two options: buy a new number through Twilio (Shopbell handles this for you via the API — pick the area code, click Buy), or attach an existing Twilio number you already own.

Once attached, Shopbell pushes the inbound webhook to Twilio for that number. The webhook URL is: https://app.shopbell.ai/api/v1/telephony/inbound/run. Twilio sends a POST to this URL every time someone calls the number. Shopbell's webhook responds with TwiML (Twilio Markup Language) that tells Twilio what to do — typically <Connect><Stream> to start a media stream to the agent.

Step 4 — Test the call

Call the Twilio number from your cell phone. You should hear the agent's greeting within one ring. Talk. The agent responds. Hang up. The transcript appears in the Recordings section of your dashboard within a few seconds.

If you hear 'this is a Twilio trial number' message, your account is in trial mode — upgrade and add credits. If you hear silence or a fast busy signal, see Troubleshooting.

Error 22105 — Invalid URL provided for VoiceUrl

Twilio error 22105 means the webhook URL Shopbell pushed to Twilio is not a public, valid HTTPS URL. The error message looks like:

{"code":22105,"message":"Invalid URL provided for VoiceUrl: http://api:8000/api/v1/telephony/inbound/run"}

The root cause on self-hosted deployments: the .env file on your server contains a stale override named BACKEND_API_ENDPOINT set to http://api:8000. That is the internal Docker container hostname — Twilio cannot reach it. To fix:

Fix on Vultr (or any self-hosted server): SSH into your server. Open /root/aiwebcall/.env. Delete the line starting with BACKEND_API_ENDPOINT. Delete the line starting with BACKEND_URL. Verify PUBLIC_BASE_URL is set to your real public domain, e.g. PUBLIC_BASE_URL=https://app.shopbell.ai. Save the file. Run cd /root/aiwebcall && docker compose up -d --force-recreate api. The API now derives the endpoint from PUBLIC_BASE_URL.

Finally, re-attach the Twilio number in the Shopbell dashboard so the corrected webhook URL gets pushed to Twilio. Or call the Twilio REST API directly to set the VoiceUrl on the number to https://app.shopbell.ai/api/v1/telephony/inbound/run with method POST.

Porting or forwarding your existing business number

Most businesses do not give customers a new phone number. They forward their existing business line to the Twilio number. Call your phone carrier (Comcast, AT&T, Verizon, etc.) and ask them to forward all incoming calls to your Twilio number. The forward is set at the carrier level — your customers keep dialing the same number they always have. You can turn off forwarding any time to take calls personally again.

You can also port your existing business number into Twilio. This takes 2-4 weeks and requires a Letter of Authorization and a recent bill from your current carrier. Porting is permanent. Forwarding is reversible. We recommend forwarding for most businesses — try Shopbell for a few weeks first, then port if you decide to keep it.

Frequently Asked Questions