Groups

im.groups covers iMessage group-only operations: display names, participants, group icons, leaving, and group events. Group methods use the group chat’s chat.guid. If you only have email addresses or phone numbers, create the group first with im.chats.create(...). Direct chats cannot use group APIs. Shared chat features, such as chat creation, read state, typing, and chat backgrounds, are documented under chats.

What You Can Do

Need	Use this when
Rename a group	You want to change the group display name
Add participants	You want to invite new email addresses or phone numbers
Remove participants	You want to remove existing group members
Set an icon	You want to use image bytes as the group avatar
Download an icon	You need the current custom group avatar
Remove an icon	You want to clear the custom group avatar
Leave a group	The current account should leave the group
Subscribe to events	You need live group name, participant, or icon changes

Group Chat GUIDs

Except for subscribeEvents(...), which takes an optional { chat } filter, group methods take the group chat.guid as their first argument. Create or fetch a group chat first:

const { chat: group } = await im.chats.create(["[email protected]", "[email protected]"]);

Then pass group.guid to group operations:

await im.groups.setDisplayName(group.guid, "Weekend");

Group chat GUIDs usually look like any;+;group-id. Do not pass email addresses, phone numbers, or direct-chat GUIDs to group methods.

Rename

const updated = await im.groups.setDisplayName(group.guid, "Weekend");

Returns the updated Chat. The display name is trimmed and must not be empty after trimming.

Add Participants

const updated = await im.groups.addParticipants(group.guid, ["[email protected]", "+15551234567"]);

Returns the updated Chat.

Input	Rule
`chat`	Group `chat.guid`
`addresses`	Non-empty array; each item must be a full email address or E.164 phone number

The server rejects duplicate addresses, addresses that are already in the group, and addresses it cannot resolve.

Remove Participants

const updated = await im.groups.removeParticipants(group.guid, ["[email protected]"]);

Returns the updated Chat.

Input	Rule
`chat`	Group `chat.guid`
`addresses`	Non-empty array; each item must already be a participant

Removing participants usually requires the current account to have permission to manage the group. The server rejects unknown addresses, duplicate addresses, and removals the current account is not allowed to perform.

Group Icons

Group icons use raw image bytes. They are not attachment GUIDs, and you do not upload them through im.attachments first.

Set an Icon

await im.groups.setIcon(group.guid, await readFile("icon.png"));

Returns void. data must not be empty. The server detects the image type from the bytes. PNG, JPEG, GIF, HEIC, and HEIF are supported.

Download an Icon

const icon = await im.groups.getIcon(group.guid);

console.log(icon.mimeType, icon.data.byteLength);

Returns GroupIcon:

{
  "data":     [137, 80, 78, 71],  // Uint8Array; raw image bytes
  "mimeType": "image/png"         // Server-detected MIME type
}

When no custom icon exists, getIcon(...) throws NotFoundError, with error.code === ErrorCode.groupIconNotFound.

Remove an Icon

await im.groups.removeIcon(group.guid);

Returns void. Removing an icon is safe to repeat, even when no custom icon is set.

Leave a Group

await im.groups.leave(group.guid);

Returns void.

leave(...) makes the current account leave the group. It cannot rejoin by itself; another participant must invite it again.

Group write methods accept optional { clientMessageId } for idempotent retries from your job system. Most direct calls can omit it. See error handling for details.

Group Events

subscribeEvents(...) returns TypedEventStream<GroupEvent>. Use the stream to observe changes made by other people, other devices, or another part of your system. Immediately after your code calls a write method, use that method’s Chat result or completion status.

Scope

Only one group:

const stream = im.groups.subscribeEvents({
  chat: group.guid,
});

All visible group events:

const stream = im.groups.subscribeEvents();

Outer Event

Every group event has type: "group.changed". The outer fields answer which group changed, who triggered it, and when:

{
  "type":       "group.changed",          // Fixed value for group change events
  "chatGuid":   "any;+;group-id",         // Group chat that changed
  "sequence":   123,                      // Event sequence for ordering and catch-up
  "isFromMe":   false,                    // Triggered by the current account
  "occurredAt": "2026-01-01T12:00:00Z",   // Event time
  "actor": {                              // Participant that triggered the event; may be absent
    "address": "[email protected]",
    "service": "iMessage"
  },
  "change": {                             // The actual group change
    "type": "displayNameChanged",
    "displayName": "Weekend"
  }
}

Change Types

event.change.type tells you what changed. Each type carries different fields:

`event.change.type`	Meaning	Extra fields
`displayNameChanged`	The group was renamed	`displayName`
`participantAdded`	A participant joined	`participant`
`participantRemoved`	A participant was removed	`participant`
`participantLeft`	A participant left on their own	`participant`
`iconChanged`	The group icon was set or replaced	None
`iconRemoved`	The group icon was cleared	None

{
  "type":        "displayNameChanged",  // The group was renamed
  "displayName": "Weekend"              // New group name
}

{
  "type": "participantAdded",           // A participant joined
  "participant": {                      // Participant that joined
    "address": "[email protected]",
    "service": "iMessage"
  }
}

{
  "type": "participantRemoved",         // A participant was removed
  "participant": {                      // Participant that was removed
    "address": "[email protected]",
    "service": "iMessage"
  }
}

{
  "type": "participantLeft",            // A participant left on their own
  "participant": {                      // Participant that left
    "address": "[email protected]",
    "service": "iMessage"
  }
}

{
  "type": "iconChanged"                 // The group icon was set or replaced
}

{
  "type": "iconRemoved"                 // The group icon was cleared
}

Handle Events

Switch on event.change.type. When you subscribe to one group, you do not need to check chatGuid again:

for await (const event of im.groups.subscribeEvents({ chat: group.guid })) {
  switch (event.change.type) {
    case "displayNameChanged":
      console.log(event.change.displayName);
      break;

    case "participantAdded":
    case "participantRemoved":
    case "participantLeft":
      console.log(event.change.type, event.change.participant.address);
      break;

    case "iconChanged":
    case "iconRemoved":
      console.log(event.change.type);
      break;
  }
}

When you subscribe to all visible groups, use event.chatGuid to identify the group:

for await (const event of im.groups.subscribeEvents()) {
  console.log(event.chatGuid, event.change.type);
}

If the stream disconnects, use events to catch up on missed durable events, then continue consuming the live stream.

Next Steps

Chats — create a group chat and get chat.guid
Messages — send messages, attachments, and reactions in a group chat
Events — catch up on durable events after a disconnect
Error Handling — handle NotFoundError, ValidationError, and idempotent retries

Advanced Kits

Opensource Kits

Utilities

What You Can Do

Group Chat GUIDs

Rename

Add Participants

Remove Participants

Group Icons

Set an Icon

Download an Icon

Remove an Icon

Leave a Group

Group Events

Scope

Outer Event

Change Types

Handle Events

Next Steps

​What You Can Do

​Group Chat GUIDs

​Rename

​Add Participants

​Remove Participants

​Group Icons

​Set an Icon

​Download an Icon

​Remove an Icon

​Leave a Group

​Group Events

​Scope

​Outer Event

​Change Types

​Handle Events

​Next Steps

What You Can Do

Group Chat GUIDs

Rename

Add Participants

Remove Participants

Group Icons

Set an Icon

Download an Icon

Remove an Icon

Leave a Group

Group Events

Scope

Outer Event

Change Types

Handle Events

Next Steps