Channels

WhatsApp

The WhatsApp channel uses the Meta Cloud API to connect Open Astra agents to a WhatsApp Business phone number. Users send messages to your business number and receive agent responses.

Prerequisites

  • A Meta Business Account
  • A WhatsApp Business Account linked to a phone number
  • A Meta App with WhatsApp product added and approved for production use
  • A publicly accessible HTTPS endpoint for the webhook

Setup

  1. In the Meta Developer Portal, go to your app and navigate to WhatsApp > API Setup
  2. Copy the Phone Number ID and generate a permanent Access Token
  3. Under Webhooks, configure the callback URL: https://your-domain/channels/whatsapp
  4. Subscribe to the messages webhook field
  5. Add to your environment:
bash
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
WHATSAPP_ACCESS_TOKEN=your-permanent-access-token

Webhook verification

Meta requires webhook verification before activating. The Astra WhatsApp channel handler automatically responds to Meta's verification GET request using a configurable verify token:

bash
# Add verify token (any string you choose)
WHATSAPP_VERIFY_TOKEN=my-secret-verify-token

# Set this same token in Meta's webhook configuration

Configuration in astra.yml

yaml
channels:
  whatsapp:
    enabled: true
    defaultAgent: assistant-agent
    allowedPhoneNumbers: []     # Empty means all numbers allowed
    sendTypingIndicator: true   # Show typing bubble while agent processes

WhatsApp limitations

  • Text responses only — rich embeds and tables are sent as plain text
  • 24-hour messaging window — you can only message a user within 24 hours of their last message, unless using approved message templates
  • Media files are supported for receipt but responses are text-only in the current implementation