Prerequisites

• A WhatsApp Business Account (WBA) linked to a Meta Business Portfolio. The account must be verified or in an approved verification state.
• A Mirai organization with the Atlas suite enabled. Onboard at app.usemirai.app if not already registered.
• At least one approved phone number in the WhatsApp Business account. Voice-only numbers are not supported for messaging.
• The phone number must not be connected to any other WhatsApp Business API client or third-party automation tool simultaneously.

Step 1: Obtain a Meta WhatsApp Business token

Generate a permanent access token from the Meta Developer Console. This token authenticates Mirai against your WhatsApp Business account. Store it securely — do not commit it to source control.

1. Go to developers.facebook.com and create or open your WhatsApp Business app.
2. Under WhatsApp > Getting Started, copy the Phone Number ID and WhatsApp Business Account ID.
3. Generate a permanent access token with the following permissions: whatsapp_business_management, whatsapp_business_messaging.
4. Save the token in your secrets manager and note the Phone Number ID — both are required in the Atlas Connect step.

Step 2: Register the channel in Atlas

Register the WhatsApp Business credentials with Atlas. Atlas stores the credentials org-scoped and encrypted. The channel_id returned is used in subsequent session and message calls.

POST /v1/atlas/channels
{
  "channel_type": "whatsapp",
  "idempotency_key": "ch_whatsapp_01HX9Z",
  "config": {
    "phone_number_id": "PHONE_NUMBER_ID_FROM_META",
    "waba_id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "access_token": "$WHATSAPP_ACCESS_TOKEN"
  },
  "display_name": "Acme Beauty WhatsApp"
}
Response: {
  "channel_id": "ch_01HXAB",
  "channel_type": "whatsapp",
  "status": "pending_verification",
  "display_name": "Acme Beauty WhatsApp"
}

Step 3: Verify the webhook callback

Meta sends a verification challenge to your registered webhook URL when you configure the Meta WhatsApp Business webhook. Atlas handles this automatically using the callback URL associated with your org. You do not need to implement the verification handshake manually.

To confirm the connection is live, send a test message from the WhatsApp app to your business number. Atlas will receive it and emit the conversation.created event to any registered webhooks.

Step 4: Confirm channel health

Check the channel status endpoint to confirm the connection is healthy and messages are flowing:

GET /v1/atlas/channels/{channel_id}
Response: {
  "channel_id": "ch_01HXAB",
  "channel_type": "whatsapp",
  "status": "active",
  "display_name": "Acme Beauty WhatsApp",
  "capabilities": ["messaging", "read_receipts", "typing_indicator"],
  "last_health_check": "2026-05-21T10:05:00Z"
}

A status of active means the channel is ready for live traffic. A status of pending_verification means the webhook callback has not been confirmed — check your Meta Developer Console settings.

Phone number quality

WhatsApp Business enforces template quality ratings on your phone number. If the quality rating drops below Medium, message delivery may be degraded. Avoid sending unsolicited messages or using spammy templates — this is the most common cause of channel deactivation.

• Start with high-quality, consent-based conversations. New numbers have a 24-hour conversation window with no quality restrictions.
• Use verified template messages (Message Templates in Meta Business Console) for all outbound proactive messages.
• Monitor your quality score in the WhatsApp Business Manager dashboard and address any user-reported issues immediately.