Module messages

Expand description

Message builders.

Any MessageLike value can be passed to send message methods and then modified by a plenty of builder options as shown in the usage examples below

§Simple text

// Regular text message
bot.send_msg(chat, "Hello").await?;

// Regular text reply with TTL
bot.send_msg(chat, "Hello")
    .reply_to(msg)
    .with_ttl(Duration::from_secs(3600))
    .await?;

// Formatted text
bot.send_msg(chat, Text::yellow("Warning: operation is cancelledd")).await?;

// Heavily-formatted text
bot.send_msg(
    chat,
    format!("{}\n\nThe operation {} {}",
        "Attention".bold(),
        op.italic(),
        "is not permitted".red()
    )
).await?;

§Simple files

// Plain file with caption
bot.send_msg(
    chat,
    File::new("document.pdf")
        .with_caption("Here's the doc")
).await?;

// Same as above but with a message builder method
bot.send_msg(chat, File::new("document.pdf"))
   .set_text("Here's the doc")
   .await?;

// Attach a CryptoFile to a text message
bot.send_msg(chat, "See attached")
   .attach(crypto_file)
   .await?;

§Images

// With multimedia: source file is automatically transcoded into a thumbnail
// Without multimedia: sends with the default placeholder as a preview
bot.send_msg(chat, Image::new("img.jpg")).await?;

// Override transcoder settings(requires `multimedia` feature)
bot.send_msg(chat, Image::new("img.jpg"))
    .with_transcoder(
        Transcoder::default()
            .with_size(200, 200)
            .with_quality(80)
            .with_blur(1.5)
    ).await?;

// Get thumbnail from in memory bytes. With `multimedia` feature the bytes will be transcoded
// to JPG so with_transcoder(Transcoder::disabled()) is used to opt out, without multimedia the bytes
// are used as is
bot.send_msg(chat, Image::new("img.jpg"))
    .with_preview(
        ImagePreview::from_bytes(thumb_bytes)
            .with_transcoder(Transcoder::disabled())
    ).await?;

// Thumbnail from a separate file(read asyncronously at send time)
bot.send_msg(chat, Image::new("img.jpg"))
    .with_preview(ImagePreview::from_file("thumb.jpg"))
    .await?;

// Encrypted source and thumbnail(requires feature `native_crypto`)
bot.send_msg(chat, Image::from(image_crypto_file))
    .with_preview(ImagePreview::from_crypto_file(thumb_crypto_file))
    .await?;

// Text transitioning to image so "Here is the photo" becomes the caption
bot.send_msg(chat, "Here is the photo")
    .with_image(Image::new("img.jpg"))
    .await?;

§Video

Automatic preview generation from video files is currently unsupported. A custom preview can be provided, or the message sends with the default placeholder preview.

// Default placeholder preview
bot.send_msg(chat, Video::new("vid.mp4", Duration::from_secs(30))).await?;

// Custom thumbnail
bot.send_msg(chat, Video::new("vid.mp4", Duration::from_secs(30)))
    .with_preview(ImagePreview::from_bytes(thumb_bytes))
    .await?;

// Custom thumbnail from a file, resized at send time(requires `multimedia`)
bot.send_msg(chat, Video::new("vid.mp4", Duration::from_secs(30)))
    .with_preview(
        ImagePreview::from_file("thumb.jpg")
            .with_transcoder(Transcoder::default().with_size(255, 255))
    )
    .await?;

§Link

// Minimal: no preview image, no metadata
bot.send_msg(chat, Link::new("https://example.com")).await?;

// Full Open Graph preview
let og_bytes: Vec<u8> = fetch_og_image("https://example.com").await?;
bot.send_msg(chat,
    Link::new("https://example.com")
        .with_title("Example Domain")
        .with_description("Domain description")
        .with_content(LinkContent::make_page())
)
.with_preview(ImagePreview::from_bytes(og_bytes))
.await?;

// Text transitioning to link
bot.send_msg(chat, "Check this out")
    .with_link(Link::new("https://example.com").with_title("Example"))
    .await?;

§Special messages like reports and chat links

// Report
bot.send_msg(chat, Report::spam("Unsolicited advertisement")).await?;

// Report via text transition so the text becomes the report body
bot.send_msg(chat, "Unsolicited advertisement").report(ReportReason::Spam).await?;

// Chat invitation
bot.send_msg(chat, Chat::new(chat_link).with_text("Join our group")).await?;

§Custom and Raw messages

Custom messages are useful for implementing interbot protocols

bot.send_msg(chat, Custom::new("app.ping", &PingPayload { id: 42 })).await?;

ComposedMessage is for dynamic construction scenarios where the message content, media type, or delivery options are determined by program logic rather than known at compile time. Because ComposedMessage is sent verbatim, preview resolution is the caller’s responsibility.

// resolve() always returns a valid preview string, falling back to the default on any error
let preview = ImagePreview::from_file("thumb.jpg").resolve().await;

// try_resolve() surfaces the error so the caller can dechate what to do
let preview = match ImagePreview::from_file("thumb.jpg").try_resolve().await {
    Ok(s) => s,
    Err(e) => {
        log::error!("Preview failed: {e}");
        return Err(e.into());
    }
};

let mut msg = ComposedMessage {
    file_source: None,
    msg_content: MsgContent::make_text(String::new()),
    quoted_item_id: None,
    mentions: Default::default(),
    undocumented: Default::default(),
};

if let Some(image_file) = attachment {
    msg.file_source = Some(image_file);
    msg.msg_content = MsgContent::make_image(caption, preview);
}

if let Some(id) = reply_to_id {
    msg.quoted_item_id = Some(id);
}

bot.send_msg(chat, msg).await?;

§Broadcasts & Multicasts

prepare_broadcast fetches the recipient list asynchronously, then returns a MulticastBuilder. Preview is resolved only once and the result is cloned for every recipient.

// All known chats
bot.prepare_broadcast("Hello everyone")
    .await?
    .send()
    .await;

// Filtered to direct chats only
bot.prepare_broadcast_with("Hello", |id| id.is_direct())
    .await?
    .send()
    .await;

// Image preview is transcoded/resolved once, result broadcast to all groups
bot.prepare_broadcast_with(Image::new("img.jpg"), |id| id.is_group())
    .await?
    .send()
    .await;

// Image with in-memory thumbnail
bot.prepare_broadcast(Image::new("img.jpg"))
    .await?
    .with_preview(ImagePreview::from_bytes(thumb_bytes))
    .send()
    .await;

// Text transitioning to link inside the broadcast builder
bot.prepare_broadcast("Check this out")
    .await?
    .with_link(Link::new("https://example.com").with_title("Example"))
    .with_preview(ImagePreview::from_bytes(og_bytes))
    .with_ttl(Duration::from_secs(86400))
    .send()
    .await;

// Explicit set of chat IDs
bot.multicast_message(chat_ids, Image::new("/tmp/photo.jpg"))
    .with_preview(ImagePreview::from_bytes(thumb_bytes))
    .await;

Structs§

Chat: Chat invitation message containing a link to a group or direct contact.
Custom: Application defined message with a string tag and arbitrary JSON payload.
File: Simple file attachment
Image: Image message type. With the multimedia feature, auto-transcodes the source file into a thumbnail on resolve when no explicit preview is set. Without it, the gray placeholder is used. With native_crypto feature can auto-transcode thumbnails even from the encrypted source files
Link: Link preview message. Use with_title, with_description, and with_image to populate the Open Graph-style card shown to the recipient.
MessageBuilder: An awaitable message builder(await sends the message)
MulticastBuilder
PreviewableKind: Builder kind for messages requiring preview processing. Exposes with_preview to override the thumbnail. With the multimedia feature, also exposes with_transcoder to control JPEG re-encoding at send time.
RawKind: Builder kind for ComposedMessage. Content is sent verbatim so no builder methods are available for this kind.
Report: A message sent to groups to report other users
RichKind: A kind for complex messages(simple attachments, reports, etc) that don’t require any pre-processing to be sent
TextKind: A kind for simple text messsages
Video: Video message type. Automatic preview generation from video files is unsupported; set a preview explicitly or the default placeholder is used. Your app can generate video previews by calling the external ffmpeg process or similar.

Enums§

Text: Represents a styled text(applies SimpleX-Chat markdown syntax to the given substr)

Traits§

MessageLike
MsgContentExt
TextExt: An extension trait supposed to construct Text types from string like types, e.g.

Module messages

Module messages Copy item path

§Simple text

§Simple files

§Images

§Video

§Link

§Special messages like reports and chat links

§Custom and Raw messages

§Broadcasts & Multicasts

Structs§

Enums§

Traits§

Module messages