Messages

Unified send + list across every line. The channel field picks the pipeline.

Every route takes Authorization: Bearer <ACCESS_TOKEN> unless the auth line says otherwise. Ids are numbers. Errors use the shape on the errors page.

List messages

GET https://api.bluereacher.com/v1/messages

Auth: Bearer access token. Scope: messages.read.

List messages across any combination of channels — inbound + outbound — with filtering.

Returns the messages in the installer's workspaces, every channel in one list, from the same conversation records the app.bluereacher.com Conversations page shows. All filters are optional and combine with AND semantics.

One id everywhere. A row's id (and message_id, the same value as a string) is the message id the other message endpoints take: GET /messages/{id} for its status, POST /messages/{id}/reactions to react to it, and the id in the conversation thread. That holds for inbound messages too.

Order. One list across channels, ordered by created_at (newest first by default). breakdown counts the matching messages per channel; total is their sum.

Without workspace_id, every workspace the installer owns is listed.

Parameters

Request

curl -X GET "https://api.bluereacher.com/v1/messages?channel=sms%2Cimessage&workspace_id=7&phone=%2B15551234567" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK — interleaved across channels, newest first):

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 84220,
        "message_id": "84220",
        "channel": "imessage",
        "workspace_id": 7,
        "contact_id": 1234,
        "direction": "inbound",
        "to": null,
        "from": "+15551234567",
        "is_group": false,
        "text": "❤️ Loved: “Here is the brochure.”",
        "effect": null,
        "reaction": {
          "kind": "love",
          "emoji": "❤️",
          "snippet": "Here is the brochure."
        },
        "media": null,
        "status": "received",
        "error_message": null,
        "created_at": "2026-06-09T14:24:00.000Z",
        "updated_at": "2026-06-09T14:24:00.000Z"
      }
    ],
    "total": 87,
    "page": 1,
    "limit": 25,
    "breakdown": {
      "sms": 32,
      "imessage": 19
    }
  }
}

Response fields

messages: Array of messages, normalized across channels. Fields:

Send message

POST https://api.bluereacher.com/v1/messages

Auth: Bearer access token. Scope: messages.write.

Limits: 30 messages / 15 min per workspace · 1 attachment per message, 5 MB max

Send an outbound message to a contact or a phone number, on any channel.

Before you can send: on app.bluereacher.com → Devices, add a device (iMessage) and assign it to the workspace. A workspace with no assigned device for an eligible channel records the message but does not deliver it.

Supply contact_id or phone (with country code, e.g. +61 / +1 — a contact is auto-created if none matches), plus message and/or attachments — a single media URL (attachment-only sends are valid).

iMessage to an email address: iMessage also reaches an iMessage email address. Send it as email, or put the email in phone. If no contact has that email, an email-only contact is auto-created, the same as for a new phone number. A contact that has a phone number is always messaged at the phone; an email-only contact (by contact_id too) is messaged at its email over iMessage.

Omit channel (or send default) to use the workspace Message Routing (Primary → Fallback; same-row channels in parallel), or force one with channel = imessage. The send is recorded in the conversation / Message Logs.

mp3, m4a/aac, ogg/opus and wav work (mp3 is the safe choice), one file up to 5 MB at a public https:// URL that answers a HEAD request with Content-Length and an audio/* content type. message is optional and becomes the caption or an accompanying text. Delivery is asynchronous as for any send; replies and reactions come back as ordinary inbound messages.

Send effects (iMessage): add effect to send the message with an iMessage effect — a full-screen one (confetti, fireworks, balloons, hearts, lasers, shooting_star, sparkles, echo, spotlight) or a bubble one (slam, loud, gentle, invisible_ink). An effect sends over iMessage (leave channel out or send imessage; another channel is a 400), needs message text, and needs a line with Advanced Mode on in the workspace — the same rule as the effect button on the dashboard; without one the request is a 400 NO_ADVANCED_MODE_LINE. In message reads the effect is the effect field (also on messages a contact sends with an effect). The stored text keeps the effect as its first line, ✦ Effect: confetti, as the dashboard writes it; the recipient sees only the body.

Threaded replies (iMessage): add reply_to with a message id to answer that message the way the reply button on the app.bluereacher.com does. The message is sent with a leading line, ↩︎ Replying to “<the first 60 characters of that message>” (“an attachment” for a photo or file), which a line in Advanced Mode turns into a real threaded reply; the contact sees only your text. Leave the recipient out and the reply goes to that message's contact. Replies are iMessage only, need message text, can't answer a group message or a reaction, and need a line with Advanced Mode on (else 400 NO_ADVANCED_MODE_LINE). With effect too, the effect line comes first. The line finds the target by its quoted text, so if two messages in the thread start the same way, the reply attaches to the one Messages picks.

Parameters

Request

curl -X POST "https://api.bluereacher.com/v1/messages" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "phone": "+61412345678",
  "channel": "default",
  "message": "Thanks for your enquiry — we open at 09:00.",
  "attachments": ""
}'

Responses

A 200 reply (OK — queued for delivery):

{
  "success": true,
  "message": "Message queued for delivery.",
  "data": {
    "id": 84213,
    "status": "webhook_sent",
    "message_id": "84213",
    "conversation_id": 512,
    "channel": "imessage",
    "queued_at": "2026-07-20T10:22:07.000Z"
  }
}

Response fields

send_result: The queued outbound message. Fields:

React to message

POST https://api.bluereacher.com/v1/messages/{id}/reactions

Auth: Bearer access token. Scope: messages.write.

Limits: 30 messages / 15 min per workspace (counts with Send message)

Send an iMessage reaction (tapback) — ❤️ 👍 👎 😂 ‼️ ❓ — to a message in a contact's conversation.

Reacts to a message the way the reaction bar on the app.bluereacher.com conversation does. {id} is the message's id: the id of a row from List messages or List conversation messages, or the message_id from Send message. Messages you sent and messages the contact sent can both be reacted to.

How it is sent: a reaction is an iMessage whose text is one line, ❤️ Loved: “<the message reacted to>”. The quote is the start of the target's text — up to 60 characters, spaces and line breaks collapsed, with "…" when it is cut. A line in Advanced Mode turns that line into a real tapback on the quoted message; the contact never sees the text. It goes to the message's contact through the same pipeline as Send message, so DND, credits and the send rate limit apply as for any message, and the response is the same.

Rules (the same as the dashboard's):

• The message must be an iMessage with text, in a one-to-one conversation.

The line finds the target by its quoted text, so when the conversation holds two messages that start the same way, the tapback lands on the one Messages picks.

In message reads a reaction is the reaction field — { kind, emoji, snippet } — on reactions you send and on the contact's, which also carry custom emoji (kind: "emoji").

Parameters

Request

curl -X POST "https://api.bluereacher.com/v1/messages/84214/reactions" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "reaction": "love"
}'

Responses

A 200 reply (OK — reaction queued for delivery):

{
  "success": true,
  "message": "Message queued for delivery.",
  "data": {
    "id": 84230,
    "status": "webhook_sent",
    "message_id": "84230",
    "conversation_id": 512,
    "channel": "imessage",
    "queued_at": "2026-10-27T09:16:00.000Z",
    "reaction": "love",
    "reacted_to_message_id": "84214"
  }
}

Response fields

send_result: The queued reaction message — the Send message result, plus what it reacted to. Fields:

Edit message

POST https://api.bluereacher.com/v1/messages/{id}/edit

Auth: Bearer access token. Scope: messages.write.

Edit the text of an iMessage you sent, within 15 minutes — the recipient sees it as edited.

Edits a sent iMessage the way the edit button on the app.bluereacher.com conversation does: the line that sent it edits it in Messages, and the recipient sees the new text marked Edited. Apple allows edits within 15 minutes of sending (and up to five edits).

Send the new body in message. If the message was sent with an effect, a subject or as a threaded reply, those stay as they were; only the body changes. The edited text is what message reads return afterwards.

Rules (the same as the dashboard's): the message must be one you sent, over iMessage, with text, sent from a line, and not itself a reaction; the workspace needs a line with Advanced Mode on (else 400 NO_ADVANCED_MODE_LINE). The request waits for the line (up to 15 s): 422 LINE_REFUSED when Messages refused, 503 LINE_UNREACHABLE when the line is offline, 504 LINE_TIMEOUT when it did not answer in time — the change may still land, so read the message again before retrying.

Parameters

Request

curl -X POST "https://api.bluereacher.com/v1/messages/84213/edit" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "message": "Booking confirmed for 5 PM."
}'

Responses

A 200 reply (OK — done on the line):

{
  "success": true,
  "message": "Message edited",
  "data": {
    "id": 84213,
    "message_id": "84213",
    "channel": "imessage",
    "workspace_id": 7,
    "contact_id": 1234,
    "direction": "outbound",
    "to": "+61412345678",
    "from": null,
    "is_group": false,
    "text": "Booking confirmed for 5 PM.",
    "effect": null,
    "reaction": null,
    "media": null,
    "status": "delivered",
    "error_message": null,
    "created_at": "2026-10-29T09:15:58.000Z",
    "updated_at": "2026-10-29T09:20:03.000Z",
    "edited_at": "2026-10-29T09:20:03.000Z"
  }
}

Unsend message

POST https://api.bluereacher.com/v1/messages/{id}/unsend

Auth: Bearer access token. Scope: messages.write.

Unsend an iMessage you sent, within 2 minutes — it disappears from the recipient's conversation.

Unsends a sent iMessage the way the unsend button on the app.bluereacher.com conversation does. Apple allows unsending within 2 minutes of sending. The message's status becomes unsent afterwards.

A recipient on an older iOS / macOS may still keep the original.

Rules (the same as the dashboard's): the message must be one you sent, over iMessage, with text, sent from a line, and not itself a reaction; the workspace needs a line with Advanced Mode on (else 400 NO_ADVANCED_MODE_LINE). The request waits for the line (up to 15 s): 422 LINE_REFUSED when Messages refused, 503 LINE_UNREACHABLE when the line is offline, 504 LINE_TIMEOUT when it did not answer in time — the change may still land, so read the message again before retrying.

Parameters

Request

curl -X POST "https://api.bluereacher.com/v1/messages/84213/unsend" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7
}'

Responses

A 200 reply (OK — done on the line):

{
  "success": true,
  "message": "Message unsent",
  "data": {
    "id": 84213,
    "message_id": "84213",
    "channel": "imessage",
    "workspace_id": 7,
    "contact_id": 1234,
    "direction": "outbound",
    "to": "+61412345678",
    "from": null,
    "is_group": false,
    "text": "Booking confirmed for 4 PM.",
    "effect": null,
    "reaction": null,
    "media": null,
    "status": "unsent",
    "error_message": null,
    "created_at": "2026-10-29T09:15:58.000Z",
    "updated_at": "2026-10-29T09:20:03.000Z",
    "edited_at": null
  }
}

Notify anyway

POST https://api.bluereacher.com/v1/messages/{id}/notify-anyway

Auth: Bearer access token. Scope: messages.write.

Break through the recipient's Focus for an iMessage you sent, within 24 hours (Apple's Notify Anyway).

When the recipient has a Focus on, Messages silences the notification and shows "has notifications silenced". Notify Anyway pushes that message's notification through once, as the app.bluereacher.com button does. Apple allows it within 24 hours of sending. The message itself does not change.

To see whether a recipient has notifications silenced first, use Check iMessage (silenced).

Rules (the same as the dashboard's): the message must be one you sent, over iMessage, with text, sent from a line, and not itself a reaction; the workspace needs a line with Advanced Mode on (else 400 NO_ADVANCED_MODE_LINE). The request waits for the line (up to 15 s): 422 LINE_REFUSED when Messages refused, 503 LINE_UNREACHABLE when the line is offline, 504 LINE_TIMEOUT when it did not answer in time — the change may still land, so read the message again before retrying.

Parameters

Request

curl -X POST "https://api.bluereacher.com/v1/messages/84213/notify-anyway" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7
}'

Responses

A 200 reply (OK — done on the line):

{
  "success": true,
  "message": "Notified anyway",
  "data": {
    "id": 84213,
    "message_id": "84213",
    "channel": "imessage",
    "workspace_id": 7,
    "contact_id": 1234,
    "direction": "outbound",
    "to": "+61412345678",
    "from": null,
    "is_group": false,
    "text": "Booking confirmed for 4 PM.",
    "effect": null,
    "reaction": null,
    "media": null,
    "status": "delivered",
    "error_message": null,
    "created_at": "2026-10-29T09:15:58.000Z",
    "updated_at": "2026-10-29T09:20:03.000Z",
    "edited_at": null
  }
}

Get message status

GET https://api.bluereacher.com/v1/messages/{id}

Auth: Bearer access token. Scope: messages.read.

Check the delivery status of a message by its id (the message_id returned from Send message).

Look up a single message by its id — the message_id returned from Send message, or the id of any List messages or conversation thread row — and read its current delivery status. Scoped to your token, so you can only read your own messages.

The response returns the message_id, channel, status and message, with effect and reaction (see List messages). Status lifecycle: queued → webhook_sent → accepted → sent → delivered (or failed).

Parameters

Request

curl -X GET "https://api.bluereacher.com/v1/messages/84213" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK — current status):

{
  "success": true,
  "data": {
    "message_id": "84213",
    "channel": "imessage",
    "status": "delivered",
    "message": "Thanks for your enquiry — we open at 09:00.",
    "effect": null
  }
}

Response fields

message: The message record with its current delivery status. Fields:

Schedule message

POST https://api.bluereacher.com/v1/messages/scheduled

Auth: Bearer access token. Scope: messages.write.

Limits: 30 messages / 15 min per workspace (counts with Send message) · 1 attachment per message

Send a message later.

Same recipient and channel rules as Send message. send_at is an ISO 8601 time at least 1 minute and at most 1 year ahead. The message goes out within a minute of send_at; credits, DND, routing and the device are checked then, not now — a message that cannot be sent at that time ends as failed with the reason in error.

An effect works as on Send message; the iMessage and Advanced Mode checks are made when you schedule it.

Parameters

Request

curl -X POST "https://api.bluereacher.com/v1/messages/scheduled" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "contact_id": 1234,
  "message": "Reminder: your call is tomorrow at 10am.",
  "send_at": "2026-10-28T23:00:00Z"
}'

Responses

A 201 reply (Scheduled):

{
  "success": true,
  "message": "Message scheduled",
  "data": {
    "id": 912,
    "workspace_id": 7,
    "contact_id": 1234,
    "to": "+61412345678",
    "message": "Reminder: your call is tomorrow at 10am.",
    "effect": null,
    "reaction": null,
    "attachments": [],
    "channel": null,
    "send_at": "2026-10-28T23:00:00.000Z",
    "status": "pending",
    "sent_message_id": null,
    "error": null,
    "created_at": "2026-10-27T09:20:00.000Z"
  }
}

List scheduled messages

GET https://api.bluereacher.com/v1/messages/scheduled

Auth: Bearer access token. Scope: messages.read.

A workspace's scheduled messages.

status defaults to pending (waiting or being sent now), soonest first. Any other status lists newest first.

Parameters

Request

curl -X GET "https://api.bluereacher.com/v1/messages/scheduled?workspace_id=7" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": [
    {
      "id": 912,
      "workspace_id": 7,
      "contact_id": 1234,
      "to": "+61412345678",
      "message": "Reminder: your call is tomorrow at 10am.",
      "effect": null,
      "reaction": null,
      "attachments": [],
      "channel": null,
      "send_at": "2026-10-28T23:00:00.000Z",
      "status": "pending",
      "sent_message_id": null,
      "error": null,
      "created_at": "2026-10-27T09:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "max_limit": 100,
    "total": 1,
    "total_pages": 1
  }
}

Cancel scheduled message

DELETE https://api.bluereacher.com/v1/messages/scheduled/{id}

Auth: Bearer access token. Scope: messages.write.

Cancel a message that has not been sent yet.

Only a pending message can be cancelled. One already being sent, sent, failed or cancelled answers 409.

Parameters

Request

curl -X DELETE "https://api.bluereacher.com/v1/messages/scheduled/912" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Scheduled message cancelled"
}