Skip to main content
Osmium supports rich URL embeds with preview metadata for links shared in messages.

​
MediaEmbed

The MediaEmbed type represents a URL embed with optional preview data: 
message MediaEmbed {
  string url = 1;
  optional string title = 2;
  optional string description = 3;
  // TODO: spoiler, etc
}
​
url
string
required
The URL being embedded
​
title
string
Page title or embed title
​
description
string
Page description or summary

​
MediaRefEmbed

To reference an embed when creating media, use MediaRefEmbed: 
message MediaRefEmbed {
  string url = 1;
}
​
url
string
required
The URL to embed

​
Using Embeds in Messages

Embeds can be attached to messages through the MessageMedia type: 
message MessageMedia {
  oneof media {
    MediaFile file = 1;
    MediaEmbed embed = 2;
  }
}

​
Example: Simple Embed

const message = await client.call('messages.sendMessage', {
  chat_id: chatId,
  content: {
    text: 'Check out this article!',
    media: [
      {
        embed: {
          url: 'https://example.com/article'
        }
      }
    ]
  }
});

​
Get Embed Preview

While not currently in the proto file, the protocol will support fetching embed previews. The embed preview would populate the title and description fields:

​
Expected Usage

// This method is referenced in comments but not yet implemented
const preview = await client.call('media.getEmbedPreview', {
  url: 'https://example.com/article'
});

// preview would contain:
// {
//   url: 'https://example.com/article',
//   title: 'Article Title',
//   description: 'Article summary...',
//   thumbnail: fileRef  // optional
// }

​
Embed Metadata Sources

Embed previews are typically generated from:

​
Open Graph Tags

<meta property="og:title" content="Page Title" />
<meta property="og:description" content="Page description" />
<meta property="og:image" content="https://example.com/image.jpg" />

​
Twitter Cards

<meta name="twitter:title" content="Page Title" />
<meta name="twitter:description" content="Page description" />
<meta name="twitter:image" content="https://example.com/image.jpg" />

​
Standard HTML

<title>Page Title</title>
<meta name="description" content="Page description" />

​
MediaRef with Embed

The MediaRef type supports both uploaded files and embeds: 
message MediaRef {
  oneof ref {
    MediaRefUploadedFile uploaded = 1;
    MediaRefEmbed embed = 2;
  }
}
This allows you to attach either files or URL embeds to messages: 
// File attachment
const fileMedia = {
  uploaded: {
    file: uploadedFileRef,
    filename: 'image.jpg',
    mimetype: 'image/jpeg',
    metadata: { image: { width: 800, height: 600 } }
  }
};

// URL embed
const embedMedia = {
  embed: {
    url: 'https://example.com/page'
  }
};

​
Future Features

The proto comments indicate planned features:
  • Spoiler support: Mark embeds as spoilers requiring click to reveal
  • Thumbnail images: Embed preview images
  • Rich metadata: Additional fields for video embeds, article metadata, etc.
  • Embed customization: Control how embeds are displayed

​
Use Cases

Share URLs with automatic preview generation: 
// User pastes link, client detects and creates embed
const url = detectUrlInMessage(text);
if (url) {
  const preview = await getEmbedPreview(url);
  attachEmbed(preview);
}

​
Rich Articles

Display article previews with title and description: 
const embed = {
  url: 'https://blog.example.com/post',
  title: 'How to Build Chat Apps',
  description: 'A comprehensive guide to building modern chat applications...'
};
Embed video URLs with metadata: 
const embed = {
  url: 'https://youtube.com/watch?v=...',
  title: 'Video Title',
  description: 'Video description'
};

Build docs developers (and LLMs) love

Get started for freeTalk to us