Listing Conversations

You can query the conversations in your account using the following paginated API endpoint.

Retrieves first page of conversations (all types):
GET https://driftapi.com/conversations/list

Supporting Query Parameters:

📘

Sorting order

Conversations returned will be ordered by their updatedAt time with the most recently updated at the top of the list. Common conversation updates include status updates (i.e. closing the conversation) or a post of a new message to that conversation.

Example requests:

Retrieves open conversations (first page, up to 50):
GET https://driftapi.com/conversations/list?statusId=1&limit=50

Retrieves open and closed conversations (after the cursor value 50):
GET https://driftapi.com/conversations/list?statusId=1&statusId=2&next=50

Example Response:

{
  "data": [
    {
            "status": "closed",
            "contactId": 1238157803,
            "createdAt": 1237922759384,
            "id": 1230200520,
            "inboxId": 123064,
            "updatedAt": 1237922783451
        },
        {
            "status": "closed",
            "contactId": 1238007734,
            "createdAt": 1237921765994,
            "id": 1230183727,
            "inboxId": 123064,
            "updatedAt": 1237921843271
        },
        {
            "status": "closed",
            "contactId": 1231375574,
            "createdAt": 1237887731334,
            "id": 1239406310,
            "inboxId": 123064,
            "updatedAt": 1237887796881
        }
  ],
  "pagination": { // field present if there are more conversations after this
      "more": true,
      "next": "123494893" // next cursor id value
  },
  "errors": [{
    "type": {validation_error, not_found, ...},
    "message": string,
    "param": string (optional)
  },
  ...
    ]
}

Thus, to retrieve the next set of conversations given this particular response, you would use the following query:

GET https://driftapi.com/conversations/list?next=100

The top level fields won't all be present at once. If errors is present, pagination and data won't be, moreover errors will always have at least one item if it is present. If data is present, errors won't be. pagination is present if data relates to something pageable.

Example Request

GET https://driftapi.com/conversations/list?limit=2&next=5

{
  "data": [
    {
            "status": "closed",
            "contactId": 1238157803,
            "createdAt": 1237922759384,
            "id": 1230200520,
            "inboxId": 123064,
            "updatedAt": 1237922783451
        },
        {
            "status": "closed",
            "contactId": 1238007734,
            "createdAt": 1237921765994,
            "id": 1230183727,
            "inboxId": 123064,
            "updatedAt": 1237921843271
        },
        {
            "status": "closed",
            "contactId": 1231375574,
            "createdAt": 1237887731334,
            "id": 1239406310,
            "inboxId": 123064,
            "updatedAt": 1237887796881
        }
  ],
  "pagination": { // field present if there are more conversations after this
      "more": true,
      "next": "7" // next cursor id value
  }
}

📘

What happens when I've reached the end of Pagination?

The "pagination" field will not appear in the response body once the search results are exhausted; the data field will contain the last remaining conversations at this point.

🚧

Known limitation

Organizations with large conversation volume (e.g. >1000 daily conversations) may not be able to read all conversations due to the current API implementation timing out. The team is aware of the issue and actively pursuing a solution. If you need to get all historic conversations please contact Drift Support.

❗️

Using older endpoints

GET /conversations also allows scrolling across conversations, but has been deprecated as of v1.3 of the docs.