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.
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
Connect without sending
Omitfirst_message to assign a number without sending an opening message:
bash
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,
messageisnulland nothing was sent. - 200: The identity and recipient already have an active connection.
already_connectedistrue,messageisnull, and no greeting is sent. Existing connections stay on their current number, including connections created through the standard shared service.
201, selected fields):
JSON
200):
JSON
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
409witherror: "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.
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
Request body
bash
Response (200)
JSON
JSON
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.
