Sending messages

Everything you send — a plain sentence, a link card, a poll — goes through one command: POST /v1/commands/message.send.

The body is always two objects. target says where the message goes, payload says what it is.

{
  "target": {
    "kind": "conversation",
    "conversationId": "a0000000-0000-4000-8000-000000000001"
  },
  "payload": { "text": "Your table is ready." }
}

A call the API accepts returns 202 with an id you can correlate later:

{ "commandId": "cmd-1", "status": "queued", "disposition": "queued" }

The boundary checks the envelope, not the contents. The body must be a JSON object of at most 65,536 bytes carrying a target object and a payload object. Those three conditions do give you a synchronous 400 — body_too_large, body_not_object and target_and_payload_required respectively — before anything is queued.

The six payload shapes

payload is a union discriminated by kind. Plain text is the exception: it carries no kind at all — only text.

The two unavailable kinds both require a transferId naming media already staged in Mapier storage, and /v1 exposes no way to produce one. Their schemas are documented on the attachments page so you know what to expect when they land, but you cannot use them today.

Two ways to address a send

message.send accepts two of the three target kinds, and the choice changes more than the address.

A conversation target replies into a thread you already know about. Its id comes from an inbound message event on the stream. This is the only target that accepts rich payloads, it honours Idempotency-Key, and it has a 30-second dispatch deadline.

A recipient target opens a new thread from a phone number or email. It takes plain text only — the server reads payload.text and drops everything else without complaining — and it ignores Idempotency-Key entirely, minting a fresh one per call. A retried recipient send delivers twice.

Pick a payload

Related