Skip to main content
A connection links one recipient to one agent. Shared-number connections reserve a number from your organization’s shared pool when created through the API. Dedicated-number connections are recorded when the recipient connects through the router or sends their first direct message. The connect API below is for shared numbers and returns the reserved number. Nothing is sent. Your agent can reply after the recipient messages that number.
Connecting through the API requires an organization shared pool, available by request. Contact support@inkbox.ai. Without one, recipients can connect by texting the router.
Paths are relative to https://inkbox.ai/api/v1/whatsapp. Unlike iMessage connect, WhatsApp connect has no first_message field. Shared WhatsApp numbers never start a conversation.

Request headers and retries

Connect and disconnect accept an admin API key or an authenticated Inkbox Console session. Identity-scoped API keys cannot connect or disconnect recipients. Reuse the same key and body when retrying the same action, including after a timeout. A completed request replays its original status and response. Use a new key for each new connect or disconnect action.

Connect a recipient

The identity must belong to your organization and must not have its own dedicated WhatsApp number. Its phone contact rules must allow this recipient. Each pool number serves at most one agent per recipient. Unsupported request fields are rejected.

Response

  • 201: A new connection was created.
  • 200: The agent and recipient are already connected. already_connected is true.
JSON
Share assigned_number, when present, with this recipient only, for example as a https://wa.me/ link. Routing depends on the sender’s number, so other people who message it may reach a different agent or none.

Errors

Connect and disconnect also return these retry errors:

Disconnect a recipient

The request body has the same agent_identity_id and recipient_number fields. Disconnecting ends the current shared or dedicated connection. Conversation history is kept, and the recipient is not notified. A recipient can reconnect through the router. For a dedicated number, a new direct message from that recipient also reconnects them.
JSON
assignment_id is null when there was no connection; that is a successful no-op.

List assignments

Returns the agent’s current shared- and dedicated-number connections, newest first. Any API key or Console session for the organization can read them; an identity-scoped key reads only its own identity.
The response is a JSON array of assignments, not an object containing items. Use limit (default 50, maximum 200) and offset (default 0) for pagination.

Assignment object

Assignments do not expose the shared WhatsApp number. Global shared numbers are also absent from message and conversation local_number fields.

Release an assignment

Requires an admin API key. Returns 204 with no body. Conversation history stays with the agent, and the recipient is not notified.
Python
TypeScript
CLI

Reply through a shared number

Send with POST /messages as usual. For an agent without a dedicated number, the recipient in to, or the conversation’s participant, selects the connection. Before the recipient’s first message on that number, sends return 409:
JSON
Nothing is admitted. Wait for a whatsapp.received event from that recipient before retrying. To attach a file, pass recipient_number when you upload the media. Connection methods are available in the SDKs and CLI from version 0.7.38.