In this tutorial we'll walk through how to send WhatsApp notifications through Knock's Twilio channel using Twilio's Programmable Messaging API. Twilio manages the WhatsApp Business API relationship on your behalf, so you skip creating the Facebook business app that Knock's WhatsApp chat channel requires. You manage your WhatsApp sender and message templates in Twilio.
Knock's Twilio channel sends SMS by default, but can be adapted for WhatsApp messages with minor adjustments:
- Recipient numbers and sender phone numbers need a
whatsapp: prefix, such as whatsapp:+1234567890.
- The message body comes from an approved Twilio content template, identified by a
ContentSid and populated with values from ContentVariables.
These changes are applied in your Knock channel settings and your workflow step templates. If you already send SMS through Twilio, your WhatsApp channel can use the same Twilio account and credentials.
Before you configure anything in Knock, you'll need a WhatsApp-enabled phone number registered with Twilio. There are two paths depending on your situation:
You'll also need at least one approved content template. Create and manage templates in the Twilio Content Template Builder. Copy your approved template's Content SID, which starts with HX, to use in your Knock workflow steps.
Create a Twilio channel
Create a new Twilio channel under Channels and sources in your Knock dashboard account settings. Use this channel only for WhatsApp, and send any Twilio SMS through a separate channel.
Configure the channel per environment with your Twilio Account ID and Auth token. Set From to the WhatsApp sender you registered with Twilio, either a phone number or a messaging service:
- Phone number. Enter your WhatsApp-enabled Twilio number. You'll add the
whatsapp: prefix in the next step.
- Messaging Service SID. Enter the SID of the Twilio messaging service that contains your WhatsApp sender.
To track message statuses in Knock, enable delivery status webhooks on the channel. In addition to the delivery events Twilio reports for SMS, WhatsApp sends read receipts, which Knock records as read. The FAQ below lists how each Twilio status maps to Knock.
Set payload overrides
Twilio requires the whatsapp: prefix on the recipient's number, and on the sender's number when From is a phone number.
In the environment's settings, expand Advanced and enter the appropriate override in Payload overrides:
To receive WhatsApp messages, recipients need a phone_number property in E.164 format, such as +1234567890. The To override adds the whatsapp: prefix to it at send time.
Set the content template ID
WhatsApp requires that business-initiated messages use a template approved by Meta. Set the template with a payload override on the workflow step rather than the channel, so templates can vary between workflows.
Open the workflow step that uses your WhatsApp Twilio channel and click the gear icon to open template settings. Add a payload override that sets the Content SID and the template's variables:
ContentVariables is a JSON string, and its keys are case-sensitive and must match the variable names your Twilio content template defines.
- For a template with named variables such as
{{first_name}}, use those names as keys.
- For a template with positional variables such as
{{1}}, use numeric string keys: "1", "2", and so on.
Values accept Liquid, so you can populate them from your workflow's trigger data as shown in the example above.
Add an optional fallback
Content provided in the step's Body field may be used as a fallback. When the override includes a valid ContentSid, Twilio ignores the body and builds the message from your content template and ContentVariables. When ContentSid is missing, Twilio sends the body as written, or rejects the message if the body is blank.
Manage user preferences
Knock treats this channel as an SMS channel, so a recipient's SMS preferences also apply to their WhatsApp messages. A recipient who opts out of SMS also stops receiving WhatsApp. To let recipients manage WhatsApp separately, set preferences by channel rather than channel type.
Frequently asked questions
#