POST /v1/commands/:type

Every action you take on iMessage is a command. They all share one endpoint, one request envelope and one response shape; the :type path segment selects the verb.

POST /v1/commands/{type}

Request

Headers

Body

The body is capped at 65,536 bytes. Both keys default to {}, so a command whose whole meaning is its type needs no body at all; a body you do send must be JSON, and one that is not an object — or whose target or payload is not one — is 422 validation_failed. See Addressing a conversation for the target shapes.

Command types

The published vocabulary is the {type} enum of the OpenAPI document. These have a page here:

Two refusals, before anything is queued

A type outside the vocabulary is a 404 at once, before the body is read — there is no body that would have made it valid:

{
  "error": {
    "code": "unsupported_command",
    "message": "`message.delete` is not a command this platform knows."
  }
}

A type in the vocabulary that no line of the resolved channel ever carries is a 404 too, raised once the line resolves and before anything is written, with details.reason: "not_on_channel", the channel and the capability the command needed. On an iMessage line, live or test, that is every type in the callout above.

Branch on details.reason, never on message. A type the channel carries and this particular line cannot is the third answer: a 202 that settles failed. Capabilities and GET /v1/whoami's lines[].capabilities say which is which before you send.

A type this line cannot carry out

A type the channel carries and this line or this environment cannot execute — group.create in the sandbox — is accepted with 202 and settles failed / unsupported_capability on the stream instead, because that one is worth retrying against a live key and the two 404s are not.

A group.update or a group.leave never gets that far in the sandbox: a test line has no group chat, so a well-formed call to either is 422 validation_failed at target.conversationId.

Response

202 Accepted:

{
  "commandId": "3f1a0c2e-8b47-4d19-9a5e-2c6f0b8d4e71",
  "status": "queued",
  "disposition": "queued",
  "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d",
  "lineSelection": "reused_active_chat"
}

lineId is the line the command went out on, as GET /v1/whoami lists it; lineSelection is why that one — named, reused_active_chat or new_best_line, explained in The shape of every response. disposition is "adopted" when an identical idempotency key already existed, meaning no new work was created and commandId refers to the original command. status is "queued" on every 202, an adopted one included: it says the command was accepted, never how it ended — even when the original has long since settled. A repeated key with nothing to adopt is not a 202 at all: a message.send whose first attempt is still running, or that no transport ever took, is a 409 conflict — see Errors.

Idempotency

Every command honours Idempotency-Key — a repeat is never run twice — except group.create, typing.start and message.read on a live line. A message.send is recorded against its key by the platform itself, before the line is asked, so a retried send is never posted twice on either target: it is adopted when a transport took the first attempt, and refused with 409 conflict when none did. The settlement's logicalActionId carries the key, or a copy of commandId for the one live command whose line mints its own identity: group.create. A message.send on the recipient path whose answer was lost is the exception: its message is left needs_reconcile, and its command frame carries the transport's own logicalActionId rather than your key. Correlate by commandId.

What is checked before anything is queued

The body first: over 65,536 bytes is 413 payload_too_large, not JSON is 400 bad_request, and a body, target or payload that is not an object is 422 validation_failed. So is a target that names nobody, with details pointing at target.recipientExternalId, and an Idempotency-Key that is empty, over 200 characters, holds a control character or has whitespace at either end, at Idempotency-Key.

A message.send payload is checked against the line the send resolves to, in both environments: a key the line does not carry that carries a value — a kind or a misspelled field included — is 422 validation_failed at payload.<key>, and so is a send with no text, at payload.text. See What a line carries. A live iMessage line also refuses what its path cannot carry, with the same code and nothing written: on the recipient path, an email address — at the target field you wrote it at (target.recipientExternalId, or whichever of its spellings you used), at target.conversationId when it is the peer of a thread you named that takes that path — and a group conversation the transport has not named yet, at target.conversationId. A reply the path cannot quote is refused at target.replyToMessageId.

On an iMessage line, live or test, the platform also checks how more commands are addressed, and refuses each with 422 validation_failed before anything is sent:

• a reaction.tapback or a name_photo.share names, at target.conversationId, a conversation the transport has named — which it does when the contact first writes into it;
• a reaction.tapback names its message at payload.targetMessageExternalId, and a messageId there for a message the line sent, or for one another conversation holds, is refused;
• a group.create names 2 to 32 other people at target.participantExternalIds, each an address the channel reads, counted once — the first is read as the command's recipient, and one the channel cannot read, the first included, is refused at target.participantExternalIds[i] (or the key and index you wrote);
• a group.update or a group.leave names, at target.conversationId, a conversation the transport reported as a group chat — and an update's action and its name or participantExternalId are checked too, and a leave's payload must be empty;
• a chat_background.set or a chat_background.remove names, at target.conversationId, a conversation with one person that the transport has confirmed is with that one person, or a group chat it reported — and a set's payload.preset and payload.colors are checked too, and a remove's payload must be empty;
• a message.edit or a message.unsend names, at target.messageId, a message this line sent in that conversation, which has a transport id and is inside its window — and an edit's payload.text is checked too;
• a name_photo.get or a name_photo.set names, at target.lineId, a line of this project in the key's environment — any other id is the 403 line_not_allowed — and a set's payload is checked too, its photo link fetched;
• a message.send, or any command addressed to a recipient, that names a line at target.lineId names one of this project's lines in the key's environment (any other id is the 403 line_not_allowed), on the channel target.channel names if it names one, and — beside a conversationId — the line that conversation is on;
• a typing.start names, at target.conversationId, a conversation the transport has confirmed is with that one person;
• a message.read names the same, and an optional payload.externalId is checked too;
• a poll.vote names, at target.conversationId, a conversation the transport has named, a group's included, and the poll and the choice at payload.pollExternalId and payload.optionExternalId; payload.remove and any other key are refused.

The platform checks no other command's payload, and in test nothing else does. On a live line the transport checks reaction.tapback and name_photo.share before it takes them, and that refusal comes back as a 422 validation_failed too, or a 400 bad_request, with the transport's word as the reason. A group.create payload is otherwise checked only when the line runs it. So in a reaction.tapback, name_photo.share or group.create payload, a misspelled field, an out-of-range value or a bad enum can return 202 and settle failed on the stream seconds later. When you are developing against a new payload shape, keep the stream open.

A sticker and a rich_link are checked by the platform as a text is — every bound at its own field, 422 validation_failed before anything is queued. What the line can still refuse is its own capability, settled failed with capability_constraint_violation on the stream.

Errors

Full descriptions and retry guidance: Error codes.

Related