SDK API reference

The Messaging SDK APIs follow the lifecycle of a secure communication system: create groups, manage membership, send messages, and maintain encryption state.

All methods are accessed through the client.messaging namespace after setup.

For permission management (grant, revoke, check membership), use client.groups. See the Sui Groups API Reference.

Key types

`GroupRef`

Most methods accept a GroupRef to identify a group. Either form works:

type GroupRef =
  | { uuid: string }                                        // derives both IDs
  | { groupId: string; encryptionHistoryId: string };       // explicit IDs

`DecryptedMessage`

Returned by getMessage, getMessages, and subscribe:

interface DecryptedMessage {
  messageId: string;
  groupId: string;
  order: number;
  text: string;                    // empty string for deleted or attachment-only messages
  senderAddress: string;
  createdAt: number;               // unix timestamp (seconds)
  updatedAt: number;
  isEdited: boolean;
  isDeleted: boolean;
  syncStatus?: SyncStatus;         // Walrus sync state (when relayer archives)
  attachments: AttachmentHandle[]; // lazy-download handles
  senderVerified: boolean;         // per-message signature verified
}

`AttachmentHandle`

Resolved attachment with lazy download:

interface AttachmentHandle {
  fileName: string;
  mimeType: string;
  fileSize: number;
  extras?: Record<string, unknown>;
  wire: Attachment;                // raw wire format (for edits)
  data(): Promise<Uint8Array>;    // download + decrypt on demand
}

`GetMessagesResult`

interface GetMessagesResult {
  messages: DecryptedMessage[];
  hasNext: boolean;
}

`EditAttachments`

interface EditAttachments {
  current: Attachment[];    // current attachments on the message
  remove?: string[];        // storageIds to remove
  new?: AttachmentFile[];   // new files to upload
}

Messaging methods

These methods handle E2EE messaging through the relayer transport. Encryption and decryption are automatic. See Encryption for the underlying encryption model.

`sendMessage(options)`

Encrypt and send a message to a group.

Parameter	Type	Required	Description
`signer`	`Signer`	Yes	Signs the message and authenticates with the relayer
`groupRef`	`GroupRef`	Yes	Target group
`text`	`string`	No*	Message text
`files`	`AttachmentFile[]`	No*	Files to attach (requires attachments config)
`sealApproveContext`	`TApproveContext`	Only with custom SealPolicy	Context for custom Seal policies

*At least one of text or files must be provided.

Returns: { messageId: string }

const { messageId } = await client.messaging.sendMessage({
  signer: keypair,
  groupRef: { uuid: 'my-group' },
  text: 'Hello!',
});

`getMessage(options)`

Fetch and decrypt a single message by ID.

Parameter	Type	Required	Description
`signer`	`Signer`	Yes	Authenticates with the relayer
`groupRef`	`GroupRef`	Yes	Target group
`messageId`	`string`	Yes	Message ID

Returns: DecryptedMessage

const msg = await client.messaging.getMessage({
  signer: keypair,
  groupRef: { uuid: 'my-group' },
  messageId: 'abc123',
});

`getMessages(options)`

Fetch and decrypt a paginated list of messages.

Parameter	Type	Required	Description
`signer`	`Signer`	Yes	Authenticates with the relayer
`groupRef`	`GroupRef`	Yes	Target group
`afterOrder`	`number`	No	Fetch messages after this order (exclusive)
`beforeOrder`	`number`	No	Fetch messages before this order (exclusive)
`limit`	`number`	No	Max messages to return

Returns: GetMessagesResult

Messages that fail decryption (for example, key not available) are silently skipped.

const { messages, hasNext } = await client.messaging.getMessages({
  signer: keypair,
  groupRef: { uuid: 'my-group' },
  limit: 50,
});

`editMessage(options)`

Re-encrypt and update an existing message. Only the original sender can edit.

Parameter	Type	Required	Description
`signer`	`Signer`	Yes	Must be the original sender
`groupRef`	`GroupRef`	Yes	Target group
`messageId`	`string`	Yes	Message to edit
`text`	`string`	Yes	New message text
`attachments`	`EditAttachments`	No	Attachment changes (omit to leave unchanged)

Returns: void

await client.messaging.editMessage({
  signer: keypair,
  groupRef: { uuid: 'my-group' },
  messageId: 'abc123',
  text: 'Updated text',
  attachments: {
    current: originalMsg.attachments.map(a => a.wire),
    remove: ['old-storage-id'],
    new: [{ fileName: 'new.txt', mimeType: 'text/plain', data: bytes }],
  },
});

`deleteMessage(options)`

Soft-delete a message. Only the original sender can delete.

Parameter	Type	Required	Description
`signer`	`Signer`	Yes	Must be the original sender
`groupRef`	`GroupRef`	Yes	Target group
`messageId`	`string`	Yes	Message to delete

Returns: void

`subscribe(options)`

Subscribe to real-time messages for a group. Returns an AsyncIterable that yields decrypted messages as they arrive.

Parameter	Type	Required	Description
`signer`	`Signer`	Yes	Authenticates with the relayer
`groupRef`	`GroupRef`	Yes	Target group
`afterOrder`	`number`	No	Resume from this order (exclusive)
`signal`	`AbortSignal`	No	Cancel the subscription

Returns: AsyncIterable<DecryptedMessage>

Messages that fail decryption are silently skipped.

const controller = new AbortController();

for await (const msg of client.messaging.subscribe({
  signer: keypair,
  groupRef: { uuid: 'my-group' },
  signal: controller.signal,
})) {
  console.log(msg.text, msg.senderVerified);
}

`disconnect()`

Disconnect the underlying transport. Active subscriptions complete.

client.messaging.disconnect();

`recoverMessages(options)`

Recover messages from an alternative storage backend (for example, Walrus). Requires a RecoveryTransport to be configured at client creation. See Archive and Recovery.

Unlike other messaging methods, this does not require a signer because recovery is read-only.

Parameter	Type	Required	Description
`groupRef`	`GroupRef`	Yes	Target group
`afterOrder`	`number`	No	Fetch messages after this order (exclusive)
`beforeOrder`	`number`	No	Fetch messages before this order (exclusive)
`limit`	`number`	No	Max messages to return

Returns: GetMessagesResult

Messages that fail decryption are silently dropped.

const { messages, hasNext } = await client.messaging.recoverMessages({
  groupRef: { uuid: 'my-group' },
  limit: 50,
});

Group management methods

Onchain transactions for group lifecycle. Each method signs and executes a transaction.

`createAndShareGroup(options)`

Create a new messaging group and share both objects (PermissionedGroup and EncryptionHistory). The transaction sender becomes the creator with all permissions.

Parameter	Type	Required	Description
`signer`	`Signer`	Yes	Transaction sender (becomes group creator)
`name`	`string`	Yes	Human-readable group name
`uuid`	`string`	No	UUID for deterministic addressing (generated if omitted)
`initialMembers`	`string[]`	No	Addresses to grant `MessagingReader` on creation