Meta Cloud

Open in CMS

This tutorial walks you through connecting your qlar agent to a WhatsApp Business number using Meta Cloud (Meta's own WhatsApp Business Platform).

The example connects Atlas, Kirana Group's operations assistant, to Kirana's WhatsApp Business number 6281200000000, so site supervisors and field staff can ask Atlas about approvals and site safety from their phones.


Before you start

  • Your agent answers well in Preview and has been published at least once. See Preview and Publish Changes.
  • You have read Connect to WhatsApp, which explains the Published and Draft configurations used below.
  • You use Meta Cloud as your WhatsApp Business provider. If you only want to get your agent on WhatsApp quickly, the Quick Start: Public Server needs no provider account.

From Meta Cloud, make sure you have:

  • A Meta Business Suite account with a verified business.
  • A Meta Developer account at developers.facebook.com.
  • A Meta App with the WhatsApp product (the WhatsApp Business use case) added.
  • A WhatsApp Business Number registered and approved in your Meta App.
  • Access to these values in the Meta Developer Console:
    • Account ID
    • App Secret
    • WhatsApp Number ID (Meta calls it Phone Number ID)
    • Access Token (a permanent or long-lived token)

Tip: The CMS shows where to find each value. Click the info icon (β“˜) next to Account ID, App Secret or Access Token to see a short explanation and a guide image of Meta's screen.


Step 1: Open Channel Settings

  1. Open the CMS dashboard and select the agent you want to connect.
  2. In the left sidebar, open Channels β†’ WhatsApp.
  3. Choose which configuration to set up: Published Configuration (for live users) or Draft Configuration (for testing). Click the corresponding tab.

Note: You can configure both tabs independently. Start with Draft to test first, then repeat the steps for Published when ready to go live.


Step 2: Enter the phone number and click Next

If no WhatsApp number has been connected yet, the Connect WhatsApp wizard appears.

  1. In the Protocol dropdown, select Meta Cloud.
  2. In the Phone Number field, enter your WhatsApp Business number starting with the country code, without + or spaces. For Kirana that is 6281200000000.
  3. Click Next.

Clicking Next creates the configuration right away. There is no separate confirmation. The wizard closes and the configuration screen opens. Its header shows the Active switch, the Notifications button and a β‹― menu, which holds Delete channel. The integration stays inactive in practice until every required field is filled in, so continue with the next steps.

Meta Cloud configuration screen after clicking Next: Meta Cloud label, Active switch, a greyed-out Notifications button and a three-dot menu at the top; Connection & Credentials card with an Edit button, Phone Number 6281200000000, a masked Webhook Secret, a text block with the Phone Number and the Webhook Configuration URL https://api.qlar.ai/messenger/api/MetaCloud/Webhook/6281200000000 to send to the provider, and under API Credentials the empty fields Account ID, App Secret, WhatsApp Number ID and Access Token; Reply Mode with AI agent selected and Redirect to web; Session Management with Ask User to End Session on, Delay Before Ask More 300 seconds, Delay Before End Session 600 seconds, and Discard and Save buttons

The screen has three cards:

CardWhat it holds
Connection & CredentialsThe Phone Number (read-only), the Webhook Secret, a text block with the details to register the webhook, and under API Credentials the Account ID, App Secret, WhatsApp Number ID and Access Token. All are required and kept encrypted at rest. The card is read-only until you click Edit.
Reply ModeAI agent (the agent answers on WhatsApp) or Redirect to web.
Session ManagementWhen an inactive conversation is wound down.

If you entered the wrong number, open the β‹― menu, choose Delete channel… and start the wizard again. The phone number cannot be edited afterwards.


Step 3: Enter the API credentials

Click Edit in the top-right of the Connection & Credentials card. The fields become editable, and Cancel and Save appear at the bottom of the card. Under API Credentials, copy each value from the Meta Developer Console:

  1. Account ID: the ID shown in the Generate Access Token section of your app's WhatsApp Business use case settings.
  2. App Secret: in the first section of the same WhatsApp Business use case settings. The field is masked; click the eye icon to check what you pasted.
  3. WhatsApp Number ID: the Phone Number ID of your WhatsApp Business number, under WhatsApp β†’ API Setup.
  4. Access Token: the token you generate in the Generate Access Token section. Use a permanent or long-lived token, because a temporary token stops working after a short time.
  5. Click Save at the bottom of the card. The CMS asks Save these changes? On the Published Configuration tab it warns instead that the change is applied to the live agent immediately. Click Yes.
  6. A message confirms Connection and credentials saved. The card goes back to read-only.

Cancel discards what you typed and closes the edit. While you are editing, the card shows Unsaved changes next to its buttons.


Step 4: Configure the webhook in the Meta App dashboard

qlar needs Meta to forward incoming messages to qlar's servers. This is done through a webhook.

  1. In the Connection & Credentials card, the Webhook Secret is already filled in. Click the eye icon to show it and the copy button to copy it. To generate a new secret, click Edit, then the refresh icon next to the label, then Save.
  2. Below the fields, qlar shows a text block with your Phone Number and the Webhook Configuration URL, for Kirana https://api.qlar.ai/messenger/api/MetaCloud/Webhook/6281200000000. Use the copy button in the corner of the block to copy both. If someone else manages your Meta App, send them this block by email.
  3. In your Meta App dashboard, open WhatsApp β†’ Configuration β†’ Webhook.
  4. Click Edit and fill in the fields:
    • Callback URL: paste the Webhook Configuration URL from qlar.
    • Verify Token: paste the Webhook Secret from qlar.
  5. Click Verify and Save. Meta sends a verification request to qlar.
  6. Under Webhook Fields, subscribe to at least messages so qlar receives incoming user messages.

Warning: Do not share the Webhook Secret publicly. If the secret is compromised, regenerate it in qlar and click Save, then update the Verify Token in your Meta App immediately.


Step 5: Choose the reply mode and session settings

  1. Under Reply Mode, keep AI agent so Atlas answers directly on WhatsApp. Redirect to web sends every private message an instant one-time sign-in link to the agent's web chat instead, and no AI runs on WhatsApp. See WhatsApp in Help for its settings.
  2. Under Session Management, keep the defaults unless you have a reason to change them: Ask User to End Session on, Delay Before Ask More 300 seconds, Delay Before End Session 600 seconds. See Session Management.
  3. If you changed anything in Session Management, click Save at the bottom of that card and confirm. Its Discard button puts the saved values back.

Each card saves only its own fields, so saving Session Management never sends a half-finished edit in another card.


Step 6: Publish

Saving marks your agent as having unpublished changes, so the Publish button appears at the top of the CMS. Click Publish so the connection is synced to the live version of your agent.

The Notifications button at the top of the screen opens the notification settings for this number. It stays greyed out until every required field is saved, and while Connection & Credentials is being edited. Hover over it to see what is still missing.


Check the result

To verify the connection is working:

  1. From a personal WhatsApp account, send a test message to your WhatsApp Business number, for example Who has to approve a project worth $2.5 million?
  2. The message should appear in your agent's conversation history in the CMS dashboard.
  3. Your agent should respond automatically, with the same kind of answer it gives in Preview.

Tip: If messages are not arriving, check that the Active switch is on, that every field under API Credentials is filled in and saved, that the Callback URL and Verify Token match exactly between qlar and your Meta App dashboard, and that the messages webhook field is subscribed.


Next steps