Twilio Setup (WhatsApp + Voice)

Objective

Connect Twilio to Helios so your AI agents can send and receive WhatsApp messages and answer phone calls. You save your Twilio Account SID and Auth Token once in Integrations; Helios then reuses them for both WhatsApp numbers and voice calls. If you would rather not manage a Twilio account at all, Helios can provision a phone number for you directly (see Helios-provisioned numbers).

Access

• Sidebar -> Integrations; Route: /app/{tenant}/integrations (Twilio card)
• Sidebar -> WhatsApp; Route: /app/{tenant}/whatsapp (Connect New Number -> Twilio)
• Sidebar -> Voice Agents; Route: /app/{tenant}/voice-agents (Create Voice Agent -> phone number)
• Sidebar -> Phone Numbers; Route: /app/{tenant}/phone-numbers (buy a Helios number)

Roles

Prerequisites

• An active Twilio account with access to the Twilio Console.
• Your Twilio Account SID (starts with AC, 34 characters) and Auth Token (32 characters).
• For WhatsApp: a Twilio number that is already registered as a WhatsApp Sender.
• For voice: a Twilio number with Voice capability, or a number bought through Helios.
• A verified email on your Helios account.

Two ways to use Twilio

Helios supports two models. You can mix them.

Step 1 - Save your Twilio credentials

Do this once. The same credentials are reused for WhatsApp and voice.

1. Open /app/{tenant}/integrations and find the Twilio (Voice & WhatsApp) card.
2. To find your credentials: log in at console.twilio.com, open the Account Info panel on the dashboard, and copy the Account SID and Auth Token.
3. Paste both values into the card.
4. Click Save Twilio Credentials.

Helios stores both values encrypted. The Auth Token (not an API Key) is required because Helios uses it to verify that incoming webhook requests really come from Twilio. To disconnect later, open the same card and click Disconnect Twilio.

Step 2 - Connect a WhatsApp number (Twilio)

1. Open /app/{tenant}/whatsapp and click Connect New Number.
2. Choose the Twilio provider (the alternative is Meta Cloud API; see WhatsApp via Meta Cloud API).
3. If Twilio is not connected yet, enter your Account SID and Auth Token and click Connect Twilio Account. This saves the same credentials as Step 1.
4. Set a Display Name and pick the agent (or team) that will answer.
5. Under WhatsApp Phone Number, select a WhatsApp-enabled number from your Twilio account, or choose Enter number manually and type it as whatsapp:+[country code][phone number].
6. Copy the Webhook URL shown in the modal and configure it in Twilio (next).

Configure the WhatsApp webhook in Twilio

The modal shows the exact Webhook URL to use (it ends in /api/whatsapp/webhook). Copy it with the button, then in Twilio:

1. Go to Twilio Console > WhatsApp Senders.
2. Select your WhatsApp-enabled number.
3. In Endpoint Configuration, set:

If you do not have a WhatsApp Sender yet, follow the WhatsApp guide to register a number in Twilio and link it to your WhatsApp Business Account.

Step 3 - Connect a number for Voice

1. Open /app/{tenant}/voice-agents and start Create Voice Agent.
2. On the phone step, choose how to connect a number:

3. For Your own Twilio number: save Twilio (if not already connected), then select a number from your Twilio account or enter one manually in E.164 format (for example +15551234567).
4. Copy the Voice Webhook URL and Status Callback URL shown in the modal and configure them in Twilio (next).

Configure the voice webhook in Twilio

1. Go to Twilio Console > Active Numbers.
2. Select the phone number you are connecting.
3. In the Voice Configuration section, set:

After saving in Twilio, incoming calls to that number are routed to your voice agent automatically. If you use a Helios number instead, telephony and webhooks are handled for you and there is nothing to configure.

Helios-provisioned numbers (no Twilio account)

If you do not want to run Twilio yourself, buy a number directly through Helios and assign it to a voice agent.

1. Open /app/{tenant}/phone-numbers.
2. Click Buy a number.
3. Search by Area code and/or Contains (both optional). Only US numbers are available today.
4. Enter an Emergency address. US law requires an address on file for emergency (911) calls; it is used only for emergency dispatch and never shared with callers.
5. Review the monthly cost, accept the Phone Number Terms and Acceptable Use Policy, and confirm the purchase.
6. Assign the new number to a voice agent.

Notes:

• Searching is free for every plan. Purchasing requires a paid plan; if your plan grants no purchase slots, the wizard shows an upgrade link instead of a purchase button.
• Numbers are for inbound voice AI only. No spam or robocalls.
• Release a number from the list when you no longer need it. Releasing is immediate and cannot be undone; you would need to buy a new number to replace it.
• If your plan later includes fewer numbers than you own, you keep them all but cannot buy more until you release some or upgrade.
• If the buy flow shows "Phone numbers are not available yet", the feature is not enabled on your environment. It is rolling out gradually; contact support if you need it.

Webhook URLs reference

Always copy the exact URL from the relevant Helios modal (it uses your production domain). The path suffixes are:

Good practices

• Save Twilio once in Integrations; both WhatsApp and voice reuse it.
• Use the Copy buttons for webhook URLs instead of typing them by hand.
• Keep the Account SID and Auth Token accurate. If you rotate the Auth Token in Twilio, update it in Helios, or webhook signature checks will start failing.
• Prefer a Helios number for voice if you want zero webhook setup.
• Test with a real message or call after configuring the webhook.

Common errors

Related

• WhatsApp
• WhatsApp via Meta Cloud API
• Voice Agents
• Phone Numbers
• Integrations