Conversation Model

What are Conversations?

Conversations are the core objects in Drift. They represent a series of messages exchanged between a single contact and a group of users. Users are the employees of the organization or a bot. Each conversation has a time-ordered set of messages representing chat messages, internal notes, and metadata events within that communication

Messages make up the meat of a conversation. They will contain information regarding the text sent and metadata on the sender.

While this endpoint may seem like a one-stop shop for information on conversations, in reality the model itself is far better for getting human-legible details about the conversations rather than metrics.

All conversation and message interactions are based at https://driftapi.com/conversations and have the following response conventions:

Schema

{
  "id": long,
  "participants": [long],
  "status": string, // one of {open, closed, pending, bulk_sent}
  "contactId": long,
  "inboxId": int,
  "createdAt": timestamp,
  "updatedAt": timestamp,
  "relatedPlaybookId": int (optional),
  "conversationTags": [
    {
      color: string (hex value),
      name: string
    },
    ...
  ]
}

Field Explanation

Field Name	Description
id	Conversations are uniquely identified by an `id`, which can be used to check its current state and its messages.
participants	Each conversation has a set of participants; Drift Users who are taking part in, or responsible for communication with the Contact. This field is a set of ids that uniquely identify each User.
status	Conversations in Drift are organized by their status: `open` Conversations are active and should be responded to, `pending` ones are waiting on follow up, `closed` are handled and not actively being communicated with. and `bulk_sent` are playbook messages that have reached an end user but not been interacted with. Conversations may move in between any of these statuses as users change them or new events cause them (e.g. if a contact sends a new message in a `closed` conversation, its status will be changed to `open`).
contactId	The `id` of the contact that's being communicated with in this conversation as a long value (int64).
createdAt	A Unix timestamp representing the moment that the conversation was created.
updatedAt	A Unix timestamp representing the moment that the conversation was updated. For example, updated due to a status change or new message post.
orgId	The Drift organization this conversation belongs to.
inboxId	The inbox this conversation belongs to, can reconstruct drift conversation links via: https://app.drift.com/inboxes/{inboxId}/conversations/{conversationId}
conversationTags	Any tags applied to the conversation, include their color appearance in the conversation view within drift.
relatedPlaybookId	This is the ID of the playbook that initiated the conversation. Conversations started from the default welcome message will not include a relatedPlaybookId in the conversation payload. This will be included in the response of the `GET conversation` endpoint if present.