Skip to main content

​
Overview

The WhatsApp integration uses the WhatsApp Cloud API (Meta Business Platform) to send and receive messages. The adapter handles HMAC signature verification for inbound webhooks and supports text, images, and media messages.
Requirements: A Meta Business account with WhatsApp Business API access and a verified phone number.

​
Architecture

​
Setup

1

Create a Meta App

  1. Go to Meta for Developers
  2. Create a new app and add the WhatsApp product
  3. Generate a permanent access token (or use a system user token)
  4. Note the Phone Number ID from the WhatsApp settings
2

Configure the Webhook

Set the webhook callback URL to:
https://your-domain.com/api/v1/channel-webhooks/whatsapp/{channel_id}
Subscribe to the messages webhook field. Set a Verify Token that matches your Nadoo AI configuration.
3

Configure in Nadoo AI

In the Nadoo AI platform, navigate to Workspace Settings > Channels and create a new WhatsApp channel:
FieldDescription
Access TokenPermanent token from the Meta Business Platform
Phone Number IDThe WhatsApp Business phone number ID
App SecretMeta app secret for webhook HMAC verification
Link the channel to your target application.

​
Credentials

The WhatsApp adapter requires the following credentials: 
credentials = {
    "access_token": "your-whatsapp-access-token",
    "phone_number_id": "your-phone-number-id",
    "app_secret": "your-meta-app-secret"  # for HMAC verification
}

​
Webhook Security

Inbound messages are verified using HMAC-SHA256 signature validation. The adapter computes: 
HMAC-SHA256(app_secret, request_body)
and compares it against the X-Hub-Signature-256 header sent by the WhatsApp Cloud API.
The app_secret must be the same secret from your Meta app’s settings. Without it, webhook signature verification will fail and messages will be rejected.

​
Message Features

TypeInboundOutbound
Plain textYesYes
ImagesYesYes
DocumentsYesPlanned
AudioYesPlanned
VideoYesPlanned
LocationYesNo
ContactsYesNo
WhatsApp requires pre-approved message templates for initiating conversations (outside the 24-hour session window). Within the 24-hour window after a user message, you can send free-form replies.
Media attachments (images, documents, audio, video) are received as WhatsApp media IDs. The normalizer downloads the media content and includes it as MediaAttachment objects in the inbound message.

​
API Base URL

The adapter communicates with the WhatsApp Cloud API at: 
https://graph.facebook.com/v18.0/{phone_number_id}/messages
Outbound messages are sent as POST requests with the access token in the Authorization header.

​
Next Steps

Channels Overview

Learn about the channel system architecture

Webhooks

Custom webhook integrations