Skip to main content
The Inkbox iMessage router is the number humans text to connect with an agent. A recipient sends connect @your-handle to the router; Inkbox creates the connection and every message they send afterward lands in your agent’s conversation. Beta: Organization-owned iMessage routers are available upon request. An organization-owned router gives your organization its own configurable router number. Authenticated requests from an organization with one receive that router; other requests receive the shared Inkbox router. Resolve the router number at runtime — it can change, so never hardcode it.

​
Automatic name and photo sharing

Stable iMessage numbers can offer their profile directly in Messages, without sending a separate router contact-card message:
  • An organization-owned router uses the display name and avatar configured in Console → iMessage → Router settings. Turn Automatic name and photo sharing off there to remove the offered router profile.
  • A dedicated agent number uses the agent’s display name and avatar. When no display name is set, it uses the agent handle exactly as written.
  • Shared agent lines do not offer one automatic profile because one line can route conversations to multiple agents.
Changing a router or agent display name or avatar updates the profile for its stable number. Name sharing remains enabled without a photo when an avatar has never been set or is removed. The connected agent’s contact card is still sent during the connect flow so the recipient can save that agent’s number and other enabled details.

​
Get organization router settings

Returns the active organization-owned router line and its configuration. This endpoint requires an authenticated organization member or an admin-scoped API key and returns 404 when the organization does not have an active router line. The response includes config.contact_sharing_enabled, the authoritative switch for automatically offering the router’s name and photo from its stable number. The response contains the complete router configuration; the example below is abbreviated to the fields relevant to contact sharing.
JSON

​
Update organization router contact sharing

Set contact_sharing_enabled to true to publish the router’s display name and optional avatar, or false to remove its automatic sharing profile. Other router settings are unchanged when omitted. The response has the same line-and-config shape as GET /router. Profile publication is asynchronous; the response confirms the saved configuration while Inkbox applies and verifies the latest profile in the background.

​
Get router number

Returns the effective router number and the connect command for the caller, plus a ready-to-share tap link and QR code. Authenticated callers receive their organization’s router when one is active, with the shared Inkbox router as the fallback. For identity-scoped API keys, connect_command is pre-filled with that agent’s handle; for admin API keys it carries a placeholder to fill in unless you pass agent_identity_id.

​
Query parameters

​
Response (200)

JSON

​
Error responses

​
Code examples

​
The connect flow

  1. Your human texts the connect_command (for example connect @my-agent) to the router number — or taps sms_link / scans connect_qr_png_data_url to get there with the message pre-drafted.
  2. The router confirms and creates a connection between that human and the agent identity, and sends the agent’s contact card — name, number, email, description, and the agent’s avatar as the contact photo.
  3. The human’s messages now arrive in your agent’s conversation — and fire imessage.received webhooks if subscribed.
  4. Your agent replies with POST /messages.
The router only connects recipients to identities with imessage_enabled: true. A human can be connected to several agents at once; each connection is its own conversation. Humans can also text the router to list or replace their connections — the router explains its own commands when texted.