Agent iMessage

Agents can be reachable over iMessage: enabling iMessage for an agent on its dashboard page provisions everything automatically, and the agent answers inbound texts on its own. This API adds outbound sending — your backend asks a specific agent to message someone first, from the dedicated number that agent answers on.

Use a Speko bearer API key on every request:

Authorization: Bearer sk_live_...
Content-Type: application/json

Prerequisites

• iMessage is enabled for the agent (dashboard → agent → iMessage), and
• the agent answers on a dedicated number picked from your workspace's number pool (ask Speko to add numbers to your pool).

An agent on the shared router cannot send first — recipients must connect to it before it can reply, and those replies are handled by the agent itself, not this API.

Send a message

POST /v1/imessage/{agentId}/messages

{
  "to": "+12015551234",
  "text": "Load 42 is ready for pickup."
}

The message is sent as the agent, from its dedicated number. Inkbox attempts iMessage first and may downgrade to SMS asynchronously when the destination has no Apple ID. The response is the same shape as the legacy phone-number send endpoint:

{
  "messageId": "76528fd0-9aeb-43d0-a851-b813fdfaeae0",
  "conversationId": "37f30c7f-565b-45fa-b04c-df29b5af2068",
  "phoneNumberId": "2b3fb8b3-17ef-4e78-b742-69a4ef55c223",
  "to": "+12015551234",
  "attemptedChannel": "imessage",
  "channel": null,
  "fallbackApplied": null,
  "deliveryFinal": false,
  "status": "pending"
}

channel and fallbackApplied stay null while the iMessage attempt is unresolved, then become the confirmed transport (imessage, sms, or rcs) and whether a downgrade happened. deliveryFinal becomes true on delivered, declined, or error. The recipient's reply goes to the agent, which answers on its own — no webhook wiring is needed for the conversation to continue.

Do not send a second message when the request succeeds: a pending asynchronous delivery retried through another path can duplicate the send. Retry only failed HTTP requests.

Errors

Relationship to the phone-number API

POST /v1/imessage-phone-numbers/{phoneNumberId}/messages is deprecated in favor of this endpoint and will be removed on August 14, 2026. The agent-scoped form names the agent instead of the raw number, so the conversation and its replies stay with the agent that owns the number.