Coming from another official partner (360dialog, Gupshup)
If you already run customers through another official partner, the model is familiar: the business owns the WhatsApp Business account, the number is on Meta’s Cloud API, and you connect a customer through a Meta flow. What changes are the names of things, the webhook and how Meta gets paid. This guide maps them and says what to do with a number that is already at the other partner.
The API reference carries each route’s contract. The other partners’ columns describe, in our own words, what each one’s public documentation shows; if something changed there, their documentation holds.
What changes and what stays the same#
- Stays the same: your customer keeps owning the WhatsApp Business account (the WABA) and their own payment method at Meta. Luna owns none of that.
- How Meta gets paid changes. Luna is a Tech Provider and has no line of credit with Meta, so there is no wallet, balance or top-up. Each business pays Meta directly, and Luna only shows each number’s usage in
GET /v1/usage. You pass that value on to your customer however you see fit, outside Luna. - There is no “client” or “app” object. Your customer is the
externalId, a label you put on the key, the connect link and the endpoint, and which comes back in every event. The instance is the number. - The webhook changes. One endpoint for the whole account (or one per customer with
externalIds), signed delivery, order preserved within each conversation and anevent_idto deduplicate. There are no custom headers on the call: the delivery’s authentication is the signature. See Receive events.
Mapping by partner#
If you come from 360dialog
| 360dialog | Luna |
|---|---|
| A key header, one key per channel | Authorization: Bearer hlsn_.... One key per customer, with externalId and profile: "agent". |
| Send a message | POST /v1/messages: asynchronous 202 and Idempotency-Key. |
| Register the webhook URL per channel, with headers | POST /v1/webhooks/endpoints with url, eventTypes and externalIds. No custom headers; the signature is X-Luna-Signature. |
| List clients | There is no “client” object: the externalId is your customer. |
| List channels | GET /v1/numbers, with the externalId, state and canSend filters. |
| Create a channel’s key | POST /v1/api-keys with externalId. |
| Integration address and a redirect with the client and channels | POST /v1/onboarding/links with redirectUrl, which receives status and numberId in the query. The link is valid for 72 hours. See Connect a number. |
| Channel created event | onboarding.link.completed |
| Channel running event | number.connected |
| Number quality event | number.quality_changed |
| Health state: available, limited, blocked | connection.status and connection.reasons in GET /v1/numbers/{id}, and GET /v1/numbers/{id}/health. See Account health. |
| List, create and delete templates | GET /v1/templates?wabaId=, POST /v1/templates and DELETE /v1/templates/{id}. See Templates. |
| Replicate a template to another customer | There is none. Create the template in each WABA with POST /v1/templates. GET /v1/templates/{id} returns the content and the wabaId, which helps copy by hand. |
| Client balance | GET /v1/usage?numberId=, for display only. There is no balance or top-up. |
| Channel limit | GET /v1/subscription: capacity and capacityLeft. See Plan and numbers. |
| Channel cancellation request | DELETE /v1/numbers/{id}, which triggers number.disconnected. It does not deregister the number at Meta. |
If you come from Gupshup
| Gupshup | Luna |
|---|---|
| Create an app per customer | There is no app: the instance is the number. Create a connect link with POST /v1/onboarding/links. |
| Signed embed link | The connect link: a url with a token, valid for 72 hours. |
| Callback subscriptions per app | POST /v1/webhooks/endpoints. |
| Templates per app | /v1/templates, per WABA. |
| Wallet and balance | It does not exist, by design: each business pays Meta directly. GET /v1/usage only shows usage. |
| Daily usage per app | GET /v1/usage, per number. |
| Business profile and display name | GET and PATCH /v1/numbers/{id}/profile, without the display name. The business sees and requests that name in Meta’s WhatsApp Manager. See Business profile. |
What changes in the webhook#
- Signature. Each delivery carries
X-Luna-Signature: t=...,v1=..., the HMAC-SHA256 oft+.+ raw body. See Verify the signature. - Order and repeats. Order holds within a conversation, and a delivery may repeat. Deduplicate by the stable
event_id. - Which account and which customer. Connection and template events carry the
waba_id, and every event carries thenumberobject with your customer’sexternal_id. You do not need to cross lists to know whose event it is. - Abandoned link. A customer who closes Meta’s window leaves the link
open, withlastFailureandreason: "abandoned". Theonboarding.link.failedevent arrives later.
Moving a number that is already at the other partner#
- The business must own the WhatsApp Business account and have the number released at the previous partner. The prerequisites and the two-step verification PIN are in A number coming from another provider.
- Send the connect link (
POST /v1/onboarding/links). If the number goes toPIN_REQUIRED, give the PIN inPOST /v1/numbers/{id}/pin. A wrong PIN spends one of the registration attempts Meta grants. - Wait for the
number.connectedevent and checkconnection.canSendinGET /v1/numbers/{id}. Only then switch the number off at the previous partner, so you are not left without a channel in the gap. - Switch your system’s webhook: the events and the signature are different, as in the table above.
Capacity and links#
Luna’s plan defines how many numbers you keep active. The connect link does not reserve a slot: if you send more links than there are slots, the last customers are left with the number "connecting" until a slot is free. Before handing over each link, check the slots, as Plan and numbers explains.