Quickstart

Connect your existing WhatsApp Business number and send your first message through the API, without taking the number off the phone your team already uses.

Five minutes, four steps, and nothing on the phone changes. At the end of it the same number is answering in the WhatsApp Business app and reachable from an API.

1. Connect the number

Connecting runs through Embedded Signup, Meta’s own hosted dialog, and it is the only sanctioned path for a coexistence number. The number is already registered to the app, so the registration step every other WhatsApp API onboarding makes you do is skipped — there is no QR code and no re-registration.

You enter the number on a laptop; the rest happens on the phone:

Enter the WhatsApp Business app’s phone number in the dialog.
A message arrives from the official Facebook Business Account. Tap Connect.
Tap Connect to the Business Platform to continue.
Tap Confirm to share chat history. This one is optional and it is the only step you cannot redo later — see below.
Copy the verification code from the app and paste it back into the dialog.

Step 4 is the one to get right. It is the consent that lets up to 180 days of prior conversations import, and the import runs once, within 24 hours of onboarding. Decline it and the inbox starts empty; there is no second attempt.

2. Create a key

A connection key grants exactly one connection, and it is the only credential the Runtime API accepts. Create one in the dashboard; the full string is shown once and stored hashed, so if you lose it you rotate rather than recover it.

Authorization: Bearer csk_live_…

Use a csk_test_ key against a test connection while you are wiring things up. The credential is the mode — there is no header to set and therefore none to forget in production.

3. Send a message

Two ways, and they are for different situations.

If you already have Graph API code, change the hostname and the token and stop:

POST https://api.cosend.app/v26.0/{phone_number_id}/messages
Authorization: Bearer csk_live_…
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "+919876543210",
  "type": "text",
  "text": { "body": "On our way." }
}

The version segment is yours: send v25.0 and we forward v25.0. The response is Meta’s, byte for byte, including its error envelope.

If you are starting fresh, /v1 is the friendlier surface — one host, no version segment, and the connection comes from the key:

POST https://api.cosend.app/v1/messages
Authorization: Bearer csk_live_…
Idempotency-Key: 8f14e45f-ea4e-4c1d-9d3a-2b6f0a1c77de
Content-Type: application/json

{
  "to": "+919876543210",
  "type": "text",
  "text": { "body": "On our way." },
  "metadata": { "order_id": "4821" }
}

Idempotency-Key is required on every send. A retried send without one is a duplicate message to a real person, so the API refuses rather than guesses. metadata is stored and echoed back on webhooks and is never sent to Meta.

4. Receive the reply

Point a webhook endpoint at your service and you get the reply, the delivery statuses, and — the part only coexistence gives you — an echo of anything your team sends from the phone.

Every delivery is signed, and the signature is verified against the raw body before parsing. There are two schemes and which one you get depends on the delivery mode you chose. The webhook reference has both, with the verification code.

What goes wrong first

Four, in the order a first integration hits them. Each links to the full entry:

missing_credential — no Authorization header at all.
idempotency_key_required — a send on /v1 without a key.
service_window_closed — a free-form message more than 24 hours after the customer’s last one. Use an approved template to reopen the conversation.
not_supported_on_coexistence — groups, calls and catalog messages. Your catalog keeps working in the app; the API cannot send catalog messages on a coexistence number.

Every error carries a request_id, and the same value is in our logs. Quote it and support starts at the right request rather than at the right hour.