End Users

Anonymize end user

Request the anonymization of an end user.

SecurityApiKeyAuth
Request
path Parameters
userId
required
string <uuid>

The id of the end user to anonymize

query Parameters
force
boolean
Default: false

Whether to force close all the conversations initiated by the end user, if any are found in a non closed state.

Responses
202

The end user's anonymization request status

400
404
409
500
patch/v1/endusers/{userId}/anonymize
Request samples
Response samples
application/json
{
  • "data": {
    • "id": "6bf55369-a670-4e6b-9f70-ecdb9913549f",
    • "entityType": "UserAnonymizationType",
    • "_type": "User",
    • "initiatedAt": "2021-12-01T12:46:36.581Z[GMT]",
    • "targetEntityId": "f28fafd6-2e42-4441-943c-388a8e0ef433",
    • "requestedBy": "2b01e4c9-0c3a-47d4-9462-cd5a1a4687f5"
    }
}

Create end user

Create an end user.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required

The end user's details

additionalEmails
Array of strings unique

Additional email addresses for the contact

additionalPhoneNumbers
Array of strings unique

Additional phone numbers for the contact

avatarUrl
string

The url from which to load the contact's avatar

displayName
string

The contact's display name

email
string

The contact's primary email address

externalId
string

Custom external identifier for the contact

firstName
string

The contact's first name

lastName
string

The contact's last name

middleNames
Array of strings

The contact's middle names

phoneNumber
string

The contact's primary phone number

Responses
201

The created end user

400

Invalid value extracted from request context, Invalid value for: body, Validation failure during enduser creation

500

Internal failure during request processing

post/v1/endusers
Request samples
application/json
{
  • "displayName": "Alice Brown",
  • "email": "alice@brown.com",
  • "phoneNumber": "+551155256325",
  • "additionalEmails": [
    • "alice@secondary.email"
    ],
  • "additionalPhoneNumbers": [
    • "+5566778899"
    ],
  • "firstName": "Alice",
  • "lastName": "Brown",
  • "middleNames": [ ],
  • "avatarUrl": "http://avatar.url",
  • "externalId": "#12345678"
}
Response samples
application/json
{
  • "data": {
    • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
    • "createdAt": "2020-12-16T09:41:43Z",
    • "displayName": "Alice Brown",
    • "email": "alice@brown.com",
    • "phoneNumber": "+551155256325",
    • "additionalEmails": [
      • "alice@secondary.email"
      ],
    • "additionalPhoneNumbers": [
      • "+5566778899"
      ],
    • "firstName": "Alice",
    • "lastName": "Brown",
    • "middleNames": [ ],
    • "externalId": "#12345678",
    • "customAttributes": [
      • {
        • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
        • "name": "My Attribute",
        • "identifier": "my_attribute",
        • "value": "My Attribute Value"
        }
      ]
    }
}

Create end users

Create multiple end users in a single bulk action

SecurityApiKeyAuth
Request
Request Body schema: application/json
required

The list of end user details

Array of objects (CreateEndUserInput)
Responses
201

The created end users

400

Invalid value extracted from request context, Invalid value for: body

500

Internal failure during request processing

post/v1/endusers/bulk
Request samples
application/json
{
  • "data": [
    • {
      • "displayName": "Alice Brown",
      • "email": "alice@brown.com",
      • "phoneNumber": "+551155256325",
      • "additionalEmails": [ ],
      • "additionalPhoneNumbers": [ ],
      • "firstName": "Alice",
      • "lastName": "Brown",
      • "middleNames": [ ],
      • "avatarUrl": "http://avatar.url",
      • "externalId": "#12345678"
      }
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "data": {
        • "id": "93b885ad-fe0d-3089-8df6-34904fd59f71",
        • "createdAt": "2020-12-16T09:41:43Z",
        • "displayName": "Enduser 0",
        • "email": "enduser.0@example.org",
        • "additionalEmails": [ ],
        • "additionalPhoneNumbers": [ ],
        • "middleNames": [ ],
        • "externalId": "#12345678",
        • "customAttributes": [
          • {
            • "id": "ec7f7e7b-b437-32ce-8681-45f71d37b53c",
            • "name": "My Attribute 0",
            • "identifier": "my_attribute_0",
            • "value": "My Attribute Value 0"
            }
          ]
        },
      • "_type": "BulkActionSuccess"
      },
    • {
      • "data": {
        • "id": "55a54008-ad1b-3589-aa21-0d2629c1df41",
        • "createdAt": "2020-12-16T09:41:43Z",
        • "displayName": "Enduser 1",
        • "email": "enduser.1@example.org",
        • "additionalEmails": [ ],
        • "additionalPhoneNumbers": [ ],
        • "middleNames": [ ],
        • "externalId": "#12345678",
        • "customAttributes": [
          • {
            • "id": "8bb6c178-3864-3f96-91cc-6a4de6c51709",
            • "name": "My Attribute 1",
            • "identifier": "my_attribute_1",
            • "value": "My Attribute Value 1"
            }
          ]
        },
      • "_type": "BulkActionSuccess"
      },
    • {
      • "data": {
        • "id": "9e688c58-a548-3b8e-af69-c9e1005ad0bf",
        • "createdAt": "2020-12-16T09:41:43Z",
        • "displayName": "Enduser 2",
        • "email": "enduser.2@example.org",
        • "additionalEmails": [ ],
        • "additionalPhoneNumbers": [ ],
        • "middleNames": [ ],
        • "externalId": "#12345678",
        • "customAttributes": [
          • {
            • "id": "06eca1b4-37c7-304c-83ce-6546c8110110",
            • "name": "My Attribute 2",
            • "identifier": "my_attribute_2",
            • "value": "My Attribute Value 2"
            }
          ]
        },
      • "_type": "BulkActionSuccess"
      },
    • {
      • "data": {
        • "id": "86666835-06aa-3d90-8bbd-5a74ac4edf68",
        • "createdAt": "2020-12-16T09:41:43Z",
        • "displayName": "Enduser 3",
        • "email": "enduser.3@example.org",
        • "additionalEmails": [ ],
        • "additionalPhoneNumbers": [ ],
        • "middleNames": [ ],
        • "externalId": "#12345678",
        • "customAttributes": [
          • {
            • "id": "89e74e64-0b8c-3625-ba29-de0616794d5d",
            • "name": "My Attribute 3",
            • "identifier": "my_attribute_3",
            • "value": "My Attribute Value 3"
            }
          ]
        },
      • "_type": "BulkActionSuccess"
      },
    • {
      • "error": {
        • "id": "1b6d1e11-0626-414e-906a-b80a384cfef0",
        • "message": "Create EndUser [userId=...] in [orgId=...] failed with [errors=...]",
        • "_type": "Validation"
        },
      • "_type": "BulkActionFailure"
      }
    ]
}

Get end user

Get an end user by id.

SecurityApiKeyAuth
Request
path Parameters
userId
required
string <uuid>

The end user id

Responses
200

The end user

400

Invalid value for: path parameter userId, Invalid value extracted from request context

404

An entity in this request could not be found

500

Internal failure during request processing

get/v1/endusers/{userId}
Request samples
Response samples
application/json
{
  • "data": {
    • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
    • "createdAt": "2020-12-16T09:41:43Z",
    • "displayName": "Alice Brown",
    • "email": "alice@brown.com",
    • "phoneNumber": "+551155256325",
    • "additionalEmails": [
      • "alice@secondary.email"
      ],
    • "additionalPhoneNumbers": [
      • "+5566778899"
      ],
    • "firstName": "Alice",
    • "lastName": "Brown",
    • "middleNames": [ ],
    • "externalId": "#12345678",
    • "customAttributes": [
      • {
        • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
        • "name": "My Attribute",
        • "identifier": "my_attribute",
        • "value": "My Attribute Value"
        }
      ]
    }
}

List end user conversations

Lists conversations requested by an end user.
Note: Custom attributes are not part of the response at this point. If you need to get custom attributes for a conversation use the GET /conversations/{conversationId} endpoint

SecurityApiKeyAuth
Request
path Parameters
userId
required
string <uuid>
query Parameters
pageKey
string

Base64 encoded form of pagination query parameters. Do not try to construct or change programmatically as the internal structure may change without notice.

pageLimit
integer <int32>

Maximum number of results per page. May be used in combination with pageKey to change the number of results in between page requests.

Responses
200

The list of conversations requested by an EndUser

400

Invalid value for: path parameter userId, Invalid value extracted from request context, Invalid value for: query parameter pageLimit, Invalid value for: query parameter pageKey

404

An entity in this request could not be found

500

Internal failure during request processing

get/v1/endusers/{userId}/conversations
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "requesterId": "9deb936b-52e5-4c44-828d-4c8d48fe0c7e",
      • "channel": "WidgetChat",
      • "createdAt": "2020-12-16T09:41:43Z",
      • "direction": "Outbound",
      • "state": "Open",
      • "stateUpdatedAt": "2020-12-16T09:41:43Z",
      • "assignment": {
        • "agentId": "0e4d0ead-dc69-470a-9b3a-e7eb16a56453",
        • "assignedAt": "2020-12-16T11:00:34Z"
        },
      • "queue": {
        • "id": "cd87b232-64c8-4ad5-b81a-6f9233352d97",
        • "queuedAt": "2020-12-16T10:40:40Z"
        },
      • "browserInfo": {
        • "name": "Chrome 9",
        • "version": "91.0.4472.114",
        • "ipAddress": "127.0.0.1",
        • "originatingUrl": "http://localhost:3000/"
        },
      • "language": "en",
      • "link": {
        • "parentId": 1234,
        • "_type": "SideConversation"
        },
      • "_type": "ChatConversation"
      }
    ]
}

List end users

Lists all end users in an organization. It is possible to filter by one of the mutually exclusive parameters: email or phone number. In case both are provided, an error is returned.

SecurityApiKeyAuth
Request
query Parameters
email
string

Filter by the contact's email

externalId
string

Filter by the contact's external id

pageKey
string

Base64 encoded form of pagination query parameters. Do not try to construct or change programmatically as the internal structure may change without notice.

pageLimit
integer <int32>

Maximum number of results per page. May be used in combination with pageKey to change the number of results in between page requests.

phone
string

Filter by the contact's phone number

Responses
200

The list of end users

400

Invalid value extracted from request context, Invalid value for: query parameter pageLimit, Invalid value for: query parameter pageKey, Invalid value for: query parameter email, Invalid value for: query parameter phone, Invalid value for: query parameter externalId, Duplicate phone number, Duplicate email address, Invalid filters: Cannot provide more than one filter

404

An entity in this request could not be found

500

Internal failure during request processing

get/v1/endusers
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "id": "93b885ad-fe0d-3089-8df6-34904fd59f71",
      • "createdAt": "2020-12-16T09:41:43Z",
      • "displayName": "Enduser 0",
      • "email": "enduser.0@example.org",
      • "additionalEmails": [ ],
      • "additionalPhoneNumbers": [ ],
      • "middleNames": [ ],
      • "externalId": "#12345678",
      • "customAttributes": [
        • {
          • "id": "ec7f7e7b-b437-32ce-8681-45f71d37b53c",
          • "name": "My Attribute 0",
          • "identifier": "my_attribute_0",
          • "value": "My Attribute Value 0"
          }
        ]
      },
    • {
      • "id": "55a54008-ad1b-3589-aa21-0d2629c1df41",
      • "createdAt": "2020-12-16T09:41:43Z",
      • "displayName": "Enduser 1",
      • "email": "enduser.1@example.org",
      • "additionalEmails": [ ],
      • "additionalPhoneNumbers": [ ],
      • "middleNames": [ ],
      • "externalId": "#12345678",
      • "customAttributes": [
        • {
          • "id": "8bb6c178-3864-3f96-91cc-6a4de6c51709",
          • "name": "My Attribute 1",
          • "identifier": "my_attribute_1",
          • "value": "My Attribute Value 1"
          }
        ]
      },
    • {
      • "id": "9e688c58-a548-3b8e-af69-c9e1005ad0bf",
      • "createdAt": "2020-12-16T09:41:43Z",
      • "displayName": "Enduser 2",
      • "email": "enduser.2@example.org",
      • "additionalEmails": [ ],
      • "additionalPhoneNumbers": [ ],
      • "middleNames": [ ],
      • "externalId": "#12345678",
      • "customAttributes": [
        • {
          • "id": "06eca1b4-37c7-304c-83ce-6546c8110110",
          • "name": "My Attribute 2",
          • "identifier": "my_attribute_2",
          • "value": "My Attribute Value 2"
          }
        ]
      },
    • {
      • "id": "86666835-06aa-3d90-8bbd-5a74ac4edf68",
      • "createdAt": "2020-12-16T09:41:43Z",
      • "displayName": "Enduser 3",
      • "email": "enduser.3@example.org",
      • "additionalEmails": [ ],
      • "additionalPhoneNumbers": [ ],
      • "middleNames": [ ],
      • "externalId": "#12345678",
      • "customAttributes": [
        • {
          • "id": "89e74e64-0b8c-3625-ba29-de0616794d5d",
          • "name": "My Attribute 3",
          • "identifier": "my_attribute_3",
          • "value": "My Attribute Value 3"
          }
        ]
      }
    ]
}

Patch end user

Patch an end user.

SecurityApiKeyAuth
Request
path Parameters
userId
required
string <uuid>

The end user id to be patched

Request Body schema: application/json
required

The end user patch

additionalEmails
Array of strings unique
additionalPhoneNumbers
Array of strings unique
avatarUrl
string
displayName
string
email
string
externalId
string
firstName
string
lastName
string
middleNames
Array of strings
phoneNumber
string
Responses
200

The patched end user

400

Invalid value for: path parameter userId, Invalid value extracted from request context, Invalid value for: body, Validation failure during update

404

An entity in this request could not be found

500

Internal failure during request processing

patch/v1/endusers/{userId}
Request samples
application/json
{
  • "displayName": "Alice Brown",
  • "email": "alice@brown.com",
  • "phoneNumber": "+551155256325",
  • "additionalEmails": [
    • "alice@secondary.email"
    ],
  • "additionalPhoneNumbers": [
    • "+5566778899"
    ],
  • "firstName": "Alice",
  • "lastName": "Brown",
  • "middleNames": [ ],
  • "avatarUrl": "http://avatar.url",
  • "externalId": "#12345678"
}
Response samples
application/json
{
  • "data": {
    • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
    • "createdAt": "2020-12-16T09:41:43Z",
    • "displayName": "Alice Brown",
    • "email": "alice@brown.com",
    • "phoneNumber": "+551155256325",
    • "additionalEmails": [
      • "alice@secondary.email"
      ],
    • "additionalPhoneNumbers": [
      • "+5566778899"
      ],
    • "firstName": "Alice",
    • "lastName": "Brown",
    • "middleNames": [ ],
    • "externalId": "#12345678",
    • "customAttributes": [
      • {
        • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
        • "name": "My Attribute",
        • "identifier": "my_attribute",
        • "value": "My Attribute Value"
        }
      ]
    }
}

Patch end user custom attributes

Patch custom attributes of an end user

SecurityApiKeyAuth
Request
path Parameters
userId
required
string <uuid>
Request Body schema: application/json
required

The custom attributes of an end user to be patched. This should map the custom attribute id to the desired attribute value. Format: Map[UUID, Option[AttributeValue].

additional property
Array of strings or string

AttributeValue values: String[] if the type of the custom attribute is Select or String if the type of the custom attribute is Text

Responses
200

The patched end user attributes

400

Invalid value for: path parameter userId, Invalid value extracted from request context, Invalid value for: body, Invalid input for patching

401

The user who issued the access token used in the request is not authorized to perform the operation

404

An entity in this request could not be found

patch/v1/endusers/{userId}/custom-attributes
Request samples
application/json
{
  • "274e5a2c-be0d-42c0-b725-3dd533729f68": "abcdef",
  • "befae0d9-9679-42b9-af76-e76f64e28429": [
    • "example1",
    • "example2"
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "id": "274e5a2c-be0d-42c0-b725-3dd533729f68",
      • "name": "End user attribute",
      • "identifier": "end_user_attribute",
      • "value": "abcdef"
      },
    • {
      • "id": "befae0d9-9679-42b9-af76-e76f64e28429",
      • "name": "End user attribute 2",
      • "identifier": "end_user_attribute_2",
      • "value": [
        • "example1",
        • "example2"
        ]
      }
    ]
}

Patch end users

Bulk patch end users.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required

List of end user patch actions

Array of objects (BulkPatchEndUserInput)
Responses
200

The patched end users

400

Invalid value extracted from request context, Invalid value for: body

500

Internal failure during request processing

patch/v1/endusers
Request samples
application/json
{
  • "data": [
    • {
      • "id": "43b1fe06-a7c4-4f34-8e48-b0559e6acdb9",
      • "displayName": "Alice Brown",
      • "email": "alice@brown.com",
      • "phoneNumber": "+551155256325",
      • "additionalEmails": [
        • "alice@secondary.email"
        ],
      • "additionalPhoneNumbers": [
        • "+5566778899"
        ],
      • "firstName": "Alice",
      • "lastName": "Brown",
      • "middleNames": [ ],
      • "avatarUrl": "http://avatar.url",
      • "externalId": "#12345678"
      }
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "data": {
        • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
        • "createdAt": "2020-12-16T09:41:43Z",
        • "displayName": "Alice Brown",
        • "email": "alice@brown.com",
        • "phoneNumber": "+551155256325",
        • "additionalEmails": [
          • "alice@secondary.email"
          ],
        • "additionalPhoneNumbers": [
          • "+5566778899"
          ],
        • "firstName": "Alice",
        • "lastName": "Brown",
        • "middleNames": [ ],
        • "externalId": "#12345678",
        • "customAttributes": [
          • {
            • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
            • "name": "My Attribute",
            • "identifier": "my_attribute",
            • "value": "My Attribute Value"
            }
          ]
        },
      • "_type": "BulkActionSuccess"
      },
    • {
      • "error": {
        • "id": "ace11abb-4ed0-42bd-9e3b-4ef6db58e0aa",
        • "message": "Updating EndUser [id=ace11abb-4ed0-42bd-9e3b-4ef6db58e0aa] in [org=b86a1842-437c-4c55-ac4b-0a9cd2f44dfb] failed with [errors=PhoneNumberExists]",
        • "_type": "Validation"
        },
      • "_type": "BulkActionFailure"
      }
    ]
}

Update end user

Update an end user.

SecurityApiKeyAuth
Request
path Parameters
userId
required
string <uuid>

The end user id

Request Body schema: application/json
required

The updated details for an end user

additionalEmails
Array of strings unique
additionalPhoneNumbers
Array of strings unique
avatarUrl
string
displayName
required
string
email
string
externalId
string
firstName
string
lastName
string
middleNames
Array of strings
phoneNumber
string
Responses
200

The updated end user

400

Invalid value for: path parameter userId, Invalid value extracted from request context, Invalid value for: body, Validation failure during update

404

An entity in this request could not be found

500

Internal failure during request processing

put/v1/endusers/{userId}
Request samples
application/json
{
  • "displayName": "Alice Brown",
  • "email": "alice@brown.com",
  • "phoneNumber": "+551155256325",
  • "additionalEmails": [
    • "alice@secondary.email"
    ],
  • "additionalPhoneNumbers": [
    • "+5566778899"
    ],
  • "firstName": "Alice",
  • "lastName": "Brown",
  • "middleNames": [
    • "J."
    ],
  • "avatarUrl": "http://avatar.url",
  • "externalId": "#12345678"
}
Response samples
application/json
{
  • "data": {
    • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
    • "createdAt": "2020-12-16T09:41:43Z",
    • "displayName": "Alice Brown",
    • "email": "alice@brown.com",
    • "phoneNumber": "+551155256325",
    • "additionalEmails": [
      • "alice@secondary.email"
      ],
    • "additionalPhoneNumbers": [
      • "+5566778899"
      ],
    • "firstName": "Alice",
    • "lastName": "Brown",
    • "middleNames": [
      • "J."
      ],
    • "externalId": "#12345678",
    • "customAttributes": [
      • {
        • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
        • "name": "My Attribute",
        • "identifier": "my_attribute",
        • "value": "My Attribute Value"
        }
      ]
    }
}

Update end users

Bulk update end users.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required

List of end user update actions

Array of objects (BulkUpdateEndUserInput)
Responses
200

The updated end users

400

Invalid value extracted from request context, Invalid value for: body

500

Internal failure during request processing

put/v1/endusers
Request samples
application/json
{
  • "data": [
    • {
      • "id": "d4826125-559f-496f-ad71-a0340f0cae06",
      • "displayName": "Alice Brown",
      • "email": "alice@brown.com",
      • "phoneNumber": "+551155256325",
      • "additionalEmails": [
        • "alice@secondary.email"
        ],
      • "additionalPhoneNumbers": [
        • "+5566778899"
        ],
      • "firstName": "Alice",
      • "lastName": "Brown",
      • "middleNames": [
        • "J."
        ],
      • "avatarUrl": "http://avatar.url",
      • "externalId": "#12345678"
      }
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "data": {
        • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
        • "createdAt": "2020-12-16T09:41:43Z",
        • "displayName": "Alice Brown",
        • "email": "alice@brown.com",
        • "phoneNumber": "+551155256325",
        • "additionalEmails": [
          • "alice@secondary.email"
          ],
        • "additionalPhoneNumbers": [
          • "+5566778899"
          ],
        • "firstName": "Alice",
        • "lastName": "Brown",
        • "middleNames": [
          • "J."
          ],
        • "externalId": "#12345678",
        • "customAttributes": [
          • {
            • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
            • "name": "My Attribute",
            • "identifier": "my_attribute",
            • "value": "My Attribute Value"
            }
          ]
        },
      • "_type": "BulkActionSuccess"
      },
    • {
      • "error": {
        • "id": "8fe8f4c3-7bc6-4767-924a-d9afa7ac7009",
        • "message": "Updating EndUser [id:8fe8f4c3-7bc6-4767-924a-d9afa7ac7009] failed with [errors:PhoneNumberExists]",
        • "_type": "Validation"
        },
      • "_type": "BulkActionFailure"
      }
    ]
}