Numbers
Status and sending health, credentials, the monitoring timeline, where messages go, removal.
A number is a WhatsApp Business number running Coexistence: the business keeps the phone app, and your backend uses the Cloud API on the same number. EasyCoexistence connects it, watches it and hands you its credentials; it is never in the message path.
Numbers connected in the dashboard and numbers your customers connect through a connect session look the same here; the second kind carries the customer's external_ref.
List numbers
GET/api/v1/connections
Every number on the account, newest first.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
external_ref | query | string | Partners: keeps the ones a customer connected, by the external_ref of their connect session. |
include_removed | query | 1 | Includes removed ones. |
Response 200
{
"data": [
{
"id": "6f1c…",
"external_ref": null,
"phone": "+55 11 9…",
"name": "Bloom Café",
"waba_id": "…",
"phone_number_id": "…",
"status": "connected",
"quality_rating": "GREEN",
"messaging_tier": "TIER_1K",
"sending_health": "AVAILABLE",
"sending_block_code": null,
"sending_blocked_since": null,
"token_ready": true,
"inbound_mode": "direct",
"webhook_url": "https://hooks.example.com/wa/…",
"created_at": "2026-10-02T14:05:11.000Z"
}
]
}status: connected, degraded, disconnected, banned, suspended, removed, unknown.
sending_health is Meta's answer to "can this number start conversations?": AVAILABLE, LIMITED or BLOCKED (null until the first check). A connected number can still be BLOCKED: Meta then accepts template sends and fails them later. sending_block_code says why; 141006 is a missing payment method in WhatsApp Manager, the usual one.
inbound_mode is direct (Meta delivers to your webhook_url) or managed (messages reach EasyCoexistence first, for automations).
Get a number
GET/api/v1/connections/{id}
One number. With credentials=1, also what your backend needs to call Meta.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
credentials | query | 1 | Adds credentials: Meta's Graph API base, the send endpoint and the number's own token. |
Request
curl "https://easycoexistence.com/api/v1/connections/<id>?credentials=1" \
-H "Authorization: Bearer ec_live_..."Response 200
{
"id": "6f1c…",
"external_ref": null,
"phone": "+55 11 9…",
"name": "Bloom Café",
"waba_id": "…",
"phone_number_id": "…",
"status": "connected",
"quality_rating": "GREEN",
"messaging_tier": "TIER_1K",
"sending_health": "AVAILABLE",
"sending_block_code": null,
"sending_blocked_since": null,
"token_ready": true,
"inbound_mode": "direct",
"webhook_url": "https://hooks.example.com/wa/…",
"created_at": "2026-10-02T14:05:11.000Z",
"credentials": {
"graph_api_base": "https://graph.facebook.com/v25.0",
"send_endpoint": "https://graph.facebook.com/v25.0/<phone_number_id>/messages",
"access_token": "EAAG…"
}
}The token is the business's own, scoped to its assets, returned only when token_ready is true. The EasyCoexistence system token is never exposed. Store it on your side and send with it directly; see Messages.
Errors besides the common ones: not_found.
Monitoring timeline
GET/api/v1/connections/{id}/events
What happened to the number, newest first: what Meta reported (source: "webhook"), what our checks saw (poller) and what was done to it (dashboard, mcp, api).
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
limit | query | 1..100 | Default 50. |
before | query | ISO date | Entries before this moment: the next page. |
Response 200
{
"data": [
{
"id": "…",
"type": "sending_restored",
"source": "poller",
"summary": "Meta is delivering business-initiated messages again",
"created_at": "…"
},
{
"id": "…",
"type": "sending_blocked",
"source": "poller",
"summary": "Meta is not delivering business-initiated messages (141006)",
"created_at": "…"
}
]
}Errors besides the common ones: not_found.
Where messages go
PUT/api/v1/connections/{id}/webhook
Routes Meta's message webhooks for this number to your URL. Meta runs its GET handshake right away and the change is refused when it fails; the response carries Meta's message.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
urlrequired | body | https URL or null | Your endpoint. null resets to none. |
verify_token | body | string | What your endpoint answers Meta's hub.verify_token with. Required with a URL. |
Request
{
"url": "https://hooks.example.com/wa/<long-random-secret>",
"verify_token": "another-long-random-string"
}Response 200
{
"webhook_url": "https://hooks.example.com/wa/…",
"note": "Meta signs these calls with easyCoexistence's app secret… authenticate with the secret in the URL path."
}Setting a URL on a managed number makes it direct again: Meta then delivers to you only and its automations stop. Deliveries are not signed for you; see Receiving messages.
Errors besides the common ones: not_found, meta_rejected.
Read the inbound mode
GET/api/v1/connections/{id}/inbound
mode, and for a managed number its forward_url. The secret is never read back.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
Response 200
{
"connection_id": "6f1c…",
"mode": "managed",
"forward_url": "https://hooks.example.com/messages",
"webhook_url": null
}Errors besides the common ones: not_found.
Set the inbound mode
PUT/api/v1/connections/{id}/inbound
managed makes Meta deliver the number's messages to EasyCoexistence, so its automations run; direct sends them straight to your webhook_url again and stops them. A managed number can still forward every message to you.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
mode | body | managed | direct | Leave out to keep it. |
forward_url | body | https URL or null | Managed only: each message is forwarded here with Meta's original payload. null stops. |
rotate_secret | body | true | Mints a new forwarding secret. |
Request
{
"mode": "managed",
"forward_url": "https://hooks.example.com/messages"
}Response 200
{
"connection_id": "6f1c…",
"mode": "managed",
"forward_url": "https://hooks.example.com/messages",
"webhook_url": null,
"forward_secret": "whsec_…",
"secret_note": "Shown once…"
}forward_secret is answered the first time only. Each forwarded call carries X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">, made as in Events.
Errors besides the common ones: not_found, not_managed.
Remove a number
DELETE/api/v1/connections/{id}
Revokes our access at Meta, stops monitoring and stops billing at the end of the cycle. The number stays on the Cloud API until the business disconnects it in the WhatsApp Business app (Settings → Account → Business Platform).
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The number's id. |
Response 200
{
"removed": true,
"billing_stops_at_period_end": true,
"note": "The number keeps working on the Cloud API until the customer opens the WhatsApp Business app: Settings > Account > Business Platform > Disconnect Account."
}Errors besides the common ones: not_found, removed, revoke_failed.