Connect your customers' accounts
The Partner API: hosted connect links, external_ref and events, on the same key.
Connect your own customers' numbers from inside your software. The shape is Stripe Checkout: your backend creates a session, you send your customer to a hosted page here, Meta's Embedded Signup runs on it, and the customer comes back to you with a connection id. From then on messages go directly between Meta and your servers; EasyCoexistence only monitors the connection and tells you when it changes.
It is the same API and the same ec_live_ key as the rest of the reference. Every number connected through a session belongs to your account and is billed to it at the normal per-number bands. This page adds the two endpoints that put a customer's account into yours, and what external_ref does afterwards.
Flow
- Your backend:
POST /connect-sessions→{ url }. - Your UI sends the customer to that URL (a redirect or a new tab, never an iframe).
- The customer presses Connect, goes through Meta's popup, scans the QR code with the WhatsApp Business app.
- They land on your
redirect_urlwith?session=…&status=connected&connection_id=…. - Your backend: Get a number with
credentials=1→phone_number_id,waba_id, the customer's token. Send, manage templates and everything else through Meta directly (Messages). - Meta delivers incoming messages to your
webhook_url. EasyCoexistence sends you events.
Create a connect session
POST/api/v1/connect-sessions
Starts a hosted onboarding for one customer. Answers 201 with the URL to send them to.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
redirect_urlrequired | body | https URL | Where the customer lands afterwards, with session, status (connected or cancelled), connection_id (or channel_id) and external_ref in the query string. |
external_ref | body | string, up to 200 | Your id for this customer. Echoed on the connection and on every event; a filter on every list. |
partner_name | body | string, up to 80 | Shown on the hosted page. Defaults to your account name. |
webhook_url | body | https URL | Numbers only. Set on the number the moment it connects, so Meta delivers messages and smb_message_echoes there, plus the one-time import of chat history and contacts. Meta runs a GET handshake first: answer hub.challenge when hub.verify_token matches. Can also be set later. |
webhook_verify_token | body | string, 8 to 200 | With webhook_url. |
channel | body | whatsapp | instagram | facebook | tiktok | whatsapp (the default, a number) or a social network: the hosted page then shows the network's own sign-in, which works on phones too, and the customer comes back with channel_id instead of connection_id. |
Request
{
"redirect_url": "https://app.example.com/whatsapp/return",
"external_ref": "customer_4821",
"partner_name": "ClinicApp",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"webhook_verify_token": "another-long-random-string"
}Response 201
{
"id": "cs_…",
"url": "https://easycoexistence.com/connect/cs_…",
"channel": "whatsapp",
"status": "created",
"external_ref": "customer_4821",
"connection_id": null,
"channel_id": null,
"token_ready": false,
"redirect_url": "https://app.example.com/whatsapp/return",
"webhook_url": "https://hooks.example.com/wa/…",
"last_error": null,
"expires_at": "…",
"opened_at": null,
"finished_at": null
}Sessions expire after 1 hour. An account may hold 50 open sessions and create 100 per hour: Meta counts every first-time onboarding against an app-wide limit that every account shares.
Errors besides the common ones: invalid_request, billing_required, channel_unavailable, rate_limited.
Read a connect session
GET/api/v1/connect-sessions/{id}
status is created, opened, connected, cancelled or expired. token_ready: false on a connected session means Meta finished without issuing the customer's own token (it happens); the hosted page asks for one more run, and if the customer skips it the number receives (the IDs are valid) but cannot send until a new session reconnects it.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | cs_… | The session's id. |
Response 200
{
"id": "cs_…",
"url": "https://easycoexistence.com/connect/cs_…",
"channel": "whatsapp",
"status": "connected",
"external_ref": "customer_4821",
"connection_id": "6f1c…",
"channel_id": null,
"token_ready": true,
"redirect_url": "https://app.example.com/whatsapp/return",
"webhook_url": "https://hooks.example.com/wa/…",
"last_error": null,
"expires_at": "…",
"opened_at": "…",
"finished_at": "…"
}Errors besides the common ones: not_found.
Telling customers apart
external_ref is your id for the customer, given on the session. It comes back on the connection or channel, on every event about it, and as ?external_ref= on every list: numbers, channels, posts, automations. Numbers connected in the dashboard have null.
What the customer sees
A page on easycoexistence.com with your name, a short eligibility checklist (the number must be on the WhatsApp Business app, active, and not on another API provider), one Connect button, Meta's popup, a QR code to scan with the app, then the redirect back to you. No account, no email, no card. The popup names EasyCoexistence as the requesting app; that cannot be white-labelled. Best done on a computer: on phones the popup opens as a new tab and the customer needs the phone free to scan.
With channel set to a social network the page shows "Continue with Instagram" instead, the network's own sign-in, which works on phones too.
Rules for your customers' numbers
- Numbers connected through sessions are yours: billed to you, monitored for you, removable by you.
- Keep to Meta's rules on your customers' behalf (24-hour window, approved templates, no spam, no general-purpose AI bots). Meta's enforcement lands on the customer's WABA and on our app; abuse ends the key.
- 20 messages per second per coexistence number (Meta's fixed limit for Coexistence).
- The 14-day rule applies: a number whose WhatsApp Business app stays closed for 14 days is disconnected by Meta. You get
connection.disconnectedwithPRIMARY_INACTIVITY; the fix is a new connect session for that customer.