Log in
Automate your customer service. Sign up free
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.

List all users

Returns list of User objects.

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

Request URL

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

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

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
    }

List single user

List single User details.

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

Request URL

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

URL Parameters

Parameter Type Description
id Alphanumeric required User id.

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"
    }

Create user

Creates new user.

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

Request URL

curl --request POST \
	--url https://api.chatbot.com/users \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'
	--data-raw '{
		"userId": "123a45b67c",
		"attributes": {
			"default_name": "John",
			"default_city": "New York"
		}
	}'

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

Response Example

[
    {
      "id": "123a45b67c",
      "timestamp": "2018-01-19T11:55:07.552Z",
      "status": {
        "code": 200,
        "type": "success"
      }
    }
]

Update user

Update User data.

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

Request URL

curl --request PUT \
	--url https://api.chatbot.com/users/:id \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'
	--data-raw '{
		"attributes": {
			"default_name": "Johnny Doe"
		}
	}'

URL Parameters

Parameter Type Description
id Alphanumeric required User id.

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

Response Example

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

Delete user

Delete single user.

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

Request URL

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

URL Parameters

Parameter Type Description
id Alphanumeric required User id.

Response Example

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

Add segments to User

Adds one or more segments to User.

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

Request URL

curl --request POST \
	--url https://api.chatbot.com/users/:id/segments \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data-raw '["<SegmentID>"]'

URL Parameters

Parameter Type Description
id Alphanumeric required User id.

Parameters

Parameter Type Description
String[] String required List of segment(s) IDs

Response Example

{
  "id": "<UserID>",
  "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

Request URL

curl --request PUT \
	--url https://api.chatbot.com/users/:id/segments \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data-raw '["<SegmentID>"]'

URL Parameters

Parameter Type Description
id Alphanumeric required User id.

Parameters

Parameter Type Description
String[] String required List of segment(s) IDs

Response Example

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

Remove segments

Removes one or more segments from User.

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

Request URL

curl --request DELETE \
	--url https://api.chatbot.com/users/:id/segments \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'
	--data-raw '["<SegmentID>"]'

URL Parameters

Parameter Type Description
id Alphanumeric required User id.

Parameters

Parameter Type Description
String[] String required List of segment(s) IDs

Response Example

        {
          "id": "<UserID>",
          "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

Request URL

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

URL Parameters

Parameter Type Description
id Alphanumeric required User id.

Properties

parameter type required default
banned Boolean required false

Response Example

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

Export users

Initiates user export procedure and sends results to the requester email address once it’s ready.

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

Request URL

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

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

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 text| products

LiveChat
Connect with customers

HelpDesk
Support customers with tickets

KnowledgeBase
Guide and educate customers

OpenWidget
Enhance websites with widgets