Skip to main content

WhatsApp

The WhatsApp channel connects your agents to customers on WhatsApp through the official Meta WhatsApp Business API. Customers write to your business 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 don't need a Meta developer account or any technical setup. You sign in with a Meta (Facebook) account, follow Meta's guided sign-up, and the portal does the rest. If you have never set up a business on Meta before, the sign-up walks you through creating everything you need along the way — the only thing you bring is a phone number.

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.

Want to enter credentials yourself?

This guide uses Login with Meta, the simplest path. If you'd rather bring your own Meta app and paste credentials by hand — or the Login with Meta button is disabled with the message "Meta App ID and App Secret are not configured on the server" — turn on Advanced mode and follow WhatsApp (advanced setup) instead.

Use this page to:

  • Connect a WhatsApp business number by signing in with Meta.
  • 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 phone number for your business that can receive an SMS or a phone call to confirm a one-time code. It must not already be in use with any WhatsApp account — personal or business. (A number on the regular WhatsApp or WhatsApp Business app counts as in use; pick a different number, or first delete that account in the app.)
  • A Meta account — the Facebook login you use for your business. If you don't have one, you can create it during sign-in.
  • An account in the portal with permission to edit settings.

You do not need to create a Meta developer app, generate tokens, or register the number by hand — Meta's guided sign-up and the portal handle all of that.

Connect WhatsApp​

Open the connector and start sign-in​

  1. Go to Settings > Channels, select WhatsApp in the list, and click Add +. The New connector panel opens on the right.
  2. Leave the Advanced mode switch (top-right of the panel) off. Optionally type a Name and Description — if you leave Name empty, the portal fills in a suggested name after sign-in.
  3. Click Login with Meta.

Complete the Meta sign-up​

A window titled Facebook Login for Business opens and walks you through Meta's WhatsApp sign-up. Sign in with your Facebook account if prompted, then follow the screens:

  1. Get started. On the welcome screen ("…connect your account to Flametree"), read what you'll be able to do and click Continue.
  2. Select your business assets. On "Select the business assets to share with…", pick your Business portfolio and WhatsApp Business account from the dropdowns. You can choose existing ones or create new ones in place. Click Next.
  3. Add your phone number. On "Add your WhatsApp phone number", choose Use a new or existing WhatsApp number, select or enter the Phone number, and click Next. If Meta asks, confirm the verification code it sends to that number by SMS or call. (Use a display name only is the other option, when you don't attach a number.)
  4. Review and confirm. On "Review what you'll share with…", check the access being granted — managing your WhatsApp account and conversations — and click Confirm.
  5. Wait for the connection. Meta shows "Connecting your account — This may take a few moments…" Leave the window open until it finishes and closes on its own. If it stalls, click Retry.

Finish in the portal​

  1. The window closes and the portal finishes the setup for you — it registers the number, connects the webhook so messages reach your agent, fills in the credentials, and saves the connection. You see the toast Integration created successfully. The new entry is named with the Name you entered, or — if you left Name empty — a suggested name like WhatsApp: +1 23 456 7890; it also shows the App ID, Phone number ID, and Business account ID. You can rename it later by editing the connection.
  2. Select the new connection and click Start in the panel header. The status dot turns purple (STARTING), then green (RUNNING).

After Login with Meta, the portal stores these values for you. You don't enter them by hand, but you'll recognize them in the connection details:

ValueWhat it is
Phone number IDMeta's internal ID for the business number you added.
Business account IDThe WhatsApp Business account that owns the number.
Simple mode shortcut

If you build your agent in Simple mode, you can do this from the agent itself: on the agent's Channels tab, click WhatsApp and run the same Login with Meta sign-in inline. The connection it creates also appears in Settings > Channels.

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

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 and either run Login with Meta (as above) or pick a connection you already created.
  3. 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​

  • Sign-in won't accept the phone number. The number is already registered with a WhatsApp account. Use a different number, or delete the existing account from the WhatsApp app first, then try again.
  • The channel goes to ERROR right after Start. Credentials expired or the number is not fully set up. Open the connection, click Logs for the message, and if a token has expired, reconnect with Login with Meta.
  • 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 can expire and numbers can be disconnected. Check the channel Logs; if the token expired, reconnect the channel with Login with Meta. Confirm the number shows Connected on the Meta side.
  • 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.
  • The Login with Meta button is disabled. The deployment has no shared Meta app. Use WhatsApp (advanced setup) with your own Meta app.

Was this article helpful?