List conversation history | Sample

7 parameters

tokenstringoptional

Authentication token with the `conversations:history` scope.

channelstringoptional

The conversation ID whose history to retrieve.

latestnumberoptional

The numeric timestamp marking the end of the message time range.

oldestnumberoptional

The numeric timestamp marking the start of the message time range.

inclusivebooleanoptional

Set to `true` to include messages whose timestamps equal `latest` or `oldest`.

limitintegeroptional

The maximum number of history items to return.

cursorstringoptional

Pagination cursor from a previous response's `response_metadata.next_cursor` value; omit it to retrieve the first page.

2 status codes

200Returns an array of message objects, a `has_more` indicator, pin count, and channel action metadata.

channel_actions_countintegerrequired

channel_actions_tsarrayrequired

has_morebooleanrequired

messagesarray<MessageObject>required

okbooleanrequired

Allowed:true

pin_countintegerrequired

defaultReturned when the conversation cannot be found, a timestamp is invalid, or authentication, permissions, or request formatting is invalid.

callstackstringoptional

Note: PHP callstack is only visible in dev/qa

errorstringrequired

Allowed:missing_scopechannel_not_foundinvalid_ts_latestinvalid_ts_oldestnot_authedinvalid_authaccount_inactiveinvalid_arg_nameinvalid_array_arginvalid_charsetinvalid_form_datainvalid_post_type

neededstringoptional

okbooleanrequired

Allowed:false

providedstringoptional

Error handling

latest and oldest must be valid numeric timestamps when supplied, and inclusive applies only when either boundary timestamp is provided. Use the cursor returned in response_metadata.next_cursor from a previous request to continue pagination.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  retry: {
    maxAttempts: 3,
    retryOn: [
      408,
      425,
      429,
      500,
      502,
      503,
      504,
    ],
    backoffMs: 500,
    maxBackoffMs: 8000,
  },
  timeoutMs: 30000,
});

const result = await client.conversationsHistory.list({
  token: "sk_live_4eC39Hq",
  channel: "example",
  latest: "example",
  oldest: "example",
  inclusive: "example",
});

{
  "has_more": true,
  "messages": [
    {
      "text": "I find you punny and would like to smell your nose letter",
      "ts": "1512085950.000216",
      "type": "message",
      "user": "U012AB3CDE"
    },
    {
      "text": "What, you want to smell my shoes better?",
      "ts": "1512104434.000490",
      "type": "message",
      "user": "U061F7AUR"
    }
  ],
  "ok": true,
  "pin_count": 0,
  "response_metadata": {
    "next_cursor": "bmV4dF90czoxNTEyMDg1ODYxMDAwNTQz"
  }
}

Request

Response

Errors