Create conversations

With your agent, you can create a new conversation, whether it's a group chat or direct message (DM).

Create a new group chat

Once you have the verified identities, create a new group chat. The maximum group chat size is 250 members.

By Ethereum address

Node

const group = await agent.createGroupWithAddresses(
  [bo.address, caro.address],
  createGroupOptions /* optional */
);

By inbox ID

Node

const group = await agent.client.conversations.createGroup(
  [bo.inboxId, caro.inboxId],
  createGroupOptions /* optional */
);

Create a new DM

Once you have the verified identity, get its inbox ID and create a new DM:

By Ethereum address

Node

// by Ethereum address
const dm = await agent.createDmWithAddress(bo.accountAddress);

By inbox ID

Node

const dm = await agent.client.conversations.createDm(bo.inboxId);

Get the address of the sender

Node

import { getTestUrl } from '@xmtp/agent-sdk';
 
agent.on('text', async (ctx) => {
  const senderAddress = ctx.getSenderAddress();
  console.log(`Message from: ${senderAddress}`);
});

Conversation helper methods

Use these helper methods to quickly locate and access specific conversations—whether by conversation ID, topic, group ID, or DM identity—returning the appropriate ConversationContainer, group, or DM object.

Node

// get a conversation by its ID
const conversationById =
  await agent.client.conversations.getConversationById(conversationId);
 
// get a message by its ID
const messageById = await agent.client.conversations.getMessageById(messageId);
 
// get a 1:1 conversation by a peer's inbox ID
const dmByInboxId =
  await agent.client.conversations.getDmByInboxId(peerInboxId);

Check if an identity is reachable

The first step to creating a conversation is to verify that participants' identities are reachable on XMTP. The canMessage method checks each identity's compatibility, returning a response indicating whether each identity can receive messages.

Node

import { Agent, IdentifierKind } from '@xmtp/agent-sdk';
 
const agent = await Agent.createFromEnv();
 
// response is a Map of string (identifier) => boolean (is reachable)
const response = await agent.client.canMessage([
  {
    identifier: '0xcaroAddress',
    identifierKind: IdentifierKind.Ethereum,
  },
]);

Last read times

For conversations with read receipts enabled, you can query when each participant last read the conversation. This enables features like showing which messages are unread or displaying "seen by" indicators.

Node

// Returns an object keyed by inbox ID
const lastReadTimes = await group.lastReadTimes();
 
// Get the last read time of an inbox in nanoseconds
const inboxLastReadTimeNs = lastReadTimes[inboxId];