Skip to main content

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 — with a few extra rules you need to know about, starting with HIPAA.

WhatsApp and HIPAA​

WhatsApp is not HIPAA-eligible. Meta, which carries every WhatsApp message, does not sign a Business Associate Agreement, and Twilio's BAA excludes WhatsApp. WhatsApp must never carry protected health information.

Gravity Rail therefore allows WhatsApp only in a workspace that has been explicitly declared free of PHI: its organization classified as non-PHI and the workspace itself marked as prohibiting PHI. Gravity Rail staff record that classification, with a review date; contact support if your workspace should be classified. A classification whose review date has passed no longer counts, so WhatsApp stops until it is renewed. In every other workspace, including one that has not been classified yet:

  • outbound WhatsApp messages are refused before they reach Twilio;
  • inbound WhatsApp messages are dropped without being stored or answered;
  • the WhatsApp switch on a phone number can't be turned on.

Prerequisites​

Before you can use WhatsApp, you need:

  1. The workspace must be declared free of PHI — see WhatsApp and HIPAA.
  2. 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.
  3. 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 is declared free of PHI, 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​

SettingWhat It Does
Enable SMSAllow text messaging on this number
Enable WhatsAppAllow WhatsApp messaging on this number
Messaging Routing RulesShared ordered destinations and replies for inbound SMS and WhatsApp messages
Reply to textsSent when a text arrives while SMS and WhatsApp are both off. Leave empty to send nothing

WhatsApp and SMS share the number's brand name, Reply to texts, and Messaging routing rules. Their enable switches and delivery metadata remain separate.

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 the workspace is declared free of PHI and that WhatsApp is enabled for the workspace and the number. If any check fails, the message is rejected without being stored.
  4. The number's shared Messaging Routing Rules select its destination or reply. A This number's owner rule sends the message to the number's owner, and the owner also answers a known sender when no rule does.
  5. If an AI destination answers, its reply is sent as WhatsApp back to the member. Human destinations and message rules follow their configured action.

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 preference (notifyWhatsapp in the Members API) 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 preference is separate from SMS, email, and voice. A member can be on for SMS and off for WhatsApp, or the other way around. It is not on the member's edit form; set it through the Members API (notifyWhatsapp on create or update).

Inbound messages are not gated by this preference — if a member WhatsApps your number on their own, the number's Messaging Routing Rules still run. The preference only gates outbound-initiated sends, and that includes an agent's reply: a member who first contacts you on WhatsApp starts with it off, so an agent cannot message them until it is turned on.

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 enabled (notifyWhatsapp).

If any check fails, the action logs a skip reason and doesn't send. A send that passes these checks is still refused if the workspace isn't declared free of PHI.

2. From an Inbound Routing Rule​

A number's shared Messaging Routing Rules decide whether inbound SMS and WhatsApp messages go to an AI Workflow, a person, an auto-reply, or another supported destination. Replies stay on the inbound transport.

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. The tool sends only to a member whose WhatsApp preference is enabled, and only from a workspace declared free of PHI; otherwise it tells the agent the message was not sent.

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 reply STOP to your workspace number on WhatsApp, and the same keyword handling as SMS processes it. A STOP on either channel records an SMS opt-out (see Notification Preferences) and turns off the member's WhatsApp preference too. A WhatsApp STOP blocks automated AI calls only if your organization has a registered texting brand; otherwise turn off the member's Voice preference as well. In a workspace not declared free of PHI, inbound WhatsApp is dropped unread, STOP included; a member there opts out by texting STOP over SMS.

START turns SMS back on but not WhatsApp: WhatsApp is opt-in, so re-enable it through the Members API once the member asks for it. You can also turn an individual member's WhatsApp preference off through the API at any time.

Limitations and Gotchas​

  • No PHI, ever. WhatsApp works only in a workspace declared free of PHI. See WhatsApp and HIPAA.
  • 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. Outbound actions and agent tools will skip them until you turn it on.
  • Media. Outbound WhatsApp messages can carry media attachments. Treat inbound media as something the AI won't be able to read.
  • Shared routing. WhatsApp and SMS use the same ordered Messaging Routing Rules list. Transport-specific enablement and delivery behavior remain separate.
  • 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 is declared free of PHI. Until it is, inbound WhatsApp is dropped silently.
  2. Confirm the workspace has the WhatsApp feature enabled (ask your org admin if unsure).
  3. Open the phone number and confirm WhatsApp is turned on.
  4. Confirm the number has a matching Messaging Routing Rule with the intended destination.
  5. 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 these 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." Turn the member's WhatsApp preference on through the Members API, if they have asked for WhatsApp.
  • Phone number not WhatsApp-enabled — Action fails with "Phone number does not have WhatsApp enabled." Turn on WhatsApp on the phone number.
  • Workspace not declared free of PHI — The send is refused before it reaches Twilio. See WhatsApp and HIPAA.

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 turns off both the member's SMS and WhatsApp preferences, except a WhatsApp STOP to a workspace not declared free of PHI, which is dropped unread (see Opt-Out). If messages still arrive, check whether something re-enabled the WhatsApp preference through the Members API, or whether the messages come from a different member record with the same number.

Common Setups​

These setups apply only to a workspace declared free of PHI. A reminder that names a clinical appointment is PHI and must not go over WhatsApp.

Event reminders on WhatsApp​

  • Approve a reminder template with Meta via Twilio, for a non-clinical event such as a class or a delivery
  • Use a scheduled Send WhatsApp action keyed on the upcoming event
  • 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
  • Phone & Voice — Voice and SMS setup on the same phone numbers
  • Notification Preferences — Per-member control over SMS, email, and voice
  • 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