WhatsApp Messaging

WhatsApp messaging lets your AI agents send and receive messages on WhatsApp through the same Twilio phone numbers you use for SMS. Inbound messages can trigger workflows, outbound actions can reach members who have opted in, and conversations appear in Chats alongside every other channel.

Shares SMS infrastructure. WhatsApp uses the same phone numbers, workflows, and chat pipeline as SMS. If you already know how Phone & Voice works, WhatsApp is a flag-flip away — with a few extra rules you need to know about.

Prerequisites

Before you can use WhatsApp, two things need to be in place:

1. The whatsapp feature must be enabled on your workspace. This is a workspace-level product feature controlled by your organization admin. If you don't see the WhatsApp toggle on your phone numbers, ask your admin to enable it.
2. A Twilio phone number approved for WhatsApp. Twilio provides two paths:
   • Sandbox — Use Twilio's shared sandbox number for development and internal testing. Members have to send the sandbox join code from their phone before the number will talk to them.
   • Production — Register your own Twilio number with WhatsApp Business through Twilio. You'll need a Meta Business account, a verified display name, and approval on any message templates you plan to send. Twilio's docs cover the full application flow.

Production WhatsApp numbers take days to approve, so start the Twilio registration early if you're planning a launch.

Enabling WhatsApp on a Phone Number

Once your workspace has the WhatsApp feature and you have a WhatsApp-approved Twilio number configured:

1. Go to Phone Numbers
2. Open the phone number you want to use for WhatsApp
3. Turn on the WhatsApp switch
4. Save

The number now accepts inbound WhatsApp messages and can send outbound WhatsApp messages via actions and agent tools. SMS and voice on the same number are unaffected — they keep working as before.

Phone Number Settings

WhatsApp reuses the SMS work mode, default workflow, brand name, and off-hours message on the phone number. You don't configure WhatsApp separately.

How Inbound WhatsApp Works

When a member sends a WhatsApp message to your number:

1. Twilio delivers the message to the same webhook used for SMS.
2. Gravity Rail detects the whatsapp: prefix Twilio adds to WhatsApp numbers and routes the message as WhatsApp.
3. The system checks that WhatsApp is enabled for the workspace and the number. If either is off, the message is rejected without being stored.
4. The phone number's Default Workflow runs, just like it does for SMS.
5. The AI reads the message and replies. The outbound reply is sent as WhatsApp back to the member.

Chats started from WhatsApp show up in Chats and carry a WhatsApp channel label so you can tell them apart from SMS.

Member Opt-In

WhatsApp has stricter opt-in rules than SMS — Meta requires members to have explicitly agreed to receive messages before you can message them from an automation.

Each member has a WhatsApp notification toggle that controls whether outbound WhatsApp actions and agent tools will message them:

• Enabled — Actions and agents can send WhatsApp messages to this member.
• Disabled (default) — WhatsApp sends skip this member.

This toggle is separate from SMS, email, and voice. A member can be on for SMS and off for WhatsApp, or the other way around. You can change it from the member's edit form (alongside SMS, Email, and Voice) or via the Members API.

For the full preferences flow, see Notification Preferences.

Inbound messages are not gated by this toggle — if a member WhatsApps your number on their own, the default workflow still runs. The toggle only gates outbound-initiated sends.

Sending WhatsApp Messages

There are two ways to send WhatsApp messages from an automation, plus one for agent tools:

1. Send WhatsApp Action (Event Rules)

Use the Send WhatsApp event rule action to message a specific member when something happens in your workspace (task entered, form submitted, schedule fired, etc.).

You configure:

• Phone Number — The workspace number to send from (must have WhatsApp enabled).
• Message Template — A Jinja2-style message body with template variables like {{member.first_name}}. Required for one-off sends.
• Workflow (optional) — If provided, the action creates a WhatsApp chat with this workflow instead of sending a single message. The AI then handles replies.
• Initial Message (optional) — The first user message in the workflow chat.

Before sending, the action checks:

1. The workspace has the WhatsApp feature enabled.
2. The phone number has WhatsApp turned on and isn't archived.
3. The target member has WhatsApp notifications enabled (notify_whatsapp).

If any check fails, the action logs a skip reason and doesn't send.

2. From a Workflow's Default Workflow

Any number with WhatsApp enabled automatically routes inbound WhatsApp messages through the phone number's Default Workflow. Replies from the AI go out as WhatsApp.

3. Agent Ability: send_whatsapp_message

When your workspace has the WhatsApp feature enabled, agents can use the Send WhatsApp ability. Add it to an agent's abilities and the agent gains a send_whatsapp_message(message) tool that sends WhatsApp to the current member in the conversation.

This ability is only registered when the WhatsApp feature is on. If it's off, the agent won't see the tool.

Template Messages and the 24-Hour Window

WhatsApp has two rules you need to understand:

The 24-Hour Customer Service Window

Once a member messages you, you have 24 hours to reply with free-form text. After 24 hours of inactivity, WhatsApp requires any outbound message from you to use a pre-approved template — a message body Meta has reviewed and approved in advance.

What this means in practice:

• Inside the window — You can send anything. Default workflow replies, agent messages, ad-hoc outbound — all fine.
• Outside the window — Twilio will reject free-form outbound sends. You need to start the conversation with an approved template.

Gravity Rail sends your messages verbatim to Twilio. If you're sending a template, the message body you pass must match an approved template exactly. Unapproved or off-template messages sent outside the 24-hour window will be rejected by Twilio with a delivery failure.

Template Approval

To send a template, you first get it approved in your Meta Business account via Twilio's console. Approval can take anywhere from a few minutes to a few days. Templates are tied to your WhatsApp Business Account, not to Gravity Rail.

Tip for development. When you're testing in the Twilio WhatsApp sandbox, the sandbox reloads its 24-hour window every time you send a join code, so you can iterate freely without template approvals. Production numbers don't get that flexibility.

Opt-Out

Members can opt out of WhatsApp the same way they opt out of SMS — by replying STOP to your workspace number. This opt-out is handled by the same keyword pipeline that processes SMS STOP messages and marks the member as opted out at the account level.

You can also flip an individual member's WhatsApp notification toggle off from the Members edit form or via the API.

Limitations and Gotchas

• Feature flag required. If the whatsapp feature isn't on for your workspace, inbound WhatsApp messages are rejected and the WhatsApp toggle won't appear on phone numbers.
• Opt-in is off by default. New members have WhatsApp disabled on their notification preferences. Outbound actions will skip them until you turn it on.
• No media support today. WhatsApp supports images, documents, and voice notes on the protocol level, but the current integration focuses on text. Treat inbound media as something the AI won't be able to read.
• Shared workflow with SMS. Inbound WhatsApp and inbound SMS run the same default workflow. If you want channel-specific behavior inside the workflow, branch on the chat's channel using a CEL expression.
• Twilio costs differ. WhatsApp messages are billed separately from SMS in Twilio. Check Twilio's WhatsApp pricing before rolling out broadcasts.
• Template-only outside 24h. Outbound sends to members who haven't messaged you recently must use an approved template, or Twilio will reject them.

Troubleshooting

Inbound WhatsApp messages aren't triggering a workflow

1. Confirm the workspace has the WhatsApp feature enabled (ask your org admin if unsure).
2. Open the phone number and confirm WhatsApp is turned on.
3. Confirm the number has a Default Workflow set — WhatsApp uses the same default as SMS.
4. Confirm the number is WhatsApp-approved in Twilio. Numbers not registered with WhatsApp Business won't receive WhatsApp messages at all.

Outbound WhatsApp actions are skipping members

Send WhatsApp actions skip a member for three common reasons, visible in the action's run logs:

• Workspace feature disabled — Skipped with "Workspace does not have WhatsApp feature enabled."
• Member opted out — Skipped with "Member has WhatsApp notifications disabled." Flip the member's WhatsApp notification toggle on.
• Phone number not WhatsApp-enabled — Action fails with "Phone number does not have WhatsApp enabled." Turn on WhatsApp on the phone number.

Twilio reports delivery failures

If Twilio accepts the send but WhatsApp returns a failure, the most common causes are:

• Sending free-form text after the 24-hour window — use an approved template.
• The template body doesn't match the approved template exactly.
• The recipient hasn't joined your Twilio sandbox (sandbox numbers only).
• The recipient has blocked your WhatsApp Business number.

Check the Twilio console's Messaging logs for the exact error code and WhatsApp's reason string.

Member replied STOP but is still getting messages

A STOP reply marks the member as opted out at the account level, which stops new workflow starts and opt-out-aware actions from sending. If a workflow is already mid-conversation with the member, in-flight AI replies may still go out. Confirm the member's account-level opt-out took effect by checking their member page, and also flip their WhatsApp notification toggle off as a belt-and-suspenders measure.

Common Setups

Appointment reminders on WhatsApp

• Approve an appointment reminder template with Meta via Twilio
• Use a scheduled Send WhatsApp action keyed on upcoming appointments
• Have the action start a workflow that handles reschedule requests inside the 24-hour window

Customer support line with WhatsApp as a secondary channel

• Keep your existing SMS-configured number; flip on WhatsApp
• Use the same support workflow for both SMS and WhatsApp — branch inside the workflow if behavior needs to differ
• Let members choose their preferred channel

Broadcast campaign

• Create an approved template with Meta (you can't run a broadcast without one)
• Target a Member Filter of opted-in members
• Run a Routine that fires a Send WhatsApp action per member

Related

• Phone & Voice — Voice and SMS setup on the same phone numbers
• Notification Preferences — Per-member control over SMS, email, voice, and WhatsApp
• Send SMS Action — The SMS counterpart to Send WhatsApp
• Actions — Event-triggered automation including the Send WhatsApp action
• Workflows — Building the conversation flows that handle inbound WhatsApp