Message Model

Schema

{
  "id": long (int),
  "orgId": int,
  "body": string,
  "author": {
    "type": string (one of {contact, user}),
    "id": long,
    "bot": boolean
  },
  "type": string (one of {chat, private_note, private_prompt, suggestion, edit}),
  "conversationId": int,
  "createdAt": timestamp,
  "buttons": [MessageButton],
  "context": {
    "ip": string,
    "userAgent": string
  },
  "editedMessageId": long,
  "editType": {delete, replace, replace_body, replace_buttons},
  "attributes": object // additional information (see below)
}

Field Name

Description

id

A unique identifier for the Message. Should be treated as long or integer 64 bit data type.

orgId

The Drift organization this Message belongs to

body

The text contents of this message, if applicable. See the Message Body section for details on the format.

author

An object describing who authored this Message. author.type is contact if the author was a Contact and user if they were a User. author.id uniquely identifies the author within the object type specified by author.type. Bot indicates whether the posting user is a bot (won't be true for contacts).

type

Specifies the type of this Message; one of chat, private_note, private_prompt, or edit. See the section Types of Messages below for details.

conversationId

The id field of the Conversation this Message is a part of

createdAt

A Unix timestamp representing the moment this Message was created

buttons

A (potentially absent) list of objects representing buttons presented to Users or Contacts from this message. See the section on Message Buttons for details.

context

An optional object representing potential metadata about where the Message was published from.

editedMessageId, editType

Required fields for edit type Messages, see the section on Editing Messages for details.

attributes

Other metadata on the message.

Possible fields:
preMessages (object): If there were messages in the conversation prior to this current message, i.e. supplied by a bot user or on behalf of a drift user, these will be supplied here. This is generally present on the first site visitor message.
developer_app_id (string): The dev app id will be included if the message was posted via the API.

Types of Messages

There are 4 types of Messages, corresponding to the type field in that object:

  • chat Messages are the most ubiquitous type. They correspond to a regular text-based communication from either a Contact or a User and are visible to both. chat type messages may also contain buttons, in which case they're only visible to the Conversation's Contact.
  • private_notes are Messages that can only be created by a User and seen by other Users. These are useful for sharing sensitive, but useful information to Users in the context of the communication they're having with a given Contact
  • private_prompts are similarly only visible to Users, but can only be created by Apps. They're intended to allow developers to present Users with an interactive context (via buttons) to perform an an action in the context of the Conversation.
  • edits allow an App developer to change Messages that have already been created. This is intended to be used interactivity in private_prompts and edits are restricted to pertain to those types of Messages for now. See the section on Editing Messages for details.

Message Bodies

The message.body field is the primary vehicle for communicating information in Messages. It follows a format that resembles HTML in order to allow for limited richness, but is heavily and automatically restricted. In particular, HTML reserved characters are automatically converted to their corresponding HTML entities if they're outside the context of an allowed tag. <b>, <em>, and <a> tags are allowed, but most others are automatically stripped, as well as any styles on the allowed ones. Ultimately, you can treat this field as plain text and not include any tags.

Message Buttons

Messages chat and private_prompt can be made interactive with buttons. Developers can present either the Contact (in the case of chats) or Users (with private_prompts) with buttons that either:

  • Automatically send a particular chat message as a reaction
  • Add a prepared message to the composer section of the Conversation view.
  • Invoke an action in an App.

Buttons can be set as a list in the message.button field and have the following format:

{
  "label": string,
  "value": string,
  "type": {reply, compose, action},
  "style": {primary, danger},
  "reaction": {
    "type": {replace, delete},
    "message": string
  }
}

They'll appear in your app like this:

Field Name

Description

label

For all button types, the label field is what is actually displayed as a label on the button to the User or Contact.

value

For reply type buttons, value must equal label. In compose types, value is what is entered into the User's composer. In action types, value should be a slug that identifies the sort of action intended by the button click; this is interpreted by an App to properly react to a button click.

style

Optional: This is only applicable to buttons within private_prompt Messages. When the value is primary the button is rendered as green with white text, if danger to be similar to the 'destructive' button above with white text. If style isn't specified, a style fitting with the overall design of the Drift UI is used.

type

Optional: defaulted to reply
reply type buttons cause the text in the button to be immediately used as a new chat Message by the Contact when pressed. replys are only ever rendered to Contacts (Users will only see the body of the Message) and are the only type allowed in chat Messages.

compose buttons cause text be added to a User's Conversation composer. A User can then edit the message before they get sent. They are only allowed in private_prompt Messages.

action type buttons signal a button click to Apps via their webhook. They are only allowed in private_prompt Messages.

reaction

A reaction can be specified to automatically cause a visual change when a button is pressed. If reaction.type is delete, the Message containing the button is (visually) deleted when the button is hit. If reaction.type is replace, the Message is replaced with one containing only a message.body set to the value of reaction.message. If the type is replace, reaction.message must be specified.

Note that the effects of a reaction are implemented with edit Messages and can always been recreated by the App using them; reactions are simply a shortcut to easily enable these common use cases.

Editing Messages

Messages of type edit allow changes to a Message that was previously created. The editedMessageId field specifies the id of the Message being edited; for now the type of the edited Message must be private_prompt. editType specifies the type of edit to be performed:

  • delete means that Message should simply be (visually) omitted.
  • replace has the body and buttons of the referenced Message replaced with those of the new edit message
  • replace_body and replace_buttons behave similarly to replace, but only replace the field specified in their names, leaving the other fields in the original Message as they were.

If a Message has multiple edit type Messages that reference it, only the last of those Messages is rendered. In particular, edits don't chain; a replace_body followed by a replace_buttons does not equal the same changes specified in one replace.

Updated about a year ago

Message Model


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.