Skip to main content

WhatsApp

The WhatsApp channel connects your agents to customers on WhatsApp through the official Meta WhatsApp Business API, using a verified business phone number. Customers write to your number and the AI agent answers; human agents reply in the same conversation from the Human Agents workspace; and campaigns use the channel to start outbound conversations with approved templates.

You create the WhatsApp connection once in Settings > Channels, then attach it to an agent — the connection holds the credentials, the agent page only attaches it.

Use this page to:

  • Set up the Meta side and collect the credentials the portal needs.
  • Create and start the WhatsApp connection.
  • Attach the connection to an agent and verify that it answers.
  • Understand templates, the 24-hour messaging window, and delivery statuses.

Conversations support text, voice messages (with transcription when speech-to-text is configured for the agent), images, videos, documents, and other files. Location sharing, calls, and group management are not supported.

Before you start​

  • A Meta Business Account — create one at business.facebook.com if you don't have one yet.
  • A phone number for the channel. Its SIM card must not be registered with any existing WhatsApp account and must be able to receive SMS verification codes.
  • An account in the portal with permission to edit settings.
Simple mode shortcut

If you build your agent in Simple mode, you can skip the Settings screen: attaching WhatsApp on the agent's Channels tab collects the same Meta credentials inline and creates the connection for you. Either way, complete the Meta-side setup below first.

Connect WhatsApp​

Get your Meta credentials​

Set up the WhatsApp Business API in the Meta developer console and collect the values you will paste into the portal.

  1. Create a developer app. Go to developers.facebook.com/apps and click Create App. Select the use case Other, the app type Business, and your business account.

  2. Add WhatsApp to the app. In the App Dashboard, find the WhatsApp card, click Set Up, then Quickstart > Start using API.

  3. Generate an access token. Under API Setup, click Generate Access Token and save the token.

  4. Register your phone number. Under WhatsApp > API Setup, click Add phone number, enter the number, and verify it with the SMS code. Then confirm the registration with a Graph API call:

    curl 'https://graph.facebook.com/v21.0/<PHONE_ID>/register' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <TOKEN>' \
      -d '{ "messaging_product": "whatsapp", "pin": "<PIN>" }'

    <PHONE_ID> and <TOKEN> come from WhatsApp > API Setup; <PIN> is the SMS verification code.

When the Meta side is ready, collect five values for the portal form:

ValueWhere to find it in the Meta console
App ID, App secretApp Settings > Basic
Access token, Phone number ID, Business account IDWhatsApp > API Setup

Create the connection​

  1. Go to Settings > Channels, select WhatsApp in the list, and click Add. The New connector form opens on the right.
  2. Fill in the form — see the field table below. Enter every value you collected in the Meta console, including the fields the form does not mark as required.
  3. Click Save.
  4. Click Start in the panel header. The status dot turns purple (STARTING), then green (RUNNING).
FieldRequiredDescription
NameYesInternal name shown across the portal.
DescriptionNoInternal reference.
App IDNoThe ID of your Meta app.
App secretNoThe app secret, found next to the App ID.
Access tokenYesThe WhatsApp API access token you generated.
Phone number IDNoOne or more phone number IDs. See Use multiple phone numbers.
Business account IDYesYour WhatsApp business account ID.
Advanced mode

The WhatsApp form has an Advanced mode switch. Advanced mode is the manual form described above; with the switch off, you sign in with your Meta account instead of pasting credentials by hand. If the switch is disabled with the message "Meta App ID and App Secret are not configured on the server", use Advanced mode.

For the general mechanics of the screen — status dots, Logs, editing credentials, stopping and restarting — see the Channels overview.

Replace an expired access token​

If the access token is rotated or stops working, update the connection rather than creating a new one:

  1. Go to Settings > Channels and select the WhatsApp connection. Secret fields display masked.
  2. Paste the new token into Access token and click Save.
  3. Restart the channel: click Stop, wait for STOPPED, then click Start.

Use multiple phone numbers​

One WhatsApp connection can serve several phone numbers from the same Meta business account. Enter the Phone number ID values separated by commas — for example, 487008484500533, 487215647816419 — and keep the order consistent across related fields.

Outbound messages rotate through the numbers. After the first message, each recipient keeps the same sender number, so every customer sees one continuous conversation.

Attach to an agent​

A running channel does nothing until an agent uses it.

If you configure your agent in Simple mode:

  1. Open the agent and go to the Channels tab.
  2. Click WhatsApp. A channel row appears.
  3. Expand the row, complete the channel form, and click Apply. The connection this creates also appears in Settings > Channels, where you manage it afterward.
  4. Check the status badge on the row — when it shows RUNNING, the agent answers messages sent to your number.

To attach a connection that already exists in Settings > Channels, use the Communication channels card on the agent's page instead:

  1. Click Add and pick WhatsApp from the dropdown.
  2. Tick the checkbox next to your connection.
  3. Enable the Inbound switch if this agent should answer incoming messages. With Inbound off, the agent can only send outbound messages through the channel — for example, in campaigns.
  4. Save the agent, then restart it (Stop agent, then Start agent).

Only one agent should handle inbound traffic for a WhatsApp number; if the number is already taken, the portal shows which agent uses it. To put another inbound agent on WhatsApp, create a separate connection with its own number.

To verify the setup, message your business number from any WhatsApp account and check that the agent replies. The conversation appears in Sessions.

Templates​

A WhatsApp template is a message pre-approved by Meta: fixed wording, optionally with numbered variables such as {{1}} and {{2}} that are filled in at send time. You create templates and submit them for approval in Meta's WhatsApp Manager, outside Flametree. Once approved, a template can be picked from the template list in the portal.

WhatsApp requires a template whenever your business writes first:

  • Starting a new conversation with a customer who has not messaged you — with Start conversation in 360 View, or with a WhatsApp Communication step in a campaign flow, which maps template variables to participant fields.
  • Continuing a conversation after the 24-hour messaging window closes.

Sending a template from a conversation or from 360 View works the same way:

  1. Pick an approved template from the list. The preview shows the template text.
  2. If the template has variables, fields for them appear with the preview. Values are pre-filled from the customer's saved contact data where possible — review and edit them before sending.
  3. Click Send template.

In the session history, the first message of an outbound WhatsApp conversation carries a WhatsApp template badge.

The 24-hour messaging window​

WhatsApp lets a business send free-form messages only within 24 hours of the customer's last message. Each new customer message reopens the window for another 24 hours.

SituationWhat you can send
The customer wrote within the last 24 hoursFree-form messages — AI agent replies and human agent replies.
More than 24 hours since the customer's last messageApproved templates only.
No conversation yet — your business writes firstApproved templates only.

The portal enforces the window for people working a WhatsApp conversation in the Human Agents workspace:

  • When the window has closed, the message input is replaced by a notice — It's been over 24 hours since the last reply. Select a WhatsApp template to continue. Click Continue with template and send an approved template.
  • When the conversation was started with a template and the customer has not replied yet, the input is disabled with the hint Waiting for customer reply. Messaging will be available once they respond.
  • A business-initiated template cannot be sent to the same customer again within 24 hours while they have not replied — the portal opens the existing conversation instead.

As soon as the customer replies — to a template or to anything else — the window reopens and normal messaging resumes.

Delivery and read status​

The channel receives Meta's status callbacks for every outbound message:

  • Sent — the message was accepted by WhatsApp.
  • Delivered — the message reached the customer's device.
  • Read — the customer opened the message. For voice messages, WhatsApp reports played, which is shown as read.

In the session chat, messages show a delivery status icon; hover over it to see the exact time and, when available, a note from the channel provider. See Sessions.

Common issues​

  • The channel goes to ERROR right after Start. Credentials are wrong or expired. Open the connection, click Logs, re-check the Access token and Business account ID, Save, and start again.
  • The channel is RUNNING but the agent does not reply. The connection is not attached to the agent, Inbound is off, or the agent was not restarted after attaching. Check the agent's status in AI Agents as well.
  • Messages stop being delivered. Access tokens expire and numbers can be disconnected. Check that the token is still valid and that the number shows Connected in the Meta console, then check the channel Logs.
  • You cannot write to a customer. More than 24 hours have passed since their last message. Send an approved template — in the conversation, click Continue with template.
  • A template cannot be sent again. You sent a business-initiated template to this customer less than 24 hours ago and they have not replied. The portal opens the existing conversation instead.
  • Voice messages arrive without transcription. Configure speech-to-text for the agent.

Was this article helpful?