You're browsing the legacy version of the API documentation. Switch to the latest stable version →

Users

Chatbots improve the way we communicate with customers but also take out the personal touch from conversations. The Users tool allows you to get closer to the people that chat with your bot and build relationships.

Create user

Creates new user.

POST https://api.chatbot.com/users

Properties

parameter	type	required	default
`userId`	String(1, 256)	required	uuid
`segments`	String(24), String[]	optional
`attributes`	Object(1, 99)	required
`attributes.<pattern>`	String(1,1024	optional
`attributes.default_email`	String(1, 1024)	optional	null
`attributes.default_name`	String(1, 256)	optional	null
`attributes.default_url`	String(1, 1024)	optional	null
`attributes.default_avatar`	String(1, 1024)	optional	null
`attributes.default_language`	String(1, 1024)	optional	null
`attributes.default_timezone`	String(1, 1024)	optional	null
`attributes.default_gender`	String(1, 1024)	optional	null
`attributes.default_ip`	String(1, 1024)	optional	null
`attributes.default_city`	String(1, 1024)	optional	null
`attributes.default_region`	String(1, 1024)	optional	null
`attributes.default_country`	String(1, 1024)	optional	null
`attributes.default_referrer`	String(1, 1024)	optional	null
`attributes.default_username`	String(1, 1024)	optional	null

Note: userId is not required when attributes.default_email is provided

Request URL

curl --request POST \
	--url https://api.chatbot.com/users \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Response Example

[
    {
      "id": "\<ID\>",
      "timestamp": "2018-01-19T11:55:07.552Z",
      "status": {
        "code": 200,
        "type": "success"
      }
    }
]

List users

Returns list of User objects.

GET https://api.chatbot.com/users

Properties

parameter	type	required	default
`limit`	Number(1, 40)	optional	40
`after`	String(24)	optional
`sort`	Object	optional
`sort.field`	`createdAt`, `lastSeen`	optional	createdAt
`sort.order`	`asc`, `desc`	optional	desc
`match`	`all`, `any`	optional	all
`filters`	Filter[1,5]	optional

Request URL

curl --request GET \
	--url https://api.chatbot.com/users \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

Response Example

    {
      "data": [
        {
          "id": "5b7ff84cc7ca3fb33c9249a8",
          "userId": "0735887f-6aaa-47cc-908e-6c84d093f317",
          "banned": false,
          "attributes": {
            "default_email": "joe@doe.com",
            "default_name": "Joe",
            "default_url": null,
            "default_avatar": null,
            "default_language": null,
            "default_timezone": null,
            "default_gender": null,
            "default_ip": null,
            "default_city": null,
            "default_region": null,
            "default_country": null,
            "default_referrer": null,
            "default_username": null
          },
          "conversations": 0,
          "createdAt": "2019-01-23 13:32:30.163Z",
          "lastSeen": "2019-01-23 13:32:30.163Z"
        }
      ],
      "count": 1
    }

User object

parameter	type
`id`	String
`userId`	String
`banned`	Boolean
`attributes`	Object
`attributes.<pattern>`	String
`attributes.default_email`	String, Null
`attributes.default_name`	String, Null
`attributes.default_url`	String, Null
`attributes.default_avatar`	String, Null
`attributes.default_language`	String, Null
`attributes.default_timezone`	String, Null
`attributes.default_gender`	String, Null
`attributes.default_ip`	String, Null
`attributes.default_city`	String, Null
`attributes.default_region`	String, Null
`attributes.default_country`	String, Null
`attributes.default_referrer`	String, Null
`attributes.default_username`	String, Null
`conversations`	Number
`createdAt`	String
`lastSeen`	String

List single user

List User Details.

GET https://api.chatbot.com/users/:id

URL Params

Required:

id=[alphanumeric]

Request URL

curl --request GET \
	--url https://api.chatbot.com/users/:id \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

Response Example

    {
      "id": "5b7ff847cc3c3fb33c9249a8",
      "userId": "0735887f-6ba5-cccc-908e-6c84d093f317",
      "banned": false,
      "attributes": {
        "default_email": "joe@doe.com",
        "default_name": "Joe",
        "default_url": null,
        "default_avatar": null,
        "default_language": null,
        "default_timezone": null,
        "default_gender": null,
        "default_ip": null,
        "default_city": null,
        "default_region": null,
        "default_country": null,
        "default_referrer": null,
        "default_username": null
      },
      "sessionAttributes": {
        "group-selected": "14"
      },
      "conversations": [
        {
          "id": "5c486eeebda7873576a379e4",
          "date": "2019-01-23 13:32:30.163Z",
          "firstMessage": "hello"
        }
      ],
      "segments": [
        {
          "id": "5c46d514bda7873www6a30c48",
          "name": "Leads"
        }
      ],
      "createdAt": "2019-01-23 13:32:30.163Z",
      "lastSeen": "2019-01-23 13:32:30.163Z"
    }

User details object

parameter	type
`id`	String
`userId`	String
`banned`	Boolean
`attributes`	Object
`attributes.<pattern>`	String
`attributes.default_email`	String, Null
`attributes.default_name`	String, Null
`attributes.default_url`	String, Null
`attributes.default_avatar`	String, Null
`attributes.default_language`	String, Null
`attributes.default_timezone`	String, Null
`attributes.default_gender`	String, Null
`attributes.default_ip`	String, Null
`attributes.default_city`	String, Null
`attributes.default_region`	String, Null
`attributes.default_country`	String, Null
`attributes.default_referrer`	String, Null
`attributes.default_username`	String, Null
`sessionAttributes`	Object
`sessionAttributes.<pattern>`	String
`conversations`	Object[Conversation]
`segments`	Object[Segments]
`createdAt`	String
`lastSeen`	String

Conversation object

parameter	type
`id`	String
`createdAt`	String
`firstMessage`	String, Null

Segments object

parameter	type
`id`	String
`name`	String

Update user

Update user basic data.

PUT https://api.chatbot.com/users/:id

URL Params

Required:

id=[alphanumeric]

Properties

parameter	type	required	default
`attributes`	Object(1, 99)	required
`attributes.<pattern>`	String(1,1024	optional
`attributes.default_email`	String(1, 1024)	optional	null
`attributes.default_name`	String(1, 256)	optional	null
`attributes.default_url`	String(1, 1024)	optional	null
`attributes.default_avatar`	String(1, 1024)	optional	null
`attributes.default_language`	String(1, 1024)	optional	null
`attributes.default_timezone`	String(1, 1024)	optional	null
`attributes.default_gender`	String(1, 1024)	optional	null
`attributes.default_ip`	String(1, 1024)	optional	null
`attributes.default_city`	String(1, 1024)	optional	null
`attributes.default_region`	String(1, 1024)	optional	null
`attributes.default_country`	String(1, 1024)	optional	null
`attributes.default_referrer`	String(1, 1024)	optional	null
`attributes.default_username`	String(1, 1024)	optional	null

Request URL

curl --request PUT \
	--url https://api.chatbot.com/users/:id \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Response Example

    {
      "timestamp": "2018-01-19T11:55:07.552Z",
      "status": {
        "code": 200,
        "type": "success"
      }
    }

Add segments

Adds one or more segments to User.

POST https://api.chatbot.com/users/:id/segments

URL Params

Required:

id=[alphanumeric]

Data Params

String[]

Request URL

curl --request POST \
	--url https://api.chatbot.com/users/:id/segments \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Response Example

{
  "id": "\<ID\>",
  "timestamp": "2018-01-19T11:55:07.552Z",
  "status": {
    "code": 200,
    "type": "success"
  }
}

Update segments

Override user segments.

PUT https://api.chatbot.com/users/:id/segments

URL Params

Required:

id=[alphanumeric]

Data Params

String[]

Request URL

curl --request PUT \
	--url https://api.chatbot.com/users/:id/segments \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Response Example

{
  "id": "\<ID\>",
  "timestamp": "2018-01-19T11:55:07.552Z",
  "status": {
    "code": 200,
    "type": "success"
  }
}

Remove segments

Removes one or more segments from User.

DELETE https://api.chatbot.com/users/:id/segments

URL Params

Required:

id=[alphanumeric]

Data Params

String[]

Request URL

curl --request DELETE \
	--url https://api.chatbot.com/users/:id/segments \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Response Example

        {
          "id": "\<ID\>",
          "timestamp": "2018-01-19T11:55:07.552Z",
          "status": {
            "code": 200,
            "type": "success"
          }
        }

Ban or unban user

Marks User as banned or unbanned.

PUT https://api.chatbot.com/users/:id/ban

URL Params

Required:

id=[alphanumeric]

Properties

parameter	type	required	default
`banned`	Boolean	required

Request URL

curl --request PUT \
	--url https://api.chatbot.com/users/:id/ban \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Response Example

    {
      "timestamp": "2018-01-19T11:55:07.552Z",
      "status": {
        "code": 200,
        "type": "success"
      }
    }

Export users

Streams CSV rows.

POST https://api.chatbot.com/users/export

Properties

parameter	type	required	default
`sort`	Object	optional
`sort.field`	`createdAt`, `lastSeen`	optional	createdAt
`sort.order`	`asc`, `desc`	optional	desc
`match`	`all`, `any`	optional	all
`filters`	Filter[1,5]	optional
`users`	String(24)[1,1000]	optional
`fields`	Field[1,16]	optional

Note: users parameter is not allowed simultaneously with filters and/or match

Request URL

curl --request POST \
	--url https://api.chatbot.com/users/export \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Export fields

field	headline
`default_name`	`Name`
`default_email`	`Email`
`createdAt`	`First Seen`
`lastSeen`	`Last Seen`
`default_source`	`Integration`
`default_url`	`Source`
`userId`	`User ID`
`default_avatar`	`Avatar`
`default_language`	`Language`
`default_timezone`	`Timezone`
`default_gender`	`Gender`
`default_ip`	`IP`
`default_city`	`City`
`default_region`	`Region`
`default_country`	`Country`
`default_referrer`	`Referrer`
`default_username`	`Username`

Users

Create user

Properties

Request URL

Response Example

List users

Properties

Request URL

Response Example

User object

List single user

URL Params

Request URL

Response Example

User details object

Conversation object

Segments object

Update user

URL Params

Properties

Request URL

Response Example

Add segments

URL Params

Request URL

Response Example

Update segments

URL Params

Request URL

Response Example

Remove segments

URL Params

Request URL

Response Example

Ban or unban user

URL Params

Properties

Request URL

Response Example

Export users

Properties

Request URL

Export fields

Start a free ChatBot trial and build your first chatbot today!

Discover our text| products

Start a free ChatBot trial
and build your first chatbot today!