Sending Messages

Send messages, work with content types, and handle message delivery in LibXMTP

This guide covers sending messages, working with different content types, and managing message delivery in LibXMTP groups.

Sending Text Messages

Basic Message Sending

Send a simple text message:

use xmtp_mls::groups::send_message_opts::SendMessageOpts;
use xmtp_content_types::text::TextCodec;
use xmtp_content_types::ContentCodec;

// Encode text content
let text_content = TextCodec::encode("Hello, world!".to_string())?;
let encoded_bytes = encoded_content_to_bytes(text_content)?;

// Send the message
let message_id = group.send_message(&encoded_bytes, SendMessageOpts::default()).await?;

Messages are sent as encoded content that specifies the content type. This allows receivers to properly decode and display the message.

Send Message Options

Control message behavior with SendMessageOpts:

use xmtp_mls::groups::send_message_opts::SendMessageOptsBuilder;

// Configure send options
let opts = SendMessageOptsBuilder::default()
    .should_push(true)  // Trigger push notifications
    .build()?;

let message_id = group.send_message(&encoded_bytes, opts).await?;

Optimistic Sending

Send messages without waiting for network confirmation:

// Message is stored locally and queued for sending
let message_id = group.send_message_optimistic(
    &encoded_bytes,
    SendMessageOpts::default()
)?;

// Later, publish all pending messages
group.publish_messages().await?;

Optimistic messages are visible locally immediately but may fail to send. Always call publish_messages() to ensure delivery.

Content Types

LibXMTP supports multiple content types for rich messaging.

Text Content

use xmtp_content_types::text::TextCodec;

let content = TextCodec::encode("Hello!".to_string())?;
let bytes = encoded_content_to_bytes(content)?;

group.send_message(&bytes, SendMessageOpts::default()).await?;

Reactions

Send reactions to messages:

use xmtp_content_types::reaction::{ReactionCodec, ReactionAction};
use xmtp_proto::xmtp::mls::message_contents::content_types::ReactionV2;

let reaction = ReactionV2 {
    reference: hex::encode(&target_message_id),  // Message being reacted to
    action: ReactionAction::Added as i32,
    content: "👍".to_string(),
    schema: 1,
};

let encoded = ReactionCodec::encode(reaction)?;
let bytes = encoded_content_to_bytes(encoded)?;

group.send_message(&bytes, SendMessageOpts::default()).await?;

Replies

Reply to specific messages:

use xmtp_content_types::reply::{ReplyCodec, Reply};

let reply = Reply {
    reference: hex::encode(&original_message_id),
    content_type: Some(TextCodec::content_type()),
    content: TextCodec::encode("Thanks!".to_string())?,
};

let encoded = ReplyCodec::encode(reply)?;
let bytes = encoded_content_to_bytes(encoded)?;

group.send_message(&bytes, SendMessageOpts::default()).await?;

Delete Messages

Delete your own messages or (as super admin) others’ messages:

use xmtp_proto::xmtp::mls::message_contents::content_types::DeleteMessage;
use xmtp_content_types::delete_message::DeleteMessageCodec;

let delete_msg = DeleteMessage {
    message_id: hex::encode(&message_id_to_delete),
};

let encoded = DeleteMessageCodec::encode(delete_msg)?;
let bytes = encoded_content_to_bytes(encoded)?;

let deletion_id = group.send_message(&bytes, SendMessageOpts::default()).await?;

Or use the helper method:

// Delete a message (validates permissions automatically)
let deletion_id = group.delete_message(&message_id).await?;

Reading Messages

Message Delivery Status

Check Delivery Status

use xmtp_db::group_message::DeliveryStatus;

let messages = group.find_messages(&MsgQueryArgs::default())?;

for msg in messages {
    match msg.delivery_status {
        DeliveryStatus::Published => {
            println!("Message sent successfully");
        }
        DeliveryStatus::Unpublished => {
            println!("Message pending (optimistic send)");
        }
        DeliveryStatus::Failed => {
            println!("Message failed to send");
        }
    }
}

Publish Pending Messages

Send all locally queued messages:

// Publish optimistic messages
group.publish_messages().await?;

// Check if any messages failed
let failed_args = MsgQueryArgs::default()
    .delivery_status(Some(vec![DeliveryStatus::Failed]));

let failed = group.find_messages(&failed_args)?;
if !failed.is_empty() {
    eprintln!("Warning: {} messages failed to send", failed.len());
}

Advanced Usage

Custom Content Types

Define your own content type:

use xmtp_proto::xmtp::mls::message_contents::EncodedContent;
use prost::Message;

// Your custom message structure
#[derive(Message)]
struct CustomMessage {
    #[prost(string, tag = "1")]
    pub custom_field: String,
}

// Encode as EncodedContent
let custom = CustomMessage {
    custom_field: "value".to_string(),
};

let mut content_bytes = Vec::new();
custom.encode(&mut content_bytes)?;

let encoded = EncodedContent {
    r#type: Some(ContentTypeId {
        authority_id: "your.authority".to_string(),
        type_id: "custom-type".to_string(),
        version_major: 1,
        version_minor: 0,
    }),
    content: content_bytes,
    ..Default::default()
};

let mut bytes = Vec::new();
encoded.encode(&mut bytes)?;

group.send_message(&bytes, SendMessageOpts::default()).await?;

Message Count

Count messages matching criteria:

let count = group.count_messages(&MsgQueryArgs::default())?;
println!("Total messages: {}", count);

// Count unread messages
let unread_args = MsgQueryArgs::default()
    .sent_after_ns(Some(last_read_timestamp));

let unread_count = group.count_messages(&unread_args)?;

Read Receipts

Get last read times by sender:

let read_times = group.get_last_read_times()?;

for (sender_inbox_id, timestamp) in read_times {
    println!("{} last read at {}", sender_inbox_id, timestamp);
}

TypeScript (Node.js) Examples

Send Text

import { Conversation } from '@xmtp/node-bindings'

// Send text message
const messageId = await conversation.sendText('Hello, world!')

// Send with optimistic delivery
const messageId = await conversation.sendText('Hello!', true)

// Publish pending messages
await conversation.publishMessages()

Error Handling

use xmtp_mls::groups::GroupError;

match group.send_message(&bytes, opts).await {
    Ok(message_id) => {
        println!("Message sent: {}", hex::encode(message_id));
    }
    Err(GroupError::InvalidPermission) => {
        eprintln!("You don't have permission to send messages");
    }
    Err(GroupError::NotFound(NotFound::MlsGroup)) => {
        eprintln!("Group not found locally, try syncing");
    }
    Err(e) => {
        eprintln!("Failed to send: {}", e);
    }
}

Best Practices

Next Steps

Permissions and Policies

Control who can send messages and perform actions

Consent Management

Manage user consent and block unwanted messages