Group chats

iMessage group chats: list and sync them, create iMessage groups, manage participants, bridge a group to the CRM, and send to it.

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

Route	Scope	What it does
`GET /v1/groups`	`groups.read`	The iMessage group chats of a workspace.
`GET /v1/groups/{channel}/{id}`	`groups.read`	One group chat.
`POST /v1/groups/imessage`	`groups.write`	Draft an iMessage group from contacts.
`POST /v1/groups/sync`	`groups.write`	Refresh a workspace's groups from its line.
`PATCH /v1/groups/{channel}/{id}`	`groups.write`	Rename an iMessage group, or bridge a group to the CRM.
`POST /v1/groups/imessage/{id}/participants`	`groups.write`	Add a phone number or email to an iMessage group.
`DELETE /v1/groups/imessage/{id}/participants`	`groups.write`	Remove a participant from an iMessage group.
`POST /v1/groups/imessage/{id}/leave`	`groups.write`	Leave an iMessage group on the line.
`POST /v1/groups/{channel}/{id}/messages`	`groups.write`	Send a message to a group chat.

List groups

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

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

The iMessage group chats of a workspace.

crm_bridged groups appear in the connected CRM as a contact with crm_phone. Inactive groups (left, or no longer on the line) are left out unless include_inactive=1.

Parameters

Name	In	Type	Required	Description
`workspace_id`	query	number	yes	A workspace of the installer.
`channel`	query	enum	no	One channel only.
`include_inactive`	query	boolean	no	1 = include groups that were left or retired.

Request

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

Responses

A 200 reply (OK):

{
  "success": true,
  "data": [
    {
      "id": "imsg_group:7",
      "channel": "imessage",
      "workspace_id": 7,
      "name": "Family",
      "participant_count": 2,
      "is_active": true,
      "crm_bridged": true,
      "crm_phone": "+881700000007",
      "last_synced_at": null,
      "created_at": "2026-10-20T00:00:00.000Z",
      "updated_at": "2026-11-04T00:00:00.000Z",
      "status": "active",
      "source": "dashboard",
      "device_id": "A1B2C3D4-0001",
      "participants": [
        {
          "handle": "+61412345678",
          "name": "Ann Lee"
        },
        {
          "handle": "bob@icloud.com",
          "name": "Bob"
        }
      ],
      "last_message_at": "2026-11-03T09:00:00.000Z"
    }
  ]
}

Status	When	Message
200	OK
400	No workspace_id	`workspace_id is required.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.read. This integration was granted: …`
404	Workspace does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`

Get group

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

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

One group chat.

Parameters

Name	In	Type	Required	Description
`channel`	path	enum	yes	The group's channel.
`id`	path	string	yes

Request

curl -X GET "https://api.bluereacher.com/v1/groups/imessage/imsg_group%3A7" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": {
    "id": "imsg_group:7",
    "channel": "imessage",
    "workspace_id": 7,
    "name": "Family",
    "participant_count": 2,
    "is_active": true,
    "crm_bridged": true,
    "crm_phone": "+881700000007",
    "last_synced_at": null,
    "created_at": "2026-10-20T00:00:00.000Z",
    "updated_at": "2026-11-04T00:00:00.000Z",
    "status": "active",
    "source": "dashboard",
    "device_id": "A1B2C3D4-0001",
    "participants": [
      {
        "handle": "+61412345678",
        "name": "Ann Lee"
      },
      {
        "handle": "bob@icloud.com",
        "name": "Bob"
      }
    ],
    "last_message_at": "2026-11-03T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.read. This integration was granted: …`
404	Group does not exist or is not the installer's (same response for both)	`Group not found or not accessible to this token`

Create iMessage group

POST https://api.bluereacher.com/v1/groups/imessage

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

Draft an iMessage group from contacts.

The chat does not exist in Messages yet: the group is pending_create and the line creates it when the first message is sent to it (Send to group). Each contact's phone, or its email when it has none, becomes a participant; a contact with neither is refused. The same participants on the same line twice returns the existing group (200). Needs an iMessage device connected to the workspace.

Parameters

Name	In	Type	Required	Description
`workspace_id`	body	number	yes	A workspace of the installer.
`contact_ids`	body	array<number>	yes	At least 2 contacts of the workspace.
`name`	body	string	no	The group name (up to 255 characters).
`device_id`	body	string	no	The line to create it on. Default: the workspace's default line.

Request

curl -X POST "https://api.bluereacher.com/v1/groups/imessage" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "contact_ids": [
    1234,
    1235
  ],
  "name": "Family"
}'

Responses

A 201 reply (Created (pending the first message)):

{
  "success": true,
  "message": "Group created — send the first message to start it in Messages",
  "data": {
    "id": "imsg_group:10",
    "channel": "imessage",
    "workspace_id": 7,
    "name": "Family",
    "participant_count": 2,
    "is_active": true,
    "crm_bridged": false,
    "crm_phone": null,
    "last_synced_at": null,
    "created_at": "2026-10-20T00:00:00.000Z",
    "updated_at": "2026-11-04T00:00:00.000Z",
    "status": "pending_create",
    "source": "dashboard",
    "device_id": "A1B2C3D4-0001",
    "participants": [
      {
        "handle": "+61412345678",
        "name": "Ann Lee"
      },
      {
        "handle": "bob@icloud.com",
        "name": "Bob"
      }
    ],
    "last_message_at": null
  }
}

Status	When	Message
201	Created (pending the first message)
200	A group with these participants already exists on that line
400	Fewer than 2 contacts, a contact with no handle, or no line	`No iMessage device is connected to this workspace`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.write. This integration was granted: …`
404	Workspace does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`

Sync groups

POST https://api.bluereacher.com/v1/groups/sync

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

Refresh a workspace's groups from its line.

imessage: asks the workspace's lines to report their group chats; they answer in the background, so list again shortly after.

Parameters

Name	In	Type	Required	Description
`workspace_id`	body	number	yes	A workspace of the installer.
`channel`	body	enum	yes	Which line to sync.

Request

curl -X POST "https://api.bluereacher.com/v1/groups/sync" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "channel": "imessage"
}'

Responses

A 202 reply (iMessage: asked):

{
  "success": true,
  "message": "Asked your line to report its group chats",
  "data": {
    "channel": "imessage",
    "devices": 1,
    "pushed": 1
  }
}

Status	When	Message
202	iMessage: asked
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.write. This integration was granted: …`
404	Workspace does not exist or is not the installer's (same response for both)	`Workspace not found or not accessible to this token`

Update group

PATCH https://api.bluereacher.com/v1/groups/{channel}/{id}

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

Rename an iMessage group, or bridge a group to the CRM.

crm_bridged: true gives the group a crm_phone and shows it in the connected CRM as a contact (created on its next message), so replies typed there reach the group; false removes it (the number is kept for re-enabling). name is for iMessage groups: with an Advanced-Mode line the chat is renamed in Messages for everyone (renamed_on_mac: true), otherwise only the dashboard label changes.

Parameters

Name	In	Type	Required	Description
`channel`	path	enum	yes	The group's channel.
`id`	path	string	yes
`name`	body	string	no	iMessage only. The new name.
`crm_bridged`	body	boolean	no	Show the group in the CRM (true) or not (false).

Request

curl -X PATCH "https://api.bluereacher.com/v1/groups/imessage/imsg_group%3A7" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Family chat",
  "crm_bridged": true
}'

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Group updated",
  "data": {
    "id": "imsg_group:7",
    "channel": "imessage",
    "workspace_id": 7,
    "name": "Family chat",
    "participant_count": 2,
    "is_active": true,
    "crm_bridged": true,
    "crm_phone": "+881700000007",
    "last_synced_at": null,
    "created_at": "2026-10-20T00:00:00.000Z",
    "updated_at": "2026-11-04T00:00:00.000Z",
    "status": "active",
    "source": "dashboard",
    "device_id": "A1B2C3D4-0001",
    "participants": [
      {
        "handle": "+61412345678",
        "name": "Ann Lee"
      },
      {
        "handle": "bob@icloud.com",
        "name": "Bob"
      }
    ],
    "last_message_at": "2026-11-03T09:00:00.000Z",
    "renamed_on_mac": true
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.write. This integration was granted: …`
404	Group does not exist or is not the installer's (same response for both)	`Group not found or not accessible to this token`

Add participant

POST https://api.bluereacher.com/v1/groups/imessage/{id}/participants

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

Add a phone number or email to an iMessage group.

Done in Messages on the group's line, which must be in Advanced Mode and have the chat already (a pending_create group gets its chat on the first send). Someone already in the group is refused.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The iMessage group key (imsg_group:<n>).
`address`	body	string	yes	A phone number with country code, or an iMessage email address.

Request

curl -X POST "https://api.bluereacher.com/v1/groups/imessage/imsg_group%3A7/participants" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "+61400000005"
}'

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Participant added",
  "data": {
    "id": "imsg_group:7",
    "channel": "imessage",
    "workspace_id": 7,
    "name": "Family",
    "participant_count": 3,
    "is_active": true,
    "crm_bridged": true,
    "crm_phone": "+881700000007",
    "last_synced_at": null,
    "created_at": "2026-10-20T00:00:00.000Z",
    "updated_at": "2026-11-04T00:00:00.000Z",
    "status": "active",
    "source": "dashboard",
    "device_id": "A1B2C3D4-0001",
    "participants": [
      {
        "handle": "+61412345678",
        "name": "Ann Lee"
      },
      {
        "handle": "bob@icloud.com",
        "name": "Bob"
      },
      {
        "handle": "+61400000005",
        "name": null
      }
    ],
    "last_message_at": "2026-11-03T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
400	The line could not do it (no Advanced Mode, offline, or Messages refused)	`The group's line isn't in Advanced Mode`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.write. This integration was granted: …`
404	Group does not exist or is not the installer's (same response for both)	`Group not found or not accessible to this token`

Remove participant

DELETE https://api.bluereacher.com/v1/groups/imessage/{id}/participants

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

Remove a participant from an iMessage group.

Send address in the JSON body or as a query parameter. Done in Messages on the group's line (Advanced Mode).

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The iMessage group key (imsg_group:<n>).
`address`	body	string	yes	The participant's phone number or email (or ?address=…).

Request

curl -X DELETE "https://api.bluereacher.com/v1/groups/imessage/imsg_group%3A7/participants" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "bob@icloud.com"
}'

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Participant removed",
  "data": {
    "id": "imsg_group:7",
    "channel": "imessage",
    "workspace_id": 7,
    "name": "Family",
    "participant_count": 1,
    "is_active": true,
    "crm_bridged": true,
    "crm_phone": "+881700000007",
    "last_synced_at": null,
    "created_at": "2026-10-20T00:00:00.000Z",
    "updated_at": "2026-11-04T00:00:00.000Z",
    "status": "active",
    "source": "dashboard",
    "device_id": "A1B2C3D4-0001",
    "participants": [
      {
        "handle": "+61412345678",
        "name": "Ann Lee"
      }
    ],
    "last_message_at": "2026-11-03T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
400	The line could not do it (no Advanced Mode, offline, or Messages refused)	`The group's line isn't in Advanced Mode`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.write. This integration was granted: …`
404	Group does not exist or is not the installer's (same response for both)	`Group not found or not accessible to this token`

Leave group

POST https://api.bluereacher.com/v1/groups/imessage/{id}/leave

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

Leave an iMessage group on the line.

The line leaves the chat in Messages (Advanced Mode); the group becomes status: "left" and inactive. Its past messages stay in the conversation. A group already left is refused.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The iMessage group key (imsg_group:<n>).

Request

curl -X POST "https://api.bluereacher.com/v1/groups/imessage/imsg_group%3A7/leave" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Left the group",
  "data": {
    "id": "imsg_group:7",
    "channel": "imessage",
    "workspace_id": 7,
    "name": "Family",
    "participant_count": 2,
    "is_active": false,
    "crm_bridged": true,
    "crm_phone": "+881700000007",
    "last_synced_at": null,
    "created_at": "2026-10-20T00:00:00.000Z",
    "updated_at": "2026-11-04T00:00:00.000Z",
    "status": "left",
    "source": "dashboard",
    "device_id": "A1B2C3D4-0001",
    "participants": [
      {
        "handle": "+61412345678",
        "name": "Ann Lee"
      },
      {
        "handle": "bob@icloud.com",
        "name": "Bob"
      }
    ],
    "last_message_at": "2026-11-03T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
400	The line could not do it (no Advanced Mode, offline, or Messages refused)	`The group's line isn't in Advanced Mode`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.write. This integration was granted: …`
404	Group does not exist or is not the installer's (same response for both)	`Group not found or not accessible to this token`

Send to group

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

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

Limits: One attachment per message, 5 MB.

Send a message to a group chat.

A pending_create iMessage group is created in Messages by this first send. One attachment (an https URL, up to 5 MB) per message. Delivery is asynchronous: the row starts pending.

Parameters

Name	In	Type	Required	Description
`channel`	path	enum	yes	The group's channel.
`id`	path	string	yes
`message`	body	string	no	The text. Required when there is no attachment.
`attachments`	body	string	no	One https URL (image, video, audio or document).

Request

curl -X POST "https://api.bluereacher.com/v1/groups/imessage/imsg_group%3A7/messages" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Meeting moved to 3pm."
}'

Responses

A 200 reply (Queued):

{
  "success": true,
  "message": "Message queued for delivery.",
  "data": {
    "id": 84290,
    "status": "pending",
    "message_id": "84290",
    "group_id": "imsg_group:7",
    "channel": "imessage",
    "queued_at": "2026-11-04T05:00:00.000Z"
  }
}

Status	When	Message
200	Queued
400	Nothing to send, or a bad attachment	`message or attachments is required.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): groups.write. This integration was granted: …`
404	Group does not exist or is not the installer's (same response for both)	`Group not found or not accessible to this token`
409	The group was left or retired	`This group is no longer active.`

Group chats

On this page