WhatsApp Business

Sophon connects to WhatsApp using the WhatsApp Business Cloud API. This requires a Meta Business account and a registered WhatsApp Business phone number.

Prerequisites

• A Meta Business account
• A phone number that can receive SMS or calls for verification
• A public URL for webhook delivery (or a tunneling tool like ngrok for development)

Step-by-Step Setup

1. Create a Meta App

1. Go to Meta for Developers
2. Click Create App > Other > Business
3. Name it (e.g., "Sophon WhatsApp") and click Create App

2. Set Up WhatsApp Product

1. In your app dashboard, find WhatsApp and click Set Up
2. Select or create a Meta Business Account
3. You'll get a test phone number to start with (or add your own later)

3. Get Your Credentials

Phone Number ID

1. Go to WhatsApp > API Setup in the app dashboard
2. Copy the Phone Number ID (numeric string)

Permanent Access Token

1. Go to Business Settings > System Users
2. Create a system user (Admin role)
3. Click Generate New Token
4. Select your app and add the whatsapp_business_messaging permission
5. Copy the token

Webhook Verify Token

Choose any custom string (e.g., sophon-verify-2026). You'll use this same string in both Sophon and the Meta webhook configuration.

4. Configure the Webhook

1. Go to WhatsApp > Configuration in the app dashboard
2. Click Edit on the Webhook section
3. Set:
   • Callback URL: https://your-domain.com/api/channels/whatsapp/webhook
   • Verify Token: The custom string you chose above
4. Click Verify and Save
5. Subscribe to the messages webhook field

For local development, use a tunnel:

ngrok http 8080
# Use the HTTPS URL as your callback: https://xxxx.ngrok.io/api/channels/whatsapp/webhook

5. Configure in Sophon Dashboard

1. Go to Channels and click Add Channel
2. Select WhatsApp Business
3. Enter the Phone Number ID
4. Enter the Permanent Access Token
5. Enter the Webhook Verify Token (same string as in Meta)
6. Click Test Connection
7. Click Activate

6. Test It

Send a message to your WhatsApp Business number from any WhatsApp account. Sophon should respond.

Note: With the test phone number, you can only send messages to numbers added to the "To" list in the API Setup page. For production, you'll need to verify your business and register a real phone number.

Configuration Reference

Media Support

channels.json Example

{
  "id": "whatsapp-business",
  "type": "whatsapp",
  "name": "Sophon WhatsApp",
  "enabled": true,
  "config": {
    "phoneNumberId": "1234567890",
    "accessToken": "<encrypted>",
    "verifyToken": "sophon-verify-2026"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session",
    "groupBehavior": "mention-only"
  },
  "status": "connected"
}

Troubleshooting

• Webhook verification fails — The verify token in Sophon must exactly match the one entered in Meta Developer Portal. Ensure Sophon is running and the callback URL is publicly accessible.
• "Access token is invalid" — System user tokens do not expire, but they can be revoked. Generate a new one in Business Settings > System Users.
• Messages not arriving — Check that you've subscribed to the messages webhook field in WhatsApp > Configuration. Also verify the callback URL is correct and responding with 200.
• "Recipient not in allowed list" — On the test phone number, you can only message numbers added to the allowed list. Go to WhatsApp > API Setup and add the recipient number.
• Media download fails — Inbound media requires the access token to download from Meta's servers. Ensure the token has whatsapp_business_messaging permission.