WhatsApp Business Account

WhatsApp sends from a WhatsApp Business Account (WABA) you connect through Meta's embedded signup. You sign in with Meta, Samva receives the account's access through that flow and stores it encrypted, and the first account you connect becomes your default sender. You never copy or paste an access token.

createClient() has no whatsapp namespace. Connect and manage WABAs in the dashboard or through the HTTP routes below. Sending still goes through POST /v1/messages with channel: "whatsapp".

Connect a numberCopy Anchor Link

Open the WhatsApp page in the dashboard and choose to connect a number. Meta's signup window walks you through choosing or creating a business portfolio and WhatsApp Business Account, adding a phone number, and verifying it. When you finish, Samva exchanges the result for access to that account, subscribes to its webhooks, and registers the number for sending.

Keep using the WhatsApp Business appCopy Anchor Link

If the number is already in the WhatsApp Business app, the signup window offers to keep using the app alongside Samva. Choose it and Samva connects the number without a two-step verification PIN or re-registering it, then asks Meta once for your saved contacts and your past chats.

• Messages you send from the app appear in the customer's conversation and mailbox thread as sent messages from the Business app. They are free and do not open or extend the customer's 24-hour service window. A new reply from the app or a supported companion pauses the hosted agent in that mailbox's conversation with the contact across all channels until you hand it back or the takeover timeout passes without another staff reply. Receiving the same reply again does not extend the pause.
• Past chats import ahead of new messages, up to six months, without notifications. The account shows the import as requested, importing, completed, or declined if the customer declined to share history. Imported chats do not pause the agent or interrupt an active turn. Contacts saved in the app become Samva contacts with the same name. Groups do not sync.
• If the app is removed from the number or the number is offboarded, sending from Samva stops until you reconnect.

Meta requires WhatsApp Business app 2.24.17 or later and caps the number at 20 messages per second. Disappearing and view-once messages, live location, broadcast lists (read-only), greeting and away messages, quick replies, labels, calls, catalog and orders, status, and Channels do not carry over, and the Windows and WearOS companion apps are unsupported. The Meta app must subscribe to the history, smb_app_state_sync, and smb_message_echoes webhook fields.

The connect route behind the dashboard takes the code, wabaId, and phoneNumberId that embedded signup returns. It is built for the signup flow, so a script cannot supply them by hand:

curl -X POST https://api.samva.dev/v1/whatsapp/business-accounts \
  -H "X-API-Key: samva_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "code": "AQB...", "wabaId": "100123456789", "phoneNumberId": "1234567890" }'

The response includes the account's verificationStatus, qualityRating, messagingLimit, and businessPortfolioId.

Status, quality, and limitsCopy Anchor Link

A number that connects as pending cannot send yet. Finish its verification in WhatsApp Manager, then sync the account (the dashboard's sync action or the route below); Samva registers the number once Meta reports it verified. Samva also updates quality, the messaging limit, and suspension as Meta reports them.

Meta sets the messaging limit for a business portfolio, and every number in the portfolio shares it. Samva counts the template conversations of all of them against it, so a second number in the same portfolio does not add room. Until Meta reports which portfolio owns an account, the account counts as its own portfolio. When Meta raises the limit, Samva applies it at once and resumes the campaign runs and journey runs the old limit was holding.

Replies inside a customer's 24-hour service window do not count toward the messaging limit.

Restore account accessCopy Anchor Link

Account access tokens last 60 days, and Samva renews them automatically well before they expire. If Samva cannot renew access, it warns your organization's owners and admins by email and shows a dashboard warning 14 days before access expires. Reconnect at any time to renew access; sending continues until the expiry date.

When access expires or Samva detects revoked access, the dashboard shows Reconnect required. Sending from that number is blocked until you restore access. This is separate from the number's verification, quality, and messaging limit; syncing cannot renew account access.

Choose Reconnect number and complete Meta's signup window with the same WhatsApp Business Account and phone number. Samva restores access on the existing account, keeping its identity, default-sender setting, and message history. You do not need to disconnect the number first. Before a warning appears, choose Connect number and select the same account and number to renew access.

Manage accountsCopy Anchor Link

Disconnecting stops sending and receiving through the number. The dashboard labels it Disconnected and excludes it from connected and registered counts. It does not delete the data Samva stores for the account; Data Deletion explains how to delete it.

Choose Reconnect number on a disconnected row to resume sending and receiving. When account access is still valid, this syncs and reactivates the number without opening signup. It becomes the default only if its organization or namespace has no active default. Expired or revoked access requires the signup window described above.

POST /v1/whatsapp/business-accounts/:id/sync refreshes the quality rating, messaging limit, and verification state from Meta, registers a verified number, and reactivates a disconnected account. If you delete and re-add the same number in WhatsApp Manager on the same WhatsApp Business Account, sync finds its new phone number ID and registers it with the stored PIN. If the number is no longer on that account, sync asks you to reconnect through signup.

With a default account connected, create your templates and send.