Key concepts

A handful of objects cover the whole API. Each one below links to the reference page that works with it.

Installs and the installer

Your app is a custom integration. A Blue Reacher user installs it, approves the scopes it asks for, and your app receives tokens for that install. The user who installed it is the installer.

Every token is bound to its installer. A token can only read and change what that installer owns: their workspaces, contacts, devices and messages. A record that belongs to someone else answers 404, never 403, so ids are not leaked.

See Authentication for the flow and Custom integrations for how an app is registered.

Workspaces

A workspace is a sub-account. It is either a location connected from a CRM, or a stand-alone custom workspace created in the dashboard or with POST /v1/workspaces. Devices are assigned to a workspace, contacts live in a workspace, and most requests take a workspace_id.

id is the numeric workspace id. remote_id is the external location id for connected workspaces, or a server-generated string for custom workspaces.

Each workspace can carry an inbound webhook URL. See Inbound webhooks.

Channels

Blue Reacher sends iMessage. The channel value is imessage. Omit channel, or send default, and the workspace's Message Routing decides.

iMessage also reaches an iMessage email address. Email recipients are iMessage only.

Devices

A device is one connected line. GET /v1/devices returns every line in one list, each row carrying channel.

Every row carries one health contract: health_status is healthy, degraded, offline or unknown, with last_seen_at, last_ping_at and a health object with the same keys on every row.

A workspace with no line assigned records the message but does not deliver it. Assign devices in the dashboard under Devices.

Contacts

A contact is a person in one workspace. Creating one needs workspace_id and at least one of email or phone_number. Phone numbers carry the country code, for example +15551234567.

A contact can hold names, company, website, address fields, timezone, custom_fields, tags and notes, plus the flag is_verified_imessage.

Deleting a contact is a soft delete. It stops appearing and its id answers 404 from then on.

Tags come from the workspace tag library, and custom field keys from the workspace's custom field definitions.

Messages

POST /v1/messages sends to a contact, a phone number or an iMessage email address. A send that names a phone number with no matching contact creates the contact first.

The response carries a numeric id and the same value as the string message_id. That one id works everywhere: GET /v1/messages/{id} reads the status, and the reaction, edit, unsend and notify-anyway routes take it too.

The status lifecycle is:

queued → webhook_sent → accepted → sent → delivered

A message can also end as failed. Three more statuses appear on reads: read when the recipient opened it, received for inbound messages, and unsent after an unsend.

One attachment per message, as a single public https:// URL, up to 5 MB. An audio file is sent as a voice note.

Scheduled messages go out within a minute of send_at, between one minute and one year ahead.

Conversations

The inbox as an API. GET /v1/conversations lists one row per contact or group, unread first, with unread_count, is_read, starred and archived state. GET /v1/conversations/{contact_id}/messages returns a contact's thread, newest first.

Groups

iMessage group chats. Groups come from the line's own chats or from POST /v1/groups/imessage. A group can be bridged to the connected CRM, where it appears as a contact.

Calls

A workspace calls from its own lines with FaceTime Audio. There are two kinds of call: a call a person makes, and a missed call that leaves a missed-call notification. Call routing sets the order lines are tried in.

Advanced Mode

Advanced Mode is a setting on the workspace's line. With it on, the line can do what Messages can do: tapbacks, threaded replies, send effects, edit, unsend, notify anyway and the Check iMessage lookup.

Without a line in Advanced Mode, each of those routes answers 400 with NO_ADVANCED_MODE_LINE in the message.

Do Not Disturb

DND is set per contact and per direction. Outbound DND refuses sends to the contact with 409. Inbound DND stops AI agents and automations from reacting to the contact's messages. Read it with GET /v1/contacts/{id}/dnd and change it with PATCH /v1/contacts/{id}/dnd.

Use outbound DND as your opt-out switch. See Opt-out handling.

Scopes

Every route declares the scope it needs, such as contacts.read or messages.write. A token without that scope answers 403. Scopes are granted at install time and checked on every request. The full list is on Scopes.