Send your first message

This guide walks through a production-shaped outbound send: auth, body fields, idempotency, and how to interpret the response.

Prerequisites

A workspace with a live line.
A Messages API key with comms_send.
A phone number you control for testing (to in E.164).

Request

POST /api/v1/comms/messages
Host: osis.co
Authorization: Bearer osis_…
Content-Type: application/json
Idempotency-Key: order-4242-confirm

{
  "to": "+12125550147",
  "body": "Your appointment is confirmed for Tuesday at 3pm.",
  "channel": "imessage"
}

Fields

Field	Required	Notes
`to`	One of `to` / `conversation_id`	E.164, e.g. `+12125550147`
`conversation_id`	One of `to` / `conversation_id`	Continue an existing thread
`body`	Yes	Plain text for SMS / iMessage
`channel`	No	`"sms"` or `"imessage"` when you want to prefer one
`idempotency_key`	No	Same as header; either works

Auth

Authorization: Bearer $COMMS_API_KEY

Missing or invalid key → 401. Missing comms_send → 403 with { "error": "missing comms_send scope" }.

Response

Accepted

202 — Comms accepted the message for delivery.

{
  "message": {
    "id": "msg_…",
    "body": "Your appointment is confirmed for Tuesday at 3pm.",
    "direction": "outbound"
  }
}

Duplicate

200 — Same idempotency key already processed. No second send.

{
  "message": { "id": "msg_…", "body": "…", "direction": "outbound" },
  "duplicate": true
}

Treat 202 and duplicate 200 as success for your queue / job runner.

Idempotency

Use a stable key derived from your business event:

order-{orderId}-shipped
booking-{bookingId}-reminder-1

If your worker crashes after the POST but before recording success, the retry hits the same key and Comms returns the original result. Full detail: Idempotency.

Channels

Value	Behavior
omitted	Comms picks the best path for that recipient
`"imessage"`	Prefer iMessage when available
`"sms"`	Force SMS

Not every recipient can receive iMessage. Prefer omitting channel unless you have a product reason.

Continuing a thread

First touch:

{ "to": "+12125550147", "body": "Hi — this is Alex from Acme." }

Later replies in the same conversation (using an id you stored):

{
  "conversation_id": "conv_…",
  "body": "Your table is ready."
}

Checklist for production

Key lives only on the server

Inject COMMS_API_KEY from your secret store. Never embed it in a frontend bundle.

Every send has an Idempotency-Key

Derive it from the domain event so retries are safe.

Log status + message id

Persist message.id and HTTP status so support can trace a send without reading phone logs.

Handle 429

Back off using retry_after when present. See Errors & rate limits.

​Prerequisites

​Request

​Fields

​Auth

​Response

​Accepted

​Duplicate

​Idempotency

​Channels

​Continuing a thread

​Checklist for production

​Related