Numbers

The console calls these Numbers. The API calls them instance. Same thing, and the mismatch is deliberate: developers know the word instance, and business owners know they are managing a phone number.

Add one

curl -X POST https://njiwa.upeo.ai/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"label": "Invoices", "msisdn": "254700111222"}'

Link it

Three methods. Start one with POST /v1/instances/{id}/link and a strategy, then poll GET /v1/instances/{id}/link.

`qr`	A QR code to scan. Fastest when the phone is in front of you.
`pairing_code`	An 8 character code typed into the phone. Use this when the phone is somewhere else and you are on a call.
`assisted`	For accounts WhatsApp will not link to a server on their own. A person produces a signed assertion in a real browser and pastes it back.

If QR linking keeps failing. WhatsApp can require a passkey signature when a new device is linked, which a headless server cannot produce. That shows up as the connection closing repeatedly during linking. Use the assisted flow.

Status

`created`	Added but never linked.
`linking`	A link is in progress.
`connected`	Live and able to send.
`disconnected`	Dropped. Njiwa reconnects on its own with backoff.
`logged_out`	Removed from WhatsApp on the phone. Link it again.
`banned`	Blocked by WhatsApp. It cannot be recovered.

When a number drops

Njiwa reconnects automatically with exponential backoff, and sends queued in the meantime go out when it returns. If it stays down, POST /v1/instances/{id}/reconnect. If it is logged_out, someone removed the device on the phone and it has to be linked again.

Check numbers are on WhatsApp

curl -X POST https://njiwa.upeo.ai/v1/instances/{id}/check-numbers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["254712345678", "254733000111"]}'