Connecting WhatsApp via Twilio
How the Pieces Fit Together
Setup has two levels, and it helps to know which is which before you start:
- A Connector lives at the Organization level. It holds your Twilio account details and the list of WhatsApp numbers you want to use. You set this up once.
- A Channel lives on an Agent. It binds one of your Connector's numbers to that Agent, so the Agent answers on it.
So the path is: build the Connector once, then hand a number to each Agent that needs one. Different Agents can answer on different numbers, all from the same Connector.
What You'll Need
WhatsApp runs on Twilio, and you bring your own Twilio account. We connect to it on your behalf, so a few things need to be in place first:
- A Twilio account. The account stays yours. We never create or own it.
- A WhatsApp sender approved in Twilio. The number you want to use must already be set up and approved for WhatsApp inside your Twilio account.
- Your Twilio credentials. We need your Account SID and Auth Token to connect. You'll find both in your Twilio console.
Step 1: Add a Twilio Connector
The Connector is what links us to your Twilio account and lets us find the WhatsApp numbers available to you.
- In the backoffice, open your Organization and go to Connectors.
- Click New connector, choose Twilio from the list, and click Continue.
- Give the Connector a Name you'll recognize later (for example, "Hotel Front Desk").
- Enter your Account SID (it starts with
AC) and your Auth Token. - Under Allow this connector to…, keep Receive inbound data turned on so the Agent gets guest messages. It's selected by default, so you can leave this as is.
- Click Create connector.
We test your credentials against Twilio right away. When they check out, the Connector shows as Active with a Connected health badge. If the credentials can't be verified, the Connector is saved in an Error state so you don't lose your setup. Just edit it, re-enter your details, and save again.
Note: Your Auth Token is a secret, just like a password. We store it securely and only use it to connect to your Twilio account.
Step 2: Activate Your WhatsApp Number
Once the Connector is connected, open it to see the numbers available in your Twilio account.
- On the Connector's detail page, find the Phone Numbers section. It lists the WhatsApp numbers and senders from your Twilio account.
- Check the box next to the number you want to use.
- Click Save. Only the numbers you check and save become active on the Connector.
Saving is what actually activates the number. A number has to be active before you can set its webhook, so always select it and save first, then move on to Step 3. You can activate more than one number here, and you'll assign each one to an Agent in Step 4.
Step 3: Set the Webhook
This is the step that makes incoming messages actually reach your Agent. A webhook is a URL Twilio calls every time a new message comes in. Point Twilio at us, and each guest message lands with your Agent.
Make sure the number is active first (selected and saved in Step 2), then click Set webhook next to it. Behind the scenes, we reach into your Twilio account, find the WhatsApp sender for that number, and write our webhook URL into it as its callback address. From that moment on, Twilio sends every message for that number straight to your Agent. We then check with Twilio to confirm the change took effect. When it's done, the number shows Webhook configured.
A few things worth knowing:
- Button greyed out? The Set webhook button only works on active numbers. Go back to Step 2, make sure the number is checked, and save.
- Prefer to do it yourself? The Connector detail page also shows an Inbound webhook URL. You can copy that and paste it as the inbound webhook for each number directly in your Twilio console instead.
- If a number shows "Webhook not set up in provider," messages won't reach your Agent yet. Click Set webhook again, or double-check the URL in Twilio.
Note: If you ever regenerate the webhook URL on the Connector, you'll need to set the webhook again for every number, or incoming messages will stop arriving.
Step 4: Add the Channel to Your Agent
With the Connector ready, hand a number to the Agent that should answer on it.
- Open the Agent you want to connect, and go to Channels.
- Click Add channel.
- Pick your Twilio Connector, then pick the Channel (the WhatsApp number) you want this Agent to use.
- Click Add channel to save.
The number now shows on the Agent's Channels page, labeled with the Connector it came from. Each number answers for one Agent, so numbers already bound elsewhere are marked Already bound and can't be double-booked.
To stop an Agent from answering on a number, remove the Channel here. That only unbinds the number from this Agent. Your Connector and its settings stay intact.
How It Works
Once everything is connected, the flow is simple:
- A guest sends a WhatsApp message to your number.
- Twilio forwards that message to the Agent bound to that number, through the webhook you set.
- The Agent reads the message and replies on the same WhatsApp number.
There's nothing for your team to do in the moment. The Agent handles each conversation on its own, the same way it does on web chat.
Why We Need Your Credentials
It's a fair question: why does answering a WhatsApp message require your Twilio credentials at all?
The short answer is that your Agent doesn't just read messages, it sends replies, and sending a reply requires your credentials. When a message arrives, Twilio gives us a very short window to respond. That window is far too short for the Agent to think through a good answer. So we acknowledge the message right away, then send the real reply a few seconds later, once the Agent has reasoned it out. That follow-up is a fresh message sent back through Twilio, and every message sent through Twilio has to be authenticated. Your Account SID and Auth Token are what prove the reply is really coming from your account.
Your credentials also let us connect to your account in the first place to find your approved WhatsApp numbers, so you can pick one during setup.
What's Next
With WhatsApp connected, round out your channels and make sure your Agent is ready for real guests:
- Integrating TrustYou Agent Web Chat -- add the Agent to your website as well, so guests can reach you everywhere
- Agent Settings to Review Before Going Live -- run through the pre-launch checklist before your first guest writes in
- What is TrustYou Agent? -- see all the Channels your Agent can work across
Comments
0 comments
Please sign in to leave a comment.