WhatsApp

VirtuAI connects to WhatsApp through Twilio. Twilio receives each message and forwards it to your agent’s webhook. The agent then replies through Twilio from your WhatsApp sender number.

Before you start

• A workspace role that can edit Settings and Agents
• A Twilio account with a WhatsApp sender approved for your number
• An agent already created in VirtuAI. See Create your first agent.

1. Add your Twilio credentials

In Settings, in the same workspace as the agent, set:

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN

Both are on your Twilio Console dashboard.

2. Choose the sender number

1. Open Telephony > Messaging.
2. Select Fetch Phone Numbers. VirtuAI lists the numbers in your Twilio account.
3. Under WhatsApp-Capable Numbers, select Set as WhatsApp Number on the number that is your WhatsApp sender.

The page then shows it as the Active WhatsApp Number. It’s saved as TWILIO_WHATSAPP_NUMBER in Settings, and every agent in the workspace replies from it.

Note

The list shows every SMS-capable number in the account. VirtuAI can’t tell which of them Twilio approved for WhatsApp, so pick the one you registered as a WhatsApp sender.

3. Turn on WhatsApp for the agent

Edit the agent. In Channels, turn on WhatsApp. In AI Model Configuration, choose the model, then save.

4. Copy the webhook URL

In the agent’s Integration URLs, copy WhatsApp Webhook. It looks like this and belongs to this agent only:

https://<your-virtuai-host>/whatsapp/webhook/<agent-id>

To put a different agent on another WhatsApp number, point that number’s webhook at the other agent’s URL.

5. Set the webhook in Twilio

In Twilio, open your WhatsApp sender’s configuration. Paste the URL as the webhook for incoming messages, keep the method as HTTP POST, and save.

Paste the URL exactly as Integration URLs shows it, with nothing added or changed. Twilio signs each request using that URL, and VirtuAI checks the signature against the same address.

6. How VirtuAI verifies Twilio

Twilio signs every webhook request with the auth token of the Twilio account that owns the number, and sends the signature in the X-Twilio-Signature header. VirtuAI checks that signature on every message and rejects with 403 any request that isn’t signed correctly.

For the check to pass:

• The webhook URL in Twilio must be exactly the WhatsApp Webhook URL from the agent’s Integration URLs.
• TWILIO_AUTH_TOKEN in Settings must be the auth token of the Twilio account that owns the WhatsApp number. If you rotate the auth token in Twilio, update it in Settings too.

WhatsApp doesn’t use integration keys: the Twilio signature replaces them, and Key Enforcement doesn’t affect WhatsApp.

7. Test

1. Send a greeting from WhatsApp to your number.
2. Ask a real product or support question.
3. Send a long question, and check that a long answer arrives complete.
4. Check that the conversation appears in Conversations.

How messages behave

• Each phone number has one ongoing conversation with the agent, so the agent remembers earlier messages from the same person.
• The agent answers in a single reply. There is no typing indicator or progress message while it works.
• Replies longer than 1,600 characters arrive as several WhatsApp messages, in order.
• Only text is handled. Photos, audio and other media aren’t processed. A message with media gets a short fixed reply saying so.

Troubleshooting

No reply in WhatsApp : Check TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN, and the Active WhatsApp Number under Telephony > Messaging. Check that Twilio’s webhook points at this agent’s URL.

Twilio’s debugger shows the webhook failing with 403 : VirtuAI couldn’t verify Twilio’s signature. Either the webhook URL in Twilio differs from the WhatsApp Webhook URL in Integration URLs (check the scheme, host and agent ID, and that nothing was added to it), or TWILIO_AUTH_TOKEN in Settings isn’t the auth token of the Twilio account that owns the number. Copy both again and save.

Twilio shows the webhook call succeeded, but no reply arrives : VirtuAI accepts the message first and replies separately. A missing or wrong credential or sender number makes the reply fail. Recheck steps 1 and 2.

A credentials error on the Messaging page : Add TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN in Settings for this workspace.

The wrong agent replies : The webhook in Twilio has another agent’s ID. Copy it again from the right agent’s Integration URLs.