WhatsApp channel setup

What the WhatsApp channel does

The WhatsApp channel lets your customers chat with one of your customer products on your own WhatsApp Business number. It uses Meta's WhatsApp Cloud API directly, with no reseller in between. The channel is in Beta.

A customer's message reaches the product's front agent, with the same tools, budget and rules your app's chat gets. Three things are always true:

• Only linked customers get answers about their account. A number that is not linked to a signed-in customer gets one message telling them how to link it in your app, and nothing else.
• A chat reply never confirms money or a commitment. A payment, a transfer or anything else that commits the customer is confirmed in your app, behind your own OTP or biometric step-up. The chat sends a link to that confirmation.
• The customer controls the conversation. STOP turns messages off and START turns them back on.

Before you start: what to set up at Meta

You need these from Meta Business Suite and the Meta for Developers site. Your bank's Meta admin usually does this once.

1. A verified Meta Business portfolio (business verification done).
2. A Meta app of type Business, with the WhatsApp product added.
3. A WhatsApp Business Account (WABA) with your phone number registered and its display name approved. Note the phone number ID and the WhatsApp Business Account ID from WhatsApp, API setup.
4. A system user in Business settings with the whatsapp_business_messaging and whatsapp_business_management permissions, assigned to the app and to the WABA. Generate a permanent access token for it. Do not use the 24-hour test token.
5. The app secret, from the app's Settings, Basic page.

Connect the number

1. Open Launch, choose the product, and press Set up WhatsApp.
2. Enter the phone number ID, the WhatsApp Business Account ID, the access token and the app secret, then press Connect.
3. The page now shows a callback URL and a verify token. In your Meta app, open WhatsApp, Configuration, Webhook, press Edit, and paste both. Meta checks them straight away.
4. In the same place, subscribe to the messages field.
5. Make sure the WABA is subscribed to your app. If messages do not arrive, call POST /<WABA ID>/subscribed_apps once with the system user's token.
6. Press Test connection. It reads the number's name and quality rating from Meta and sends no message.

The access token and app secret are stored encrypted. The page only shows whether each is set and the token's last four characters. To replace one, type the new value and press Save; leave a field empty to keep the stored one.

Every webhook delivery is checked against your app secret (X-Hub-Signature-256) before anything is read. A delivery with no signature, a wrong signature, or a number no workspace has connected is refused. A delivery Meta sends twice is handled once.

Link customers

A WhatsApp number is never trusted to be a customer by itself. Your app links it, in one of two ways.

A link code (recommended). When a signed-in customer taps "Chat on WhatsApp" in your app, your app calls:

POST /api/launch/v1/whatsapp/links
{ "endUserId": "<the end user id from POST /users>" }

It gets back a code such as K7Q2-M9XD, valid for 10 minutes and usable once, and a wa.me link that opens WhatsApp with LINK K7Q2-M9XD typed. When the customer sends it, that number is linked. Five wrong codes from one number in a day stop further tries until the next day.

The wa.me link needs the number's display number, which Test connection reads from Meta. Run the test once after connecting.

Your registered mobile number. If your records hold the customer's verified mobile number, your app can link it directly:

POST /api/launch/v1/whatsapp/links
{ "endUserId": "...", "phone": "+919800000000" }

WhatsApp verified the number's owner when the account was made. If a number is recycled to someone else, a direct link would reach the new owner, so keep your registered numbers current or use link codes.

To unlink, call DELETE /api/launch/v1/whatsapp/links with the endUserId. A blocked end user gets no answers on any channel.

Payments, commitments and buttons

When the agent proposes an action, the customer confirms it one of two ways.

• In your app (always for money and commitments). The reply carries a link to your confirmation page with ?proposal=<id>. Your app opens it signed in and reads the proposal:

  GET /api/launch/v1/whatsapp/proposals/<id>?endUserId=...
  

  It runs your step-up, carries out the action, posts its audit event to /api/launch/v1/audit as usual, and closes the proposal:

  POST /api/launch/v1/whatsapp/proposals/<id>
  { "endUserId": "...", "outcome": "confirmed" }
  

• With a WhatsApp button (only protective actions you allow). Under Confirm in chat you can allow actions that protect the customer, such as blocking a card. The customer then gets Confirm and Cancel buttons. When they press Confirm, your webhook endpoint receives the signed event whatsapp.action.confirmed, and your backend carries out the action. Add the endpoint under Settings, API, Webhooks.

Typing "yes" never confirms anything. A button press is accepted only from the same customer, within 15 minutes, for an action you still allow. Payments and commitments cannot be allowed for chat.

The 24-hour window and templates

WhatsApp lets a business reply freely for 24 hours after the customer's last message. After that, only an approved message template may be sent.

• Replies to a customer who has just written always go, even in quiet hours.
• Your app can send a message with POST /api/launch/v1/whatsapp/messages {"endUserId", "text"}. Inside the window the text is sent. Outside it the call is refused with window-closed, unless you add "reengage": true. That sends your approved Chat: invite to reply template instead, and not your text.
• Create that template in WhatsApp Manager and wait for Meta to approve it. Then save it under Retail, Follow-ups, Templates with the kind Chat: invite to reply (WhatsApp), and have head office approve it. Its parameters can use firstName, store (the product name) and topic. Put "Reply STOP to opt out" in the approved text.
• Templates go only to customers who linked through your app or whom you linked by registered number.

Consent, quiet hours and limits

• Consent. Linking records the customer's opt-in with your consent text version, which you set on the page. A number that writes in without linking is recorded as a conversation-only opt-in.
• STOP and START. STOP, UNSUBSCRIBE or OPT OUT stops every message except one acknowledgement. START or SUBSCRIBE turns messages back on. Each change is recorded in the audit log.
• Quiet hours. Set a start, an end and your time zone. Templates are not sent inside quiet hours.
• Limits. Messages a day and templates a day cap what the number sends (templates are what Meta charges for). Messages per customer an hour stops a flood: past it, the customer gets one notice and nothing runs until the hour turns. Every agent turn also counts against the product's own budget.

What is kept, and what never is

• Never in chat: a customer who types something that looks like a PIN, OTP, CVV or password is told not to share it. The message is not passed to the agent. Agent replies never show a full account or card number; long numbers are shown as their last four digits.
• Kept: one record per message in and out (its type, status, Meta's delivered, read and failed callbacks, and why anything was refused), for a year. The text itself is kept only on the agent's run, like every other product chat. Numbers are stored encrypted and looked up by a keyed hash.
• Voice notes and images: the chat reads text only for now. A voice note's reference is kept and the customer is asked to type.

Disconnect

Press Disconnect to stop the channel. The stored token, app secret and verify token are removed, and the message history is kept. Customers who write afterwards get no answer until you connect again, which makes a new verify token to paste into Meta.