WhatsApp

The WhatsApp extension lets your AI agent receive and respond to messages on WhatsApp. Users message your business number and your agent replies automatically — with optional handoff to a human operator when needed.

Prerequisites

Before setting up the WhatsApp extension, make sure you have:

• A Meta Business Account with a verified business.
• A Meta Developer App with the WhatsApp Business API enabled.
• A WhatsApp Business phone number registered in your Meta Business Manager.
• A Meta Token (permanent or system user token) with whatsapp_business_messaging permission.

Tip

If you don’t have a Meta Developer App yet, go to developers.facebook.com and create one. Select “Business” as the app type, then add the WhatsApp product.

Setup

1. Enable the extension

1. Navigate to your agent’s Extensions page.
2. In the Explore tab, find WhatsApp under the Chat category.
3. Click the card to open the configuration page.

2. Enter your credentials

Field	Description
Meta Token	The access token from your Meta Developer App. This token is encrypted and stored securely — it will appear masked after saving.
Phone ID	The Phone Number ID from your WhatsApp Business account (found in the Meta Developer App under WhatsApp > Getting Started).

Click Save to store your credentials.

3. Configure the webhook

After saving, the extension page displays a Webhook URL unique to your agent:

https://api.synapsai.app/v1/{accountId}/whatsapp/{agentKey}

Copy this URL and configure it in your Meta Developer App:

1. In your Meta Developer App, go to WhatsApp > Configuration.
2. Under Webhook, click Edit and paste the webhook URL provided by SynapsAI.
3. Set the Verify Token to match your configuration.
4. Subscribe to the messages webhook field.

Caution

The webhook URL is specific to your agent. If you have multiple agents, each one has its own URL.

4. Test the connection

Send a WhatsApp message to your business number from another phone. You should see the conversation appear in the Conversations page within a few seconds.

What your agent can do

Once configured, your WhatsApp agent can:

• Respond to messages automatically — using your knowledge base, FAQ, and system prompt.
• Collect data and execute actions — through triggers that fire based on conversation conditions.
• Send links and personalized information — including product details, booking links, or custom responses.
• Maintain conversation context — the agent remembers the full conversation history for natural, coherent interactions.

How it works

1. A user sends a WhatsApp message to your business number.
2. WhatsApp delivers the message to SynapsAI via the webhook.
3. Your AI agent processes the message, consults the knowledge base, and generates a response.
4. The response is sent back to the user on WhatsApp.

The user stays in WhatsApp the entire time — no redirects, no external links.

Features

• Automatic replies — your agent responds to WhatsApp messages 24/7 using your knowledge base and system prompt.
• Rich conversation history — all WhatsApp conversations appear in the Conversations page with the WHATSAPP origin badge.
• Contact tracking — WhatsApp users are automatically created as contacts with their phone number linked.
• Operator handoff — when the agent can’t help, the conversation can be transferred to a human operator. The operator responds from the dashboard and the user sees the reply in WhatsApp.
• Cross-channel view — if a contact also interacts via Instagram or Live Chat, you can see all their conversations in one place using the contact filter.

Security

• Your Meta Token is encrypted at rest and never exposed in the UI after saving. The console shows masked bullet points instead.
• If you need to rotate the token, enter the new token and save — the old one is replaced immediately.
• The token is only sent to the Meta API for message delivery and is never logged.

Troubleshooting

Problem	Solution
Messages not arriving	Verify the webhook URL is correctly configured in your Meta Developer App. Check that the messages subscription is active.
Agent not responding	Confirm the extension is enabled (green status on the Extensions page). Check that your Meta Token is valid and has not expired.
”Token expired” errors	Generate a new system user token from Meta Business Manager and update it in the extension settings.
Messages delayed	Check your Meta Developer App rate limits. WhatsApp Business API has per-number throughput limits depending on your tier.

Next steps

• Configure behavior — customize how your agent responds on WhatsApp.
• Operator Handoff — set up human takeover for complex conversations.
• Triggers — automate actions based on conversation conditions.
• Conversations — review WhatsApp conversation history.
• Instagram — add another messaging channel.