Managing Chats

Overview

The Advanced iMessage Kit SDK provides comprehensive chat management capabilities including fetching chats, creating group conversations, managing participants, and customizing chat settings.

Getting Chats

Fetch all chats

Get a list of all your iMessage conversations.

const chats = await sdk.chats.getChats();

console.log(`You have ${chats.length} chats`);

chats.forEach((chat, i) => {
  console.log(`${i + 1}. ${chat.displayName || chat.chatIdentifier}`);
});

Get a specific chat

Retrieve detailed information about a single chat.

const chat = await sdk.chats.getChat("iMessage;-;+1234567890");

console.log("Chat details:");
console.log(`  GUID: ${chat.guid}`);
console.log(`  Display Name: ${chat.displayName || "(none)"}`);
console.log(`  Participants: ${chat.participants?.length || 0}`);

Chat Queries

Fetch chats with specific options and filters.

// Get chats with last message included
const chatsWithMessages = await sdk.chats.getChats({
  withLastMessage: true,
  limit: 20,
  offset: 0
});

chatsWithMessages.forEach(chat => {
  if (chat.lastMessage) {
    const preview = chat.lastMessage.text?.substring(0, 50) || "(no text)";
    console.log(`${chat.displayName}: ${preview}`);
  }
});

// Include archived chats
const allChats = await sdk.chats.getChats({
  withArchived: true
});

console.log(`Total chats (including archived): ${allChats.length}`);

Getting Chat Details

Retrieve a chat with additional related data.

const CHAT_GUID = "iMessage;-;+1234567890";

// Get chat with last message
const chatWithLastMessage = await sdk.chats.getChat(CHAT_GUID, {
  with: ["lastMessage"]
});

if (chatWithLastMessage.lastMessage) {
  console.log("Last message:");
  console.log(`  Text: ${chatWithLastMessage.lastMessage.text}`);
  console.log(`  From: ${chatWithLastMessage.lastMessage.isFromMe ? "me" : "them"}`);
  console.log(`  Date: ${new Date(chatWithLastMessage.lastMessage.dateCreated).toLocaleString()}`);
}

// Get chat with participants
const chatWithParticipants = await sdk.chats.getChat(CHAT_GUID);

if (chatWithParticipants.participants?.length) {
  console.log("\nParticipants:");
  chatWithParticipants.participants.forEach((p, i) => {
    console.log(`  ${i + 1}. ${p.address}`);
  });
}

Identifying Group Chats

Filter and work with group conversations.

const allChats = await sdk.chats.getChats();

// Group chats have style 43, 1-on-1 chats have style 45
const groupChats = allChats.filter(chat => "style" in chat && chat.style === 43);
const directChats = allChats.filter(chat => "style" in chat && chat.style === 45);

console.log(`Group chats: ${groupChats.length}`);
console.log(`Direct chats: ${directChats.length}`);

groupChats.forEach((group, i) => {
  console.log(`\n${i + 1}. ${group.displayName || group.chatIdentifier}`);
  console.log(`   GUID: ${group.guid}`);
  console.log(`   Participants: ${group.participants?.length || 0}`);
  
  if (group.participants?.length) {
    group.participants.slice(0, 3).forEach(p => {
      console.log(`     - ${p.address}`);
    });
    if (group.participants.length > 3) {
      console.log(`     ... and ${group.participants.length - 3} more`);
    }
  }
});

Chat styles:

43 = Group chat (3+ participants)
45 = Direct message (1-on-1)

Creating Group Chats

Create a new group conversation with multiple participants.

const groupChat = await sdk.chats.createChat({
  addresses: ["+1234567890", "+0987654321", "+1122334455"],
  message: "Welcome to the team chat!"
});

console.log(`Created group: ${groupChat.guid}`);
console.log(`Participants: ${groupChat.participants?.length}`);

With Initial Message
Without Initial Message
With Effects

const chat = await sdk.chats.createChat({
  addresses: ["+1234567890", "+0987654321"],
  message: "Let's start planning the event!",
  service: "iMessage"
});

console.log(`Chat created: ${chat.guid}`);

// Create group without sending a message
const chat = await sdk.chats.createChat({
  addresses: ["+1234567890", "+0987654321", "+1122334455"]
});

// Send a message later
await sdk.messages.sendMessage({
  chatGuid: chat.guid,
  message: "Hello everyone!"
});

const chat = await sdk.chats.createChat({
  addresses: ["+1234567890", "+0987654321"],
  message: "Happy Birthday!",
  effectId: "com.apple.messages.effect.CKConfettiEffect",
  method: "private-api" // Required for effects
});

Managing Participants

Add or remove people from group chats.

Adding Participants

const GROUP_GUID = "iMessage;+;chat123456";
const NEW_MEMBER = "+1234567890";

try {
  const updatedChat = await sdk.chats.addParticipant(GROUP_GUID, NEW_MEMBER);
  
  console.log(`Added ${NEW_MEMBER} to group`);
  console.log(`Current members: ${updatedChat.participants?.map(p => p.address).join(", ")}`);
} catch (error) {
  console.error("Failed to add participant:", error.message);
}

Removing Participants

const GROUP_GUID = "iMessage;+;chat123456";
const MEMBER_TO_REMOVE = "+1234567890";

try {
  const updatedChat = await sdk.chats.removeParticipant(GROUP_GUID, MEMBER_TO_REMOVE);
  
  console.log(`Removed ${MEMBER_TO_REMOVE} from group`);
  console.log(`Remaining members: ${updatedChat.participants?.map(p => p.address).join(", ")}`);
} catch (error) {
  console.error("Failed to remove participant:", error.message);
}

Leaving a Group

const GROUP_GUID = "iMessage;+;chat123456";

try {
  await sdk.chats.leaveChat(GROUP_GUID);
  console.log("Successfully left the group");
} catch (error) {
  console.error("Failed to leave group:", error.message);
}

Removing participants requires administrator permissions in the group. Attempting to remove someone without proper permissions will fail.

Updating Chat Settings

Modify chat properties like display name.

const GROUP_GUID = "iMessage;+;chat123456";

// Update group name
const updatedChat = await sdk.chats.updateChat(GROUP_GUID, {
  displayName: "Engineering Team"
});

console.log(`Updated group name to: ${updatedChat.displayName}`);

Group Icons

Set and manage group chat icons.

Set a group icon

Upload an image file as the group icon.

import path from "path";

const GROUP_GUID = "iMessage;+;chat123456";
const iconPath = path.join(__dirname, "group-icon.png");

await sdk.chats.setGroupIcon(GROUP_GUID, iconPath);
console.log("Group icon updated");

Download the group icon

Retrieve the current group icon.

import fs from "fs";

const iconBuffer = await sdk.chats.getGroupIcon(GROUP_GUID);

fs.writeFileSync("downloaded-icon.png", iconBuffer);
console.log("Icon downloaded");

Remove the group icon

Delete the group icon.

await sdk.chats.removeGroupIcon(GROUP_GUID);
console.log("Group icon removed");

Chat Messages

Get messages from a specific chat.

const CHAT_GUID = "iMessage;-;+1234567890";

// Get last 50 messages
const messages = await sdk.chats.getChatMessages(CHAT_GUID, {
  limit: 50,
  sort: "DESC", // Most recent first
  with: ["attachment", "handle"]
});

console.log(`Found ${messages.length} messages`);

messages.forEach(msg => {
  const sender = msg.isFromMe ? "Me" : msg.handle?.address;
  const time = new Date(msg.dateCreated).toLocaleString();
  const hasAttachment = msg.attachments?.length ? " 📎" : "";
  
  console.log(`[${time}] ${sender}: ${msg.text}${hasAttachment}`);
});

Pagination

// Get messages in batches
const BATCH_SIZE = 25;
let offset = 0;
let hasMore = true;

while (hasMore) {
  const batch = await sdk.chats.getChatMessages(CHAT_GUID, {
    limit: BATCH_SIZE,
    offset: offset,
    sort: "DESC"
  });
  
  console.log(`Fetched ${batch.length} messages (offset: ${offset})`);
  
  // Process batch
  batch.forEach(msg => {
    console.log(`  ${msg.text?.substring(0, 50)}`);
  });
  
  offset += BATCH_SIZE;
  hasMore = batch.length === BATCH_SIZE;
}

Marking Chats

Mark chats as read or unread.

const CHAT_GUID = "iMessage;-;+1234567890";

// Mark as read
await sdk.chats.markChatRead(CHAT_GUID);
console.log("Chat marked as read");

// Mark as unread
await sdk.chats.markChatUnread(CHAT_GUID);
console.log("Chat marked as unread");

Deleting Chats

Remove a chat from your device.

const CHAT_GUID = "iMessage;-;+1234567890";

try {
  await sdk.chats.deleteChat(CHAT_GUID);
  console.log("Chat deleted successfully");
} catch (error) {
  console.error("Failed to delete chat:", error.message);
}

Deleting a chat removes it from your local device only. The conversation may still exist for other participants.

Typing Indicators

Show typing status in a chat.

const CHAT_GUID = "iMessage;-;+1234567890";

// Start typing indicator
await sdk.chats.startTyping(CHAT_GUID);
console.log("Typing indicator shown");

// Simulate typing for 3 seconds
await new Promise(resolve => setTimeout(resolve, 3000));

// Stop typing indicator
await sdk.chats.stopTyping(CHAT_GUID);
console.log("Typing indicator hidden");

// Send the actual message
await sdk.messages.sendMessage({
  chatGuid: CHAT_GUID,
  message: "Hello!"
});

Chat Count

Get the total number of chats.

const count = await sdk.chats.getChatCount();

console.log(`Total chats: ${count.total}`);
console.log(`Breakdown:`, count.breakdown);

// Include archived chats
const countWithArchived = await sdk.chats.getChatCount({
  includeArchived: true
});

console.log(`Total (with archived): ${countWithArchived.total}`);

Monitoring Group Events

Listen for real-time group changes.

sdk.on("group-name-change", (data) => {
  console.log(`Group name changed to: ${data.groupTitle}`);
  console.log(`Chat: ${data.displayName || data.guid}`);
});

sdk.on("participant-added", (data) => {
  console.log(`Someone was added to: ${data.displayName || data.guid}`);
});

sdk.on("participant-removed", (data) => {
  console.log(`Someone was removed from: ${data.displayName || data.guid}`);
});

sdk.on("participant-left", (data) => {
  console.log(`Someone left: ${data.displayName || data.guid}`);
});

sdk.on("group-icon-changed", (data) => {
  console.log(`Group icon changed: ${data.displayName || data.guid}`);
});

sdk.on("group-icon-removed", (data) => {
  console.log(`Group icon removed: ${data.displayName || data.guid}`);
});

Chat Backgrounds

Customize chat backgrounds (requires Private API).

Set from URL
Set from File
Get Background
Remove Background

const CHAT_GUID = "iMessage;-;+1234567890";

await sdk.chats.setBackground(CHAT_GUID, "https://example.com/background.jpg");
console.log("Background set from URL");

import path from "path";

const CHAT_GUID = "iMessage;-;+1234567890";
const bgPath = path.join(__dirname, "background.jpg");

await sdk.chats.setBackground(CHAT_GUID, {
  filePath: bgPath
});

console.log("Background set from file");

const background = await sdk.chats.getBackground(CHAT_GUID);

console.log(`Has background: ${background.hasBackground}`);
if (background.imageUrl) {
  console.log(`Image URL: ${background.imageUrl}`);
}

await sdk.chats.removeBackground(CHAT_GUID);
console.log("Background removed");

Chat backgrounds require the Private API feature to be enabled on your server.

Next Steps

Working with Attachments

Send and receive files, images, and media

Real-Time Events

Learn about all available events

Get Started

Core Concepts

Guides

Overview

Getting Chats

Chat Queries

Getting Chat Details

Identifying Group Chats

Creating Group Chats

Managing Participants

Adding Participants

Removing Participants

Leaving a Group

Updating Chat Settings

Group Icons

Chat Messages

Marking Chats

Deleting Chats

Typing Indicators

Chat Count

Monitoring Group Events

Chat Backgrounds

Next Steps

Working with Attachments

Real-Time Events

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Overview

​Getting Chats

​Chat Queries

​Getting Chat Details

​Identifying Group Chats

​Creating Group Chats

​Managing Participants

​Adding Participants

​Removing Participants

​Leaving a Group

​Updating Chat Settings

​Group Icons

​Chat Messages

​Pagination

​Marking Chats

​Deleting Chats

​Typing Indicators

​Chat Count

​Monitoring Group Events

​Chat Backgrounds

​Next Steps

Working with Attachments

Real-Time Events

Build docs developers (and LLMs) love

Overview

Getting Chats

Chat Queries

Getting Chat Details

Identifying Group Chats

Creating Group Chats

Managing Participants

Adding Participants

Removing Participants

Leaving a Group

Updating Chat Settings

Group Icons

Chat Messages

Pagination

Marking Chats

Deleting Chats

Typing Indicators

Chat Count

Monitoring Group Events

Chat Backgrounds

Next Steps