Built‑in filters

Instead of manually checking every incoming message, you can use the provided filters.

Example

import { Agent, filter } from '@xmtp/agent-sdk';
 
const agent = await Agent.createFromEnv();
 
// Using filter in message handler
agent.on('text', async (ctx) => {
  if (filter.isText(ctx.message)) {
    await ctx.sendText('You sent a text message!');
  }
});
 
// Combine multiple conditions
agent.on('text', async (ctx) => {
  if (
    filter.hasContent(ctx.message) &&
    !filter.fromSelf(ctx.message, ctx.client) &&
    filter.isText(ctx.message)
  ) {
    await ctx.sendText('Valid text message received ✅');
  }
});

For convenience, the filter object can also be imported as f:

// You can import either name:
import { filter, f } from '@xmtp/agent-sdk';
 
// Both work the same way:
if (f.isText(ctx.message)) {
  // Handle message...
}

Available filters

fromSelf
hasContent
isDM
isGroup
isGroupAdmin
isGroupSuperAdmin
isReaction
isReply
isRemoteAttachment
isText
isTextReply

To learn more about all available prebuilt filters, see filter.ts.

Node

import { filter } from '@xmtp/agent-sdk';
 
const fromSelf = <ContentTypes>(
  message: DecodedMessage<ContentTypes>,
  client: Client<ContentTypes>
) => {
  return message.senderInboxId === client.inboxId;
};
 
const hasContent = <ContentTypes>(
  message: DecodedMessage<ContentTypes>
): message is DecodedMessage<ContentTypes> & {
  content: NonNullable<ContentTypes>;
} => {
  return message.content !== undefined && message.content !== null;
};
 
const isDM = (conversation: Conversation): conversation is Dm => {
  return conversation instanceof Dm;
};
 
const isGroup = (conversation: Conversation): conversation is Group => {
  return conversation instanceof Group;
};
 
const isGroupAdmin = (conversation: Conversation, message: DecodedMessage) => {
  if (isGroup(conversation)) {
    return conversation.isAdmin(message.senderInboxId);
  }
  return false;
};
 
const isGroupSuperAdmin = (
  conversation: Conversation,
  message: DecodedMessage
) => {
  if (isGroup(conversation)) {
    return conversation.isSuperAdmin(message.senderInboxId);
  }
  return false;
};
 
const isReaction = (
  message: DecodedMessage
): message is DecodedMessage & { content: Reaction } => {
  return !!message.contentType?.sameAs(ContentTypeReaction);
};
 
const isReply = (
  message: DecodedMessage
): message is DecodedMessage & { content: Reply } => {
  return !!message.contentType?.sameAs(ContentTypeReply);
};
 
const isRemoteAttachment = (
  message: DecodedMessage
): message is DecodedMessage & { content: RemoteAttachment } => {
  return !!message.contentType?.sameAs(ContentTypeRemoteAttachment);
};
 
const isText = (
  message: DecodedMessage
): message is DecodedMessage & { content: string } => {
  return !!message.contentType?.sameAs(ContentTypeText);
};
 
const isTextReply = (message: DecodedMessage) => {
  return isReply(message) && typeof message.content.content === 'string';
};