Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/photon-hq/advanced-imessage-kit/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Learn how to initialize the Advanced iMessage Kit SDK and perform basic operations like sending messages and listening for incoming messages.

​
Sending a Message

The simplest way to send a message is to initialize the SDK, wait for the ready event, and use the sendMessage method. 
import { createSDK, handleError } from "./utils";

const CHAT_GUID = process.env.CHAT_GUID || "any;-;+1234567890";

async function main() {
    const sdk = createSDK();

    sdk.on("ready", async () => {
        try {
            const message = await sdk.messages.sendMessage({
                chatGuid: CHAT_GUID,
                message: "Hello from MOBAI!",
            });

            console.log(`sent: ${message.guid}`);
            console.log(`${new Date(message.dateCreated).toLocaleString()}`);
        } catch (error) {
            handleError(error, "Failed to send message");
        }

        await sdk.close();
        process.exit(0);
    });

    await sdk.connect();
}

main().catch(console.error);

​
Key Points

  • Initialize the SDK with createSDK()
  • Wait for the ready event before performing operations
  • Use chatGuid to specify which conversation to send to
  • The returned message object contains metadata like guid and dateCreated
  • Always close the SDK connection when done

​
Listening for Messages

To build a message listener that handles incoming messages in real-time: 
import { getPollSummary, isPollMessage } from "../lib/poll-utils";
import { createSDK, handleExit } from "./utils";

async function main() {
    const sdk = createSDK();

    sdk.on("ready", () => {
        console.log("ready");
    });

    sdk.on("new-message", (message) => {
        const sender = message.handle?.address ?? "unknown";

        if (isPollMessage(message)) {
            const pollSummary = getPollSummary(message);
            console.log(`\n${sender}: ${pollSummary}`);
        } else {
            console.log(`\n${sender}: ${message.text ?? "(no text)"}`);
        }
    });

    sdk.on("updated-message", (message) => {
        const status = message.dateRead ? "read" : message.dateDelivered ? "delivered" : "sent";
        console.log(status);
    });

    sdk.on("error", (error) => {
        console.error("error:", error.message);
    });

    await sdk.connect();
    handleExit(sdk);
}

main().catch(console.error);

​
Event Handlers

Fired when a new message is received. The message object contains:
  • handle.address - Sender’s phone number or email
  • text - Message text content
  • isFromMe - Boolean indicating if you sent the message
Fired when a message status changes (delivered, read, etc.):
  • dateRead - Timestamp when message was read
  • dateDelivered - Timestamp when message was delivered
  • dateSent - Timestamp when message was sent
Handles SDK errors. Always implement this handler for production apps.

​
Getting Chat GUIDs

To find a chat GUID for sending messages, you can list all your chats: 
const chats = await sdk.chats.getChats();
chats.forEach(chat => {
    console.log(`${chat.displayName}: ${chat.guid}`);
});
For phone numbers, the chat GUID format is typically any;-;+1234567890

​
Next Steps

Auto-Reply Bot

Build an automated responder

Message Effects

Add visual effects to messages

Reactions

Send tapbacks and reactions

Group Chats

Manage group conversations

Build docs developers (and LLMs) love

Get started for freeTalk to us