WhatsApp in a project: connecting through the Cloud API

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

10 মিনিটে পড়া

WhatsApp in a project: connecting through the Cloud API

The WhatsApp channel works the same way as Telegram and MAX: a customer writes to your business number, a request appears in the project's requests, and an agent replies from there. There's one difference: you register the number yourself on Meta's WhatsApp Business Platform (Cloud API), and in Sensever you paste details from your Meta dashboard — the Phone number ID, a permanent token, the App secret, a PIN and, optionally, the WhatsApp Business Account ID. The token and secret are stored encrypted and aren't shown again.

What you'll need

  • A phone number that isn't used in regular WhatsApp or in the WhatsApp Business app: when you register it in the Cloud API, the number is unlinked from the app.

  • A personal number for testing — you'll send the first message from it.

  • A verified Meta business portfolio (Business Manager). Without business verification, Meta keeps the number in test mode with a limit on recipients.

  • Owner or administrator rights in the Sensever project.

Connecting

  1. Meta app. On developers.facebook.com/apps, click "Create app" and choose the "Connect with customers through WhatsApp" use case. If you already have an app (for example, for Instagram), open it → Use cases → Add use case → the same use case.

  2. Number. In the WhatsApp use case, open API Setup → "Add phone number": enter the number and confirm it with a code from an SMS or a call. The Phone number ID appears in the list — a long number next to the phone number. It isn't the phone number itself or the WhatsApp Business Account ID: that one is shown next to the account name. If you paste the account ID, Sensever responds with "The messenger didn't accept the token".

  3. WhatsApp Business Account ID. On the same API Setup page, next to the account name. The field is optional in Sensever, but with it Sensever links your app to the account on its own — without this, Meta may not send calls.

  4. Permanent token. The temporary token from API Setup lasts 24 hours and won't work. In Business Settings → Users → System users, create a system user with the Admin role, assign it the app and the WhatsApp Business Account, then Generate token → choose the app, the "Never" expiration and the whatsapp_business_messaging and whatsapp_business_management permissions. The token is shown only once — copy it right away.

  5. App secret. App → App settings → Basic → App secret → Show. Meta uses it to sign every incoming message, and Sensever checks the signature so that no one can write on behalf of your customer.

  6. Two-step verification PIN. The six digits that protect the number. If two-step verification was already turned on (WhatsApp Manager → Phone numbers → the number → Two-step verification), you need exactly that PIN; if you've forgotten it, change it in the same place. If it was never turned on, come up with six digits and write them down: Sensever sets them when it activates the number.

  7. Sensever. Projects → the project → "Channels" → the "Messaging channels" block → "Connect" on the gray WhatsApp tile. Paste the Phone number ID, WhatsApp Business Account ID, permanent token, App secret and PIN, choose a department and click "Connect". Sensever registers the number in the Cloud API (if it isn't registered yet) and subscribes your app to the WhatsApp Business Account on its own. The tile shows "Waiting for the first request from Meta" — that's expected.

  8. Webhook. Click the gear on the WhatsApp tile and, in the "Webhook details for the Meta dashboard" block, copy the Callback URL and Verify token with the "Copy" buttons. In the Meta app: WhatsApp → Configuration → Edit → paste both values → Verify and save. Then, in the same section (Webhook fields), subscribe to the messages, phone_number_name_update and calls fields. The second one makes the display name approved by Meta appear in Sensever right away; the third one is for calls.

  9. Test. Write to the business number from your personal phone. A request appears in the project's requests, the tile status changes to "Connected", and the WhatsApp button appears in the website widget (if "Show in widget" is selected).

If Meta still hasn't sent the first request an hour after you saved, the "Sensever Channels" bot reminds you that the webhook isn't saved.

What gets delivered

  • From the customer: text, photos, videos, documents, voice messages, stickers, locations, contacts, button replies, reactions. Files larger than 20 MB aren't uploaded — the customer gets a request to send a link instead.

  • To the customer: text, reactions and files. Photos up to 5 MB, video and audio up to 16 MB, and documents up to 100 MB (with the file name) are sent as files; anything WhatsApp doesn't accept is sent as a link that's valid for 48 hours. WhatsApp doesn't allow editing or deleting a sent reply.

  • While an agent is typing a reply, the customer sees a typing indicator; WhatsApp then immediately marks the customer's message as read.

  • If the customer replied to a specific message, the request shows it as a reply.

  • Read receipts work both ways: the agent sees that the customer has read the reply, and the customer sees blue checkmarks when the agent has read their message.

  • If Meta accepted a reply but couldn't deliver it, the message in the request is marked as undelivered.

Message templates

After the 24-hour window, WhatsApp delivers only a message template approved by Meta in advance. Templates are useful earlier too: to remind about an order or confirm an appointment.

Where to see them. The gear on the WhatsApp tile → the "Message templates" block: all of the account's templates with their language, category, text and status — "Approved", "Awaiting review", "Rejected" (with Meta's reason), "Paused", "Disabled". The "Refresh" button reloads the list.

How to create one. The "Create template ↗" button in the same block opens WhatsApp Manager for your account. Create a template; variables in the text are written as {{1}}, {{2}} — Sensever asks you to fill them in when sending. Meta usually reviews a template within anywhere from a few minutes to 24 hours.

How to send one.

  1. In a WhatsApp request, click the templates icon next to the paperclip — or the "Send template" link under a reply that wasn't sent because the window was closed.

  2. At the top, you can see whether the reply window is open and until when.

  3. Choose a template, fill in the variables and check how the customer will see the message.

  4. Click "Send template". It appears in the request as a regular message with that text and a delivery status.

From your server. Your server can send an approved template to any phone number, even one that has never written to the project: Sensever starts the conversation and the customer's answer arrives in the requests. See "WhatsApp API: the first message to a customer with an approved template".

Limitations. From a request, you can send templates that are filled in with text. Templates with an image, video or document in the header, and templates with variables in buttons, can't be sent yet — they're marked in the settings. Templates require the WhatsApp Business Account ID in the channel settings. Meta charges for templates according to its own rates.

WhatsApp calls

Customers can call your number right from WhatsApp — the call rings for everyone who can reply in the customer's request. Agents can call customers themselves if the customers have allowed it.

For calls to work:

  • the webhook settings in the Meta app must include a subscription to the calls field;

  • the WhatsApp Business Account ID must be set in the channel settings;

  • Meta allows calls only for numbers with a limit of at least 2000 business-initiated conversations per 24 hours and an approved display name.

The settings are under the channel's gear, in the "WhatsApp calls" block: accept calls on this number, show the call button in the WhatsApp chat, ask the customer for permission to call back after a call, and accept calls only during business hours (with a time zone).

Calls from customers are free. Meta charges per minute for calls to customers, based on the customer's country. Answer calls or turn them off: Meta restricts numbers with many missed calls. If SIP is turned on for the number in Meta, calls go to your SIP server and don't reach Sensever.

Limitations worth knowing in advance

  • 24 hours. WhatsApp allows free-form replies only within 24 hours of the customer's last message. After that, Meta rejects the reply, the agent sees "Not sent: in WhatsApp you can reply only within 24 hours of the customer's message", and the message isn't sent. After the window, you can send the customer an approved template — see the "Message templates" section.

  • One number, one project. The same number can't be connected to a second Sensever project.

  • WhatsApp Business app. A number running through the Cloud API isn't available in the WhatsApp Business mobile app. Coexistence mode, which lets you use both, isn't supported yet.

  • Billing. Meta charges for conversations under its own rules and bills you directly; Sensever isn't involved in the payments.

If something goes wrong

  • WhatsApp or Meta says the number needs to be activated through the API, or the "Sensever Channels" bot reported that the number was deregistered — the number isn't registered in the Cloud API. Click the gear on the channel, enter the PIN and click "Save". You don't need to re-enter the token and secret: they're saved and shown by their first characters.

  • "The PIN didn't match" — the number has a different two-step verification PIN. Enter it or change it in WhatsApp Manager.

  • "Meta has temporarily limited registration attempts" — Meta allows 10 number registrations per 72 hours. Sensever doesn't re-register an already activated number, but attempts with a wrong PIN count too. Wait and try again.

  • The "Waiting for the first request from Meta" status persists — the webhook isn't saved (step 8) or the messages field isn't selected. Check that the Callback URL was copied in full and that the Verify token matches.

  • "The messenger didn't accept the token" — the temporary token expired, the token was issued for a different app, or the system user has no rights to this number. Generate a permanent token again, click the gear, then × next to the token field, and paste the new one.

  • "Meta has restricted the WhatsApp Business account" — a block, a billing problem or a policy violation. Check "Account quality" and the payment method in Meta Business Suite.

  • Messages stopped arriving after the App secret changed — paste the new secret through the gear (× next to the secret field). Sensever notices a foreign signature within a few minutes and sends a notification.

Other situations are covered in the article "Messaging channels: when messages don't arrive or aren't sent".

Channel name and customer names

Sensever checks the channel name (the WhatsApp number's display name) against Meta every 6 hours. The "Refresh channel data" button on the tile does it right away. A name approved by Meta also arrives without waiting if you're subscribed to the phone_number_name_update field.

A customer's name is updated with each of their messages: if the customer changed their name in WhatsApp, the request shows the new name.

The "On / Off" switch on the tile stops receiving and sending while keeping the request history; turning it back on reconnects the channel with the saved details. "Remove bot" also erases the saved token and secret. The number itself stays yours in Meta in both cases. Other common settings — showing in the widget, button order, notifications — are described in the article "Project messaging channels: messengers in Requests".

মন্তব্য

লেখকগণ