WhatsApp Integration

Overview

The Reaktly WhatsApp integration connects your WhatsApp Business number to your AI-powered operator. Incoming WhatsApp messages are routed to Reaktly, where your AI responds instantly — and can hand off to a human agent when needed.

Key capabilities include text messaging, interactive button replies, AI-powered responses drawn from your knowledge base, automatic conversation routing, and seamless human handoff. This integration uses the WhatsApp Business API (via Meta's Cloud API) — it does not work with personal WhatsApp or the WhatsApp Business mobile app.

Prerequisites

Before you begin, make sure you have:

• A Meta Business Account (verified, or with verification in progress)
• A Facebook Developer Account at developers.facebook.com
• A phone number for WhatsApp Business — you can use Meta's test number during development
• An active Reaktly account with at least one operator configured
• An HTTPS-accessible API endpoint for webhook delivery (your Reaktly instance)

Step 1: Create a Meta App

1. Go to developers.facebook.com → My Apps → Create App.
2. Select the app type Business.
3. Fill in your app name, contact email, and select your Business Account.
4. On the app dashboard, click Add Product → find WhatsApp → click Set Up.
5. You now have a WhatsApp-enabled Meta App.

Step 2: Get Your WhatsApp API Credentials

You need four credentials. Here's where to find each one:

Phone Number ID

Go to your Meta App Dashboard → WhatsApp → Getting Started. Select your phone number from the dropdown — the Phone Number ID is displayed below it.

WhatsApp Business Account ID

On the same Getting Started page, find the WhatsApp Business Account ID near the top. You can also find it under Settings → WhatsApp Accounts.

Permanent Access Token

Temporary tokens from the Getting Started page expire in 24 hours. For a permanent token:

1. Go to business.facebook.com → Settings → System Users.
2. Click Add to create a new System User with the Admin role.
3. Click Generate Token on the System User.
4. Select your WhatsApp Meta App.
5. Grant the following permissions:
   • whatsapp_business_messaging
   • whatsapp_business_management
6. Click Generate Token and copy it immediately.

App Secret

Go to your Meta App Dashboard → Settings → Basic → App Secret. Click Show to reveal it. This is used for webhook signature verification.

Step 3: Configure in Reaktly

1. Navigate to your Operator Dashboard → Integrations → Add WhatsApp.
2. Enter the credentials from Step 2:
   • Access Token
   • Phone Number ID
   • WhatsApp Business Account ID
   • Phone Number (in E.164 format, e.g. +1234567890)
3. Reaktly auto-generates a Webhook URL and a Verify Token.
4. Copy both — you need them for the next step.

POST /api/integrations/credentials
Content-Type: application/json

{
  "accessToken": "EAAGn...",
  "phoneNumberId": "10620...",
  "businessAccountId": "17841...",
  "phoneNumber": "+1234567890"
}

Step 4: Configure Webhook in Meta

1. In your Meta App Dashboard, go to WhatsApp → Configuration.
2. Under Webhook, click Edit.
3. Paste the values from Reaktly:
   • Callback URL: Your Reaktly webhook URL (format: https://your-api.com/webhooks/whatsapp_cloud/{webhookPath})
   • Verify Token: The verify token generated by Reaktly
4. Click Verify and Save. Meta sends a verification request to your endpoint — if it responds correctly, the webhook is confirmed.
5. Under Webhook Fields, subscribe to:

Step 5: Test the Integration

1. In your Meta App Dashboard → WhatsApp → Getting Started, add a test phone number.
2. Send a message from your test number to your WhatsApp Business number.
3. Open the Reaktly inbox — a new conversation should appear with a WhatsApp channel badge.
4. Verify that the AI responds and the reply appears back in WhatsApp.

If everything is working, you'll see the full conversation thread in both WhatsApp and the Reaktly dashboard.

Supported Message Types

AI Behavior on WhatsApp

The AI automatically adapts its responses for the WhatsApp medium:

• Concise responses — messages are kept short and mobile-friendly.
• No markdown tables or headers — WhatsApp doesn't render them, so the AI avoids these constructs.
• Supported formatting — bold (*text*) and italic (_text_) work on WhatsApp and are used when appropriate.
• Link sharing — the AI suggests visiting your website for detailed information and shares knowledge base articles as text summaries with links.
• Conversational tone — responses feel natural for a messaging context rather than a formal support channel.

Phone Number Requirements

• Must be in E.164 format (e.g., +1234567890, +4915112345678).
• The number must be registered for the WhatsApp Business API through Meta.
• It cannot be currently registered on regular WhatsApp or the WhatsApp Business mobile app.
• For production use, the number must have an approved display name via Meta.

Going to Production

Once you've tested with development credentials, follow these steps for production:

1. Complete Meta Business Verification — go to Business Settings → Business Verification and submit the required documents.
2. Request production access for your WhatsApp Business API in the Meta App Dashboard.
3. Register your production phone number through the WhatsApp setup flow.
4. Generate a permanent System User access token (see Step 2 above).
5. Update credentials in Reaktly with your production values.
6. Verify your API endpoint uses a valid SSL certificate from a trusted CA.

Rate Limits & Messaging Tiers

WhatsApp enforces messaging limits based on your account tier:

• New accounts start at Tier 1 — 1,000 business-initiated conversations per day.
• Customer-initiated conversations (where the user messages you first) have no limit.
• Tiers increase automatically as your message volume and quality rating improve.
• The quality rating is based on user feedback — if recipients block or report your number, your rating drops.

For full details on tier limits and quality ratings, see Meta's messaging limits documentation.

Troubleshooting

Webhook verification fails

• Confirm the Verify Token matches exactly between Reaktly and Meta (no trailing spaces).
• Ensure the Callback URL is HTTPS and publicly accessible.
• Check that your server responds to GET requests with the hub.challenge value.

Messages not arriving in Reaktly

• Verify you've subscribed to the messages webhook field in Meta's Configuration panel.
• Check that the webhook status shows a green checkmark (not an error).
• Review your server logs for incoming webhook POST requests.

"Access denied" errors when sending replies

• Ensure the System User token has the whatsapp_business_messaging permission.
• Verify the token has not been revoked or rotated in Business Settings.

Phone number format errors

• Use E.164 format with the country code — e.g., +49 for Germany, +1 for US/Canada.
• Do not include spaces, dashes, or parentheses.

Responses not sent back to WhatsApp

• Check that the access token is valid and has not expired (use a permanent System User token, not a temporary one).
• Confirm the Phone Number ID is correct and matches the number receiving messages.
• Review the Reaktly logs for outbound API errors.

Security Notes

• Encryption at rest — access tokens and credentials are encrypted using AES-256.
• Obfuscated webhook paths — webhook URLs use randomized paths, not phone numbers or account IDs.
• Webhook signature verification — for production, enable signature verification using your App Secret. Meta signs every webhook payload with a SHA-256 HMAC, allowing your server to verify that requests genuinely come from Meta.