Skip to content
SynapsAI Docs

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

Section titled “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.

Setup

Section titled “Setup”

1. Enable the extension

Section titled “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

Section titled “2. Enter your credentials”
FieldDescription
Meta TokenThe access token from your Meta Developer App. This token is encrypted and stored securely — it will appear masked after saving.
Phone IDThe 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

Section titled “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.

4. Test the connection

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Troubleshooting”
ProblemSolution
Messages not arrivingVerify the webhook URL is correctly configured in your Meta Developer App. Check that the messages subscription is active.
Agent not respondingConfirm the extension is enabled (green status on the Extensions page). Check that your Meta Token is valid and has not expired.
”Token expired” errorsGenerate a new system user token from Meta Business Manager and update it in the extension settings.
Messages delayedCheck your Meta Developer App rate limits. WhatsApp Business API has per-number throughput limits depending on your tier.

Next steps

Section titled “Next steps”