WhatsApp Integration Guide

Connect your Sutra agents to WhatsApp using the official Cloud API — giving your users a familiar, secure way to interact with AI agents on the world's most popular messaging platform. Whether it's customer support, internal queries, or automated notifications, your agents are just a WhatsApp message away.

Setup

1. Create a Meta App

  1. Go to the Meta for Developers portal and log in.
  2. Click Create App and select Other -> Business.
  3. Once the app is created, scroll down to "Add products to your app" and set up WhatsApp.
  4. You will be provided with a temporary access token and a Test Phone Number.
Note: The temporary access token Meta provides expires after 24 hours. For production use, you'll need to generate a permanent System User token through the Meta Business Suite. The test phone number works well for development — you can send messages to up to 5 verified numbers without going through business verification.

2. Configure Sutra

In the Sutra UI, go to Settings > Configuration (under Integrations), or update your .env file with the details from your Meta App dashboard:

WHATSAPP_ACCESS_TOKEN=EAA...
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_VERIFY_TOKEN=my_secure_random_string

(Make sure to invent a secure WHATSAPP_VERIFY_TOKEN—you will need it in the next step).

3. Setup the Webhook

Meta needs to know where to send incoming WhatsApp messages. 1. In your Meta App dashboard, go to WhatsApp > Configuration. 2. Under "Webhook", click Edit. 3. Callback URL: Enter your Sutra server's public URL followed by the webhook path (e.g., https://sutra.mycompany.com/api/whatsapp/webhook). Note: Meta requires HTTPS. 4. Verify Token: Enter the exact string you set for WHATSAPP_VERIFY_TOKEN in the previous step. 5. Click Verify and Save. 6. Subscribe to the messages webhook field.

Troubleshooting: If webhook verification fails, check that your Sutra server is publicly accessible over HTTPS (Meta won't accept HTTP). If you're developing locally, use a tunneling service like ngrok to expose your local server. Also verify that the WHATSAPP_VERIFY_TOKEN in your .env matches exactly what you entered in the Meta dashboard — even an extra space will cause verification to fail.

Interacting via WhatsApp

Basic Communication

Once configured, send a WhatsApp message to your configured phone number. By default, Sutra will route incoming WhatsApp messages to your primary designated agent (or you can configure Sutra to route based on the incoming phone number to specific agents).

The default routing sends all incoming messages to your primary agent, but you can configure phone-number-based routing in the Sutra admin panel. This is useful for multi-tenant setups — for example, routing messages from sales team numbers to a Sales Agent and support team numbers to a Support Agent.

Media Handling

The WhatsApp integration supports rich media. If you send an image to the bot, the image is downloaded and passed to the agent. If the agent is equipped with a Vision model (like GPT-4o or Claude 3.5 Sonnet), it can analyze the image and respond.

Supported media types include images (JPEG, PNG), documents (PDF), audio messages, and videos. For audio messages, Sutra automatically transcribes the content using speech-to-text before passing it to the agent, so your users can literally talk to your AI agents via WhatsApp voice notes.

Limitations & Best Practices

  • 24-Hour Window: WhatsApp enforces a 24-hour customer service window. Agents can only reply to a user freely within 24 hours of the user's last message.
  • Templates: To initiate a conversation outside the 24-hour window (e.g., an agent sending a proactive alert), you must use pre-approved WhatsApp Templates. This requires configuring specific template sending tools for your agents within Sutra.
  • Production: When moving from the Test Phone Number to a live production number, ensure your Meta app undergoes the necessary business verification processes required by Meta.
  • Rate Limits: WhatsApp enforces per-phone-number rate limits (varies by tier). Monitor your sending volume and request a tier upgrade through Meta Business Suite if your agents need to send more than 1,000 messages per day.
  • Message Formatting: WhatsApp supports basic formatting (bold, italic, strikethrough, monospace) but not full Markdown or HTML. Sutra automatically converts agent responses to WhatsApp-compatible formatting, but keep this in mind when designing system prompts — tables and complex layouts won't render well.
Going to Production: Before launching, complete Meta's business verification process (typically takes 2-5 business days). You'll need a verified business phone number, a display name, and a brief description of your use case. Once approved, you can message any WhatsApp user — not just your verified test numbers.