WhatsApp

WhatsApp integration uses the WhatsApp Business API provided through Meta. This requires a Meta developer account, a verified business phone number, and a webhook endpoint that Talon exposes for Meta to deliver messages to.

Note

The WhatsApp Business API is distinct from the WhatsApp consumer app. You will be communicating through a dedicated business phone number, not your personal WhatsApp account.

Prerequisites

• A Meta developer account
• A phone number to register with WhatsApp Business (it cannot already be registered to a personal WhatsApp account)
• A publicly accessible URL for Talon’s webhook endpoint (or a tunnel such as ngrok for local development)

Setup

1. Create a Meta App

Go to developers.facebook.com and click My Apps > Create App.

Select the Business app type and complete the creation form.

2. Add the WhatsApp Product

Inside your app dashboard, click Add Product and select WhatsApp. Click Set up.

3. Get a Test Phone Number

In the WhatsApp setup wizard, Meta provides a free test phone number for development. Use this to verify the integration before registering a production number.

From the API Setup page, note your:

• Phone Number ID — identifies which number to send from
• WhatsApp Business Account ID

Click Generate to create a temporary access token (valid for 24 hours). For production, create a permanent System User token under Business Settings > System Users.

4. Configure the Webhook

In the WhatsApp > Configuration page, click Edit next to Webhook.

Set the Callback URL to the URL where Talon is listening, typically:

https://your-domain.com/webhook/whatsapp

Set a Verify Token — this is a secret string you choose. Talon will use this same value in its config to validate incoming webhook verification requests from Meta.

Under Webhook Fields, subscribe to the messages field.

5. Add to Config

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "my-number": {
          "verify_token": "my-secret-verify-token",
          "access_token": "EAAxxxxxxxxxxxxx",
          "phone_number_id": "1234567890"
        }
      }
    }
  }
}

Restart Talon and send a test message to your WhatsApp business number. Meta delivers the message to Talon’s webhook, the agent responds, and the reply is sent back via the WhatsApp API.

Configuration Fields

Field	Required	Description
verify_token	Yes	Secret string used to validate Meta’s webhook verification request
access_token	Yes	Meta access token with whatsapp_business_messaging permission
phone_number_id	Yes	The Phone Number ID from the WhatsApp API Setup page
allow_from	No	List of phone numbers (in E.164 format) allowed to message the bot
model	No	Override the default AI model for this account

Restricting Access

Phone numbers in allow_from must be in E.164 format (country code with no spaces or dashes, e.g. +14155552671):

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "my-number": {
          "verify_token": "my-secret-verify-token",
          "access_token": "EAAxxxxxxxxxxxxx",
          "phone_number_id": "1234567890",
          "allow_from": ["+14155552671"]
        }
      }
    }
  }
}

Tip

For production use, replace the temporary 24-hour access token with a permanent System User token. In Meta Business Suite, go to Business Settings > System Users, create a system user, assign it to your WhatsApp app with appropriate permissions, and generate a permanent token.

Going to Production

During development, you can only message phone numbers that have been added as test recipients in the Meta dashboard. To send messages to any number, you must:

1. Submit your app for Business Verification in Meta Business Manager.
2. Complete the WhatsApp Business Account verification process.
3. Register a production phone number.
4. Switch from a test token to a permanent System User token.