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:

Query Param

Type

Description

limit (optional)

int

Max number of conversations to retrieve (max 50, default 25).

next (optional)

int

Cursor param used for pagination (explained below)

statusId (optional, repeatable)

int

Return only conversations that match the provided status code. Uses the following values:

1: OPEN
2: CLOSED
3: PENDING

📘

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.

🚧

Using older endpoints

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


Did this page help you?