Log in

Build your bot using ChatBot API

API 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

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

Free 14-day trial No credit card required

Discover our other products

LiveChat
Connect with customers

HelpDesk
Support customers with tickets

KnowledgeBase
Guide and educate customers