Message Format

Last Edit: Oct 29 2020

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.

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

Name Type Description Default Optional
type string The attachment type based on the URL resource. This can be: audio, image or video
author_name string The name of the author.
title string The attachment title.
title_link string The link to which the attachment message points to.
text string The attachment text. It will be displayed in the channel next to the original message.
image_url string The URL to the attached image. This is present for URL pointing to an image article (eg. Unsplash)
thumb_url string The URL to the attached file thumbnail. You can use this to represent the attached link.
asset_url string The URL to the audio, video or image related to the URL.
og_scrape_url string The original URL that was used to scrape this attachment.

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


const response = await channel.sendMessage({
    text: 'Check this bear out https://imgur.com/r/bears/4zmGbMN'
})

// response message object
{
    "id": "thierry-5e9619ec-1a0d-443b-ab26-c597ed7af3d0",
    "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
    "html": "<p>Check this bear out <a href="\&quot;https://imgur.com/r/bears/4zmGbMN\&quot;" rel="\&quot;nofollow\&quot;">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
    "type": "regular",
    "user": {
      "id": "thierry",
      "role": "user",
      "created_at": "2019-04-03T14:42:47.087869Z",
      "updated_at": "2019-04-16T09:20:03.982283Z",
      "last_active": "2019-04-16T11:23:51.168113408+02:00",
      "online": true
    },
    "attachments": [
      {
        "type": "image",
        "author_name": "Imgur",
        "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
        "title_link": "https://imgur.com/4zmGbMN",
        "text": "1678 views on Imgur",
        "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
        "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
        "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
      }
    ],
    "latest_reactions": [],
    "own_reactions": [],
    "reaction_counts": null,
    "reply_count": 0,
    "created_at": "2019-04-16T09:40:04.665274Z",
    "updated_at": "2019-04-16T09:40:04.665274Z"
  }
                    

Message message = new Message();
message.setText("Check this bear out https://imgur.com/r/bears/4zmGbMN");

channelController.sendMessage(message).enqueue(result -> Unit.INSTANCE);

// response message object
//    {
//        "id": "thierry-5e9619ec-1a0d-443b-ab26-c597ed7af3d0",
//            "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
//            "html": "<p>Check this bear out <a href="\&quot;https://imgur.com/r/bears/4zmGbMN\&quot;" rel="\&quot;nofollow\&quot;">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
//            "type": "regular",
//            "user": {
//        "id": "thierry",
//                "role": "user",
//                "created_at": "2019-04-03T14:42:47.087869Z",
//                "updated_at": "2019-04-16T09:20:03.982283Z",
//                "last_active": "2019-04-16T11:23:51.168113408+02:00",
//                "online": true
//    },
//        "attachments": [
//        {
//            "type": "image",
//                "author_name": "Imgur",
//                "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
//                "title_link": "https://imgur.com/4zmGbMN",
//                "text": "1678 views on Imgur",
//                "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
//        }
//    ],
//        "latest_reactions": [],
//        "own_reactions": [],
//        "reaction_counts": null,
//            "reply_count": 0,
//            "created_at": "2019-04-16T09:40:04.665274Z",
//            "updated_at": "2019-04-16T09:40:04.665274Z"
//    }
                    

let channel = Client.shared.channel(type: .messaging, id: "general")
let message = Message(text: "Check this bear out https://imgur.com/r/bears/4zmGbMN")
// Send the message
channel.send(message: message) { (result) in
    do {
        let response = try result.get()
        print(response)
    } catch {
        print("Error when sending message: \(error)")
    }
}

// response message object
//    {
//        "id": "thierry-5e9619ec-1a0d-443b-ab26-c597ed7af3d0",
//            "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
//            "html": "<p>Check this bear out <a href="\&quot;https://imgur.com/r/bears/4zmGbMN\&quot;" rel="\&quot;nofollow\&quot;">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
//            "type": "regular",
//            "user": {
//        "id": "thierry",
//                "role": "user",
//                "created_at": "2019-04-03T14:42:47.087869Z",
//                "updated_at": "2019-04-16T09:20:03.982283Z",
//                "last_active": "2019-04-16T11:23:51.168113408+02:00",
//                "online": true
//    },
//        "attachments": [
//        {
//            "type": "image",
//                "author_name": "Imgur",
//                "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
//                "title_link": "https://imgur.com/4zmGbMN",
//                "text": "1678 views on Imgur",
//                "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
//        }
//    ],
//        "latest_reactions": [],
//        "own_reactions": [],
//        "reaction_counts": null,
//            "reply_count": 0,
//            "created_at": "2019-04-16T09:40:04.665274Z",
//            "updated_at": "2019-04-16T09:40:04.665274Z"
//
                    

val message = Message()
message.text = "Check this bear out https://imgur.com/r/bears/4zmGbMN"

// send the message to the channel
channelController.sendMessage(message).enqueue { 
    val sentMessage = it.data()
}

// response message object
//    {
//        "id": "thierry-5e9619ec-1a0d-443b-ab26-c597ed7af3d0",
//            "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
//            "html": "<p>Check this bear out <a href="\&quot;https://imgur.com/r/bears/4zmGbMN\&quot;" rel="\&quot;nofollow\&quot;">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
//            "type": "regular",
//            "user": {
//        "id": "thierry",
//                "role": "user",
//                "created_at": "2019-04-03T14:42:47.087869Z",
//                "updated_at": "2019-04-16T09:20:03.982283Z",
//                "last_active": "2019-04-16T11:23:51.168113408+02:00",
//                "online": true
//    },
//        "attachments": [
//        {
//            "type": "image",
//                "author_name": "Imgur",
//                "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
//                "title_link": "https://imgur.com/4zmGbMN",
//                "text": "1678 views on Imgur",
//                "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
//                "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
//        }
//    ],
//        "latest_reactions": [],
//        "own_reactions": [],
//        "reaction_counts": null,
//            "reply_count": 0,
//            "created_at": "2019-04-16T09:40:04.665274Z",
//            "updated_at": "2019-04-16T09:40:04.665274Z"
//
                    

$response = $channel->sendMessage(["text" => "Check this bear out https://imgur.com/r/bears/4zmGbMN"], 'jenny');

// response message object
{
  "message": {
    "id": "7ae3b66e-80a4-445d-85bf-3445d6f5e0cc",
    "text": "Check this bear out https://imgur.com/r/bears/4zmGbMN",
    "html": "<p>Check this bear out <a href=\"https://imgur.com/r/bears/4zmGbMN\" rel=\"nofollow\">https://imgur.com/r/bears/4zmGbMN</a></p>\n",
    "type": "regular",
    "user": {
      "id": "jenny",
      "role": "user",
      "created_at": "2020-02-14T11:04:24.181212Z",
      "updated_at": "2020-02-14T11:04:24.182192Z",
      "banned": false,
      "online": false
    },
    "attachments": [
      {
        "type": "image",
        "author_name": "Imgur",
        "title": "An update: Dushi made it safe to Bear Sanctuary Müritz",
        "title_link": "https://imgur.com/4zmGbMN",
        "text": "2712 views on Imgur",
        "image_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
        "thumb_url": "https://i.imgur.com/4zmGbMN.jpg?fb",
        "og_scrape_url": "https://imgur.com/r/bears/4zmGbMN"
      }
    ],
    "latest_reactions": [],
    "own_reactions": [],
    "reaction_counts": null,
    "reaction_scores": [],
    "reply_count": 0,
    "created_at": "2020-02-14T11:21:17.277779Z",
    "updated_at": "2020-02-14T11:21:17.277779Z",
    "mentioned_users": []
  },
  "duration": "33.02ms"
}
                    

Messages returned by the API follow this structure:

Name Type Description Default Optional
id string The message ID. This is either created by Stream or set client side when the message is added.
html string The safe HTML generated from the raw text message. This field can only be set using server-side APIs or via the import
type string The message type. See below for more information.
user object The author user object. Schema is as described in the Setting the user portion of the docs.
attachments array The list of attachments, either provided by the user or generated from a command or as a result of URL scraping.
latest_reactions array The latest reactions to the message created by any user.
own_reactions array The reactions added to the message by the current user. e.g. ["haha", "angry"].
reaction_counts object The reaction count by type for this message e.g. {"haha": 3, "angry": 2}.
reply_count integer Reserved field indicating the number of replies for this message.
parent_id string The ID of the parent message, if the message is a reply.
created_at date Reserved field indicating when the message was created.
updated_at date Reserved field indicating when the message was updated last time.
deleted_at date Reserved field indicating when the message was deleted.
mentioned_users array of users The list of users that are mentioned in this message.
status string Message status: e.g. 'received', 'sending', 'failed' -

Message Types

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.