glyde/embed

Message embeds. One type for both directions: the receive-only fields (type, provider, video, proxy urls, media sizes) are None on a value you build and to_json never writes them, so a received embed round-trips through a draft without a conversion.

embed.new()
|> embed.title("glyde")
|> embed.description("A sans-IO Discord library for Gleam.")
|> embed.color(0x5865F2)
|> embed.field("Runs on", "Erlang", inline: True)

Setters replace, field appends. Nothing checks a length. Discord allows a 256 title, a 4096 description, 25 fields and 6000 characters overall.

Types

Embed

</>

pub type Embed {
  Embed(
    title: option.Option(String),
    type_: option.Option(EmbedType),
    description: option.Option(String),
    url: option.Option(String),
    timestamp: option.Option(String),
    color: option.Option(Int),
    footer: option.Option(EmbedFooter),
    image: option.Option(EmbedMedia),
    thumbnail: option.Option(EmbedMedia),
    video: option.Option(EmbedMedia),
    provider: option.Option(EmbedProvider),
    author: option.Option(EmbedAuthor),
    fields: List(EmbedField),
    flags: flags.Flags(EmbedFlag),
  )
}

Constructors

Embed(
  title: option.Option(String),
  type_: option.Option(EmbedType),
  description: option.Option(String),
  url: option.Option(String),
  timestamp: option.Option(String),
  color: option.Option(Int),
  footer: option.Option(EmbedFooter),
  image: option.Option(EmbedMedia),
  thumbnail: option.Option(EmbedMedia),
  video: option.Option(EmbedMedia),
  provider: option.Option(EmbedProvider),
  author: option.Option(EmbedAuthor),
  fields: List(EmbedField),
  flags: flags.Flags(EmbedFlag),
)

Arguments

title: Max 256 characters.
type_: Receive only. An open set: Discord ships values it has not documented.
description: Max 4096 characters.
url: Embeds sharing a url are merged into one by the client.
timestamp: ISO-8601. glyde does not own a clock, so this is a string you supply.
color: 24-bit RGB, so 0x5865F2 is blurple.
image: On send only url is read. Point it at attachment://<filename> to use a file uploaded in the same request.
video: Receive only.
provider: Receive only.
fields: Max 25.
flags: Receive only.

EmbedAuthor

</>

pub type EmbedAuthor {
  EmbedAuthor(
    name: String,
    url: option.Option(String),
    icon_url: option.Option(String),
    proxy_icon_url: option.Option(String),
  )
}

Constructors

EmbedAuthor(
  name: String,
  url: option.Option(String),
  icon_url: option.Option(String),
  proxy_icon_url: option.Option(String),
)

Arguments

name: Max 256 characters.
proxy_icon_url: Receive only.

EmbedField

</>

pub type EmbedField {
  EmbedField(name: String, value: String, inline: Bool)
}

Constructors

```
EmbedField(name: String, value: String, inline: Bool)
```
name max 256, value max 1024, and 6000 characters across the embed.

EmbedFlag

</>

pub type EmbedFlag {
  IsContentInventoryEntry
}

Constructors

```
IsContentInventoryEntry
```
The embed is a content inventory entry, which a bot never sends.

EmbedFlags

</>

pub type EmbedFlags =
  flags.Flags(EmbedFlag)

EmbedFooter

</>

pub type EmbedFooter {
  EmbedFooter(
    text: String,
    icon_url: option.Option(String),
    proxy_icon_url: option.Option(String),
  )
}

Constructors

EmbedFooter(
  text: String,
  icon_url: option.Option(String),
  proxy_icon_url: option.Option(String),
)

Arguments

text: Max 2048 characters.
proxy_icon_url: Receive only.

EmbedMedia

</>

One record for image, thumbnail and video. On send only url goes out; Discord rejects height, width and proxy_url on an embed you post.

pub type EmbedMedia {
  EmbedMedia(
    url: option.Option(String),
    proxy_url: option.Option(String),
    dimensions: option.Option(attachment.Dimensions),
    content_type: option.Option(String),
    placeholder: option.Option(attachment.Placeholder),
    description: option.Option(String),
    flags: flags.Flags(EmbedMediaFlag),
  )
}

Constructors

EmbedMedia(
  url: option.Option(String),
  proxy_url: option.Option(String),
  dimensions: option.Option(attachment.Dimensions),
  content_type: option.Option(String),
  placeholder: option.Option(attachment.Placeholder),
  description: option.Option(String),
  flags: flags.Flags(EmbedMediaFlag),
)

Arguments

dimensions: Discord sends both sides or neither, so one value carries both.
placeholder: A thumbhash: a blurred preview to paint while the image loads. The version only says how the hash is encoded, so one value carries both.
description: Alt text.

EmbedMediaFlag

</>

pub type EmbedMediaFlag {
  IsAnimated
}

Constructors

```
IsAnimated
```

EmbedMediaFlags

</>

Its own type, not the attachment one: Discord documents a separate table for embed media, and today it names a single bit.

pub type EmbedMediaFlags =
  flags.Flags(EmbedMediaFlag)

EmbedProvider

</>

pub type EmbedProvider {
  EmbedProvider(
    name: option.Option(String),
    url: option.Option(String),
  )
}

Constructors

EmbedProvider(
  name: option.Option(String),
  url: option.Option(String),
)

EmbedType

</>

Discord’s documented embed types. Only Rich is ever sent by a bot; the rest are what the client made of a link. An open set on the wire, so a value this build has no name for decodes as None.

pub type EmbedType {
  Rich
  Image
  Video
  Gifv
  Article
  Link
  PollResult
  AutoModerationMessage
}

Constructors

```
Rich
```
```
Image
```
```
Video
```
```
Gifv
```
```
Article
```
```
Link
```
```
PollResult
```
```
AutoModerationMessage
```

Values

author

</>

pub fn author(embed: Embed, name: String) -> Embed

author_decoder

</>

pub fn author_decoder() -> decode.Decoder(EmbedAuthor)

character_count

</>

pub fn character_count(embeds: List(Embed)) -> Int

What Discord counts against total_character_limit: title, description, footer text, author name, and every field name and value, over all the embeds a message carries. One embed on its own is character_count([it]).

color

</>

pub fn color(embed: Embed, rgb: Int) -> Embed

The colour of the bar down the left, as 24-bit RGB.

decoder

</>

pub fn decoder() -> decode.Decoder(Embed)

description

</>

pub fn description(embed: Embed, description: String) -> Embed

embed_type_decoder

</>

pub fn embed_type_decoder() -> decode.Decoder(
  option.Option(EmbedType),
)

embed_type_from_string

</>

pub fn embed_type_from_string(
  value: String,
) -> option.Option(EmbedType)

embed_type_to_string

</>

pub fn embed_type_to_string(value: EmbedType) -> String

field

</>

pub fn field(
  embed: Embed,
  name: String,
  value: String,
  inline inline: Bool,
) -> Embed

Append a field. Discord shows up to three inline fields side by side and stacks the rest.

field_decoder

</>

pub fn field_decoder() -> decode.Decoder(EmbedField)

</>

pub fn footer(embed: Embed, text: String) -> Embed

footer_decoder

</>

pub fn footer_decoder() -> decode.Decoder(EmbedFooter)

has_flag

</>

pub fn has_flag(
  bits: flags.Flags(EmbedFlag),
  flag: EmbedFlag,
) -> Bool

has_media_flag

</>

pub fn has_media_flag(
  bits: flags.Flags(EmbedMediaFlag),
  flag: EmbedMediaFlag,
) -> Bool

image

</>

pub fn image(embed: Embed, url: String) -> Embed

media_decoder

</>

pub fn media_decoder() -> decode.Decoder(EmbedMedia)

new

</>

pub fn new() -> Embed

An empty embed, to pipe setters onto.

provider_decoder

</>

pub fn provider_decoder() -> decode.Decoder(EmbedProvider)

thumbnail

</>

pub fn thumbnail(embed: Embed, url: String) -> Embed

timestamp

</>

pub fn timestamp(embed: Embed, iso8601: String) -> Embed

ISO-8601, for the timestamp Discord renders in the footer.

title

</>

pub fn title(embed: Embed, title: String) -> Embed

to_json

</>

pub fn to_json(embed: Embed) -> json.Json

The send shape. Type, provider, video, proxy urls and media sizes are not written: Discord ignores them on a create anyway.

total_character_limit

</>

pub const total_character_limit: Int

Discord’s cap across every embed on one message, not per embed. In UTF-16 code units, so an emoji spends two of them.

url

</>

pub fn url(embed: Embed, url: String) -> Embed

Makes the title a link. Without a title it shows nothing.