listUsers

Retrieves a list of User previously created. The users are returned in sorted order, with the most recent appearing first. The list can be filtered using Tags.

GET/v1/chat/users

Authorization

AuthorizationBearerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Header parameters

x-bot-idstringrequired

Bot id

x-integration-idstring

Integration id

x-integration-aliasstring

Integration alias

Query parameters

nextTokenstring

Provide the `meta.nextToken` value provided in the last API response to retrieve the next page of results

conversationIdstring

Filter by conversation id. This will return all users that have participated in the conversation.

tagsobject

Filter by tags

afterDatestring

Date in ISO 8601 string with UTC timezone after which the user was created or updated (inclusive)

beforeDatestring

Date in ISO 8601 string with UTC timezone before which the user was created or updated (inclusive)

rangeFieldenum<string>

Field used for range filtering. Allowed values are "updatedAt" or "createdAt". Defaults to "createdAt" if omitted.

Available options:"updatedAt","createdAt"

sortFieldenum<string>

Sort results by this field

Available options:"updatedAt","createdAt"

sortDirectionenum<string>

Sort results in this direction

Available options:"asc","desc"

Response

Returns a list of User objects

usersobject[]required

metaobjectrequired

Request

curl --request GET \ \
  --url https://api.botpress.cloud/v1/chat/users \
  --header 'x-bot-id: <x-bot-id>' \
  --header 'Authorization: Bearer <token>'

Response

{
  "users": [
    {
      "id": "string",
      "createdAt": "2025-01-15T12:00:00Z",
      "updatedAt": "2025-01-15T12:00:00Z",
      "tags": {
        "key": "string"
      },
      "name": "string",
      "pictureUrl": "string",
      "properties": {
        "key": "string"
      },
      "attributes": {
        "key": "string"
      }
    }
  ],
  "meta": {
    "nextToken": "string"
  }
}