Skip to main content
Create a 1:1 connection with an optional opening message. You choose the agent identity and recipient. Inkbox chooses the sending number from your organization’s pool. API base URL:
Both endpoints accept an admin API key or an authenticated Inkbox Console session for your organization. Identity-scoped API keys cannot connect or disconnect recipients. The examples below use an admin API key.

Request headers and retries

For API-key authentication: Generate a random UUID before the first request. Reuse that key and the same body when retrying the same action, including after a timeout. A completed request replays its original status and response without repeating the action. Unlike the optional retry mode on message sends, these endpoints do not require a Prefer header. Use a new key for each new connect or disconnect action. Reconnecting after a disconnect is a new action: replaying an old connect key returns the old result and does not reactivate the connection. Keys are scoped to your organization, agent identity, and operation: connect and disconnect have separate scopes. After an action commits, reusing its key with different input returns 409 with error: "idempotency_key_reused". Admission rejections do not save a completed result; fix the cause and retry. A timeout does not prove that an action failed to commit, so retry an uncertain action with the original key and body.

Connect a recipient

Beta — available only by request to organizations with their own organization-owned shared iMessage pool. Contact support@inkbox.ai to request access. Standard shared service requires the recipient-initiated router flow. Organizations with a pool can also use a router; router-created connections can use their pool numbers.
The identity must belong to your organization and have imessage_enabled: true. Its contact rules must allow this recipient in both inbound and outbound directions. Connecting does not change those rules. For a new connection, Inkbox assigns an eligible pool number and, if supplied, accepts the opening message together. A rejected request creates neither a new connection nor an opening message. There is no waiting list for requests that cannot be admitted; your application handles retries.

Request body

There is no sending-number parameter. Unsupported request fields are rejected. Without first_message, the response includes the assigned number and message: null. Give the recipient that number so they can message first. Creating a connection does not reserve capacity for a later send. With or without an opening message, further sends require a direct message from the recipient on this connection. Messages from a previous connection and tapbacks do not satisfy this requirement. After the recipient messages, normal sending limits still apply. For an opening message to a number the recipient has not previously messaged, use fewer than 160 characters of plain text (159 maximum), without links, phone numbers, or media. A prior direct message to that number during your organization’s ownership satisfies the opening-message content requirement, but does not unlock follow-up sends on a new connection. A reply on another number does not count. Connect accepts text only.
bash
Generate your own key rather than reusing the example value for multiple actions.

Connect without sending

Omit first_message to assign a number without sending an opening message:
bash
A new connection returns 201 with assigned_number, conversation_id, already_connected: false, and message: null. Ask the recipient to message the returned number. Until they do, ordinary message sends return 409 imessage_awaiting_inbound. Calling connect again with first_message does not send a delayed opener for an already-active connection. It returns 200 with already_connected: true and message: null.

Response

  • 201: A new connection was created. If supplied, its opening message was accepted, not necessarily delivered. Otherwise, message is null and nothing was sent.
  • 200: The identity and recipient already have an active connection. already_connected is true, message is null, and no greeting is sent. Existing connections stay on their current number, including connections created through the standard shared service.
Example new-connection response (201, selected fields):
JSON
Example already-connected response (200):
JSON
An idempotency replay returns the original status and body, rather than checking the connection’s current state again. Responses saved before assigned_number was introduced can omit that field. Use assigned_number for a “Text your agent” button or a QR code in your application. It is the agent-side number, not recipient_number. For a shared pool, show the button or QR code only to the connected recipient: routing depends on their sending number, and other senders may reach a different agent or have no connection. It is not a public contact number for this agent. The number can change after disconnecting and reconnecting. Omit first_message to let the recipient start the conversation on the returned number. Existing personal dedicated-line connections also return their number; use the message endpoint to start a new conversation on a personal dedicated line. Check GET /messages/{message_id} for the current delivery status, or subscribe to delivery-lifecycle webhooks.

Number selection and recipient replies

  • Inkbox selects an available, eligible number from your organization’s pool. Do not depend on a particular number or selection order.
  • One pool number can serve different recipients, but it cannot connect the same recipient to two agents simultaneously. A two-number pool therefore supports at most two simultaneous agent connections for each recipient.
  • The optional opening message is the only outbound message allowed on a new connection until the recipient messages that connection. Further sends return 409 with error: "imessage_awaiting_inbound".
  • A message from a previous connection does not unlock the new connection, even when it uses the same number and agent. Messaging another number or a group does not satisfy the requirement. Tapbacks do not count as replies on pool numbers, even when you receive imessage.reaction_received.
  • Each new connection can accept one opening message, up to three total unanswered messages for the same recipient and pool number before their first reply. Disconnecting and reconnecting can accept openings two and three; a fourth countable message is blocked. Changing agents does not reset the cumulative count. Pending messages and uncertain outcomes count. A terminal failure is excluded only when Inkbox can confirm the message was never sent; this does not refund quota usage.
  • Replaying a request or connecting an already-active pair never sends another opening. Reconnects can use another eligible pool number; they are not pinned to the previous number. Configured quotas still apply.
Reusing a number preserves the recipient’s existing iMessage thread with that number. A reply arriving after reassignment routes to the newly connected agent. Each agent’s API conversation history remains separate.

Limits and errors

Pool-number limits, including new-contact capacity and spacing, are configured for your organization and enforced per number when sending. For a connect request with an opening message, they determine whether a number can accept that send. Silent connections do not use or reserve opening-message capacity. Account and identity quotas also apply when sending. Limits are not request parameters. Common 409 errors: Common 422 errors: A timed quota response includes Retry-After in seconds. Wait at least that long before retrying with the same key and body. Some limits require another condition to change and have no timed reset; do not assume every 429 includes Retry-After.

Disconnect a recipient

Disconnect the active connection for an identity and recipient. This operation does not require the organization to have an active pool and can also release an existing standard shared-service connection.

Request body

bash

Response (200)

JSON
If there is no active connection, this is a successful no-op:
JSON
Disconnect stops routing new messages to that agent and cancels outgoing messages whose sending has not started. Messages already being sent cannot be recalled. Canceled messages remain in history with status: "error" and error_code: "imessage_assignment_inactive". For pool connections, their imessage.delivery_failed event reports that cancellation. An uncertain delivery outcome is not a confirmed failure. The conversation history remains readable, and the recipient is not notified. Use a fresh Idempotency-Key for a later reconnect. Neither disconnect nor a new request key resets recipient engagement requirements or messaging limits. Missing authentication returns 401; an unauthorized caller receives 403. An unknown or inaccessible identity returns 404. Invalid requests return 422. Conflicting idempotency input or concurrent connection changes return 409; honor Retry-After when present.