Message Format

LAST EDIT Apr 26 2021

When you post a message on a Channel, there are a few things that happen on the server:

  1. The text markdown format is parsed.
  2. The first URL found in message.text is enriched, and additional information is added automatically. This gives you a preview of the images, videos, etc. from the open-graph data on the associated page.
Any slash commands such as /giphy/imgur/ban, /flag, etc. are handled.

Attachment Format

Copied!

Messages containing URLs will have a generated attachment with the following structure:

nametypedescriptiondefaultoptional
typestringThe attachment type based on the URL resource. This can be: audio, image or video
author_namestringThe name of the author.
titlestringThe attachment title.
title_linkstringThe link to which the attachment message points to.
textstringThe attachment text. It will be displayed in the channel next to the original message.
image_urlstringThe URL to the attached image. This is present for URL pointing to an image article (eg. Unsplash)
thumb_urlstringThe URL to the attached file thumbnail. You can use this to represent the attached link.
asset_urlstringThe URL to the audio, video or image related to the URL.
og_scrape_urlstringThe original URL that was used to scrape this attachment.

Open Graph Scraper

Copied!

Our scraper uses the following user agent, as well as the latest desktop and mobile user agents: getstream.io/opengraph-bot facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php) If you plan to scrape any links to websites you can control, please ensure that this user agent isn't blocked and returns valid opengraph data, for the best results.

Below is an example of URL enrichment as well as the resulting message structure:

Messages returned by the API follow this structure:

nametypedescriptiondefaultoptional
idstringThe message ID. This is either created by Stream or set client side when the message is added.
htmlstringThe safe HTML generated from the raw text message. This field can only be set using server-side APIs or via the import
typestringThe message type. See below for more information.
userobjectThe author user object. Schema is as described in the Setting the user portion of the docs.
attachmentsarrayThe list of attachments, either provided by the user or generated from a command or as a result of URL scraping.
latest_reactionsarrayThe latest reactions to the message created by any user.
own_reactionsarrayThe array of reactions added to the message by the current user. e.g. [ReactionObject1, ReactionObject2].
reaction_countsobjectThe reaction count by type for this message e.g. {"haha": 3, "angry": 2}.
reply_countintegerReserved field indicating the number of replies for this message.
parent_idstringThe ID of the parent message, if the message is a reply.
created_atdateReserved field indicating when the message was created.
updated_atdateReserved field indicating when the message was updated last time.
deleted_atdateReserved field indicating when the message was deleted.
mentioned_usersarray of usersThe list of users that are mentioned in this message.
statusstringMessage status: e.g. 'received', 'sending', 'failed'-

Message Types

Copied!

Chat supports different types of messages. The type of the message is set by the APIs or by chat bots and custom commands.

Name

Description

regular

A regular message created in the channel.

ephemeral

A temporary message which is only delivered to one user. It is not stored in the channel history. Ephemeral messages are normally used by commands (e.g. /giphy) to prompt messages or request for actions.

error

An error message generated as a result of a failed command. It is also ephemeral, as it is not stored in the channel history and is only delivered to one user.

reply

A message in a reply thread. Messages created with parent_id are automatically of this type.

system

A message generated by a system event, like updating the channel or muting a user.

deleted

A soft deleted message