Dixa Developer Hub
GuidesWebhooksCustom CardsDixa Messenger SDKAPI ReferencesAI Transparency
API References ▾
GuidesWebhooksCustom CardsDixa Messenger SDKAPI ReferencesAI TransparencyDixa website ↗
Dixa website

End Users

List end users

GET
/beta/endusers

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.
Note: Custom attributes are not part of the response at this point. If you need to get custom attributes for a user use the GET /endusers/{userId} endpoint

Authorization

ApiKeyAuth
headerAuthorization<token>

Query Parameters

pageLimit?integer

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

Formatint32
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.

email?string

Filter by the contact's email

phone?string

Filter by the contact's phone number

externalId?string

Filter by the contact's external id

Response Body

The list of end users

application/json
  1. response
data?array<>
meta?
Example Request
curl -X GET 'https://dev.dixa.io/beta/endusers' \  -H 'Authorization: <API token>'
{
"data": [
{
"id": "93b885ad-fe0d-3089-8df6-34904fd59f71",
"createdAt": "2020-12-16T09:41:43Z",
"displayName": "Enduser 0",
"email": "enduser.0@example.org",
"additionalEmails": [],
"additionalPhoneNumbers": [],
"middleNames": [],
"avatarUrl": "https://files.dixa.io/public/image_0_id",
"externalId": "#12345678"
},
{
"id": "55a54008-ad1b-3589-aa21-0d2629c1df41",
"createdAt": "2020-12-16T09:41:43Z",
"displayName": "Enduser 1",
"email": "enduser.1@example.org",
"additionalEmails": [],
"additionalPhoneNumbers": [],
"middleNames": [],
"avatarUrl": "https://files.dixa.io/public/image_1_id",
"externalId": "#12345678"
},
{
"id": "9e688c58-a548-3b8e-af69-c9e1005ad0bf",
"createdAt": "2020-12-16T09:41:43Z",
"displayName": "Enduser 2",
"email": "enduser.2@example.org",
"additionalEmails": [],
"additionalPhoneNumbers": [],
"middleNames": [],
"avatarUrl": "https://files.dixa.io/public/image_2_id",
"externalId": "#12345678"
},
{
"id": "86666835-06aa-3d90-8bbd-5a74ac4edf68",
"createdAt": "2020-12-16T09:41:43Z",
"displayName": "Enduser 3",
"email": "enduser.3@example.org",
"additionalEmails": [],
"additionalPhoneNumbers": [],
"middleNames": [],
"avatarUrl": "https://files.dixa.io/public/image_3_id",
"externalId": "#12345678"
}
]
}

Update end users

PUT
/beta/endusers

Bulk update end users.

Authorization

ApiKeyAuth organization.member
headerAuthorization<token>

Scope: organization.member

Request Body

List of end user update actions

application/json
  1. body
data?array<>

Response Body

The updated end users

application/json
  1. response
data?array<|>
Example Request
curl -X PUT 'https://dev.dixa.io/beta/endusers' \  -H 'Authorization: <API token>' \  -H 'Content-Type: application/json' \  -d '{  "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"    }  ]}'
{
"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."
],
"avatarUrl": "https://files.dixa.io/public/image_id",
"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"
}
]
}

Create end user

POST
/beta/endusers

Create an end user.

Authorization

ApiKeyAuth organization.member
headerAuthorization<token>

Scope: organization.member

Request Body

The end user's details

application/json
  1. body
displayName?string

The contact's display name

email?string

The contact's primary email address

phoneNumber?string

The contact's primary phone number

additionalEmails?array<string>

Additional email addresses for the contact

additionalPhoneNumbers?array<string>

Additional phone numbers for the contact

firstName?string

The contact's first name

lastName?string

The contact's last name

middleNames?array<string>

The contact's middle names

avatarUrl?string

The url from which to load the contact's avatar

externalId?string

Custom external identifier for the contact

Response Body

The created end user

application/json
  1. response
data*
Example Request
curl -X POST 'https://dev.dixa.io/beta/endusers' \  -H 'Authorization: <API token>' \  -H 'Content-Type: application/json' \  -d '{  "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"}'
{
"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": [],
"avatarUrl": "https://files.dixa.io/public/image_id",
"externalId": "#12345678",
"customAttributes": [
{
"id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
"name": "My Attribute",
"identifier": "my_attribute",
"value": "My Attribute Value"
}
]
}
}

Patch end users

PATCH
/beta/endusers

Bulk patch end users.

Authorization

ApiKeyAuth organization.member
headerAuthorization<token>

Scope: organization.member

Request Body

List of end user patch actions

application/json
  1. body
data?array<>

Response Body

The patched end users

application/json
  1. response
data?array<|>
Example Request
curl -X PATCH 'https://dev.dixa.io/beta/endusers' \  -H 'Authorization: <API token>' \  -H 'Content-Type: application/json' \  -d '{  "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"    }  ]}'
{
"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": [],
"avatarUrl": "https://files.dixa.io/public/image_id",
"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"
}
]
}

Create end users

POST
/beta/endusers/bulk

Create multiple end users in a single bulk action

Authorization

ApiKeyAuth organization.member
headerAuthorization<token>

Scope: organization.member

Request Body

The list of end user details

application/json
  1. body
data?array<>

Response Body

The created end users

application/json
  1. response
data?array<|>
Example Request
curl -X POST 'https://dev.dixa.io/beta/endusers/bulk' \  -H 'Authorization: <API token>' \  -H 'Content-Type: application/json' \  -d '{  "data": [    {      "displayName": "Alice Brown",      "email": "alice@brown.com",      "phoneNumber": "+551155256325",      "additionalEmails": [],      "additionalPhoneNumbers": [],      "firstName": "Alice",      "lastName": "Brown",      "middleNames": [],      "avatarUrl": "http://avatar.url",      "externalId": "#12345678"    }  ]}'
{
"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": [],
"avatarUrl": "https://files.dixa.io/public/image_0_id",
"externalId": "#12345678"
},
"_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": [],
"avatarUrl": "https://files.dixa.io/public/image_1_id",
"externalId": "#12345678"
},
"_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": [],
"avatarUrl": "https://files.dixa.io/public/image_2_id",
"externalId": "#12345678"
},
"_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": [],
"avatarUrl": "https://files.dixa.io/public/image_3_id",
"externalId": "#12345678"
},
"_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
/beta/endusers/{userId}

Get an end user by id.

Authorization

ApiKeyAuth
headerAuthorization<token>

Path Parameters

userId*string

The end user id

Formatuuid

Response Body

The end user

application/json
  1. response
data*
Example Request
curl -X GET 'https://dev.dixa.io/beta/endusers/{userId}' \  -H 'Authorization: <API token>'
{
"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": [],
"avatarUrl": "https://files.dixa.io/public/image_id",
"externalId": "#12345678",
"customAttributes": [
{
"id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
"name": "My Attribute",
"identifier": "my_attribute",
"value": "My Attribute Value"
}
]
}
}

Update end user

PUT
/beta/endusers/{userId}

Update an end user.

Authorization

ApiKeyAuth organization.member
headerAuthorization<token>

Scope: organization.member

Path Parameters

userId*string

The end user id

Formatuuid

Request Body

The updated details for an end user

application/json
  1. body
displayName*string
email?string
phoneNumber?string
additionalEmails?array<string>
additionalPhoneNumbers?array<string>
firstName?string
lastName?string
middleNames?array<string>
avatarUrl?string
externalId?string

Response Body

The updated end user

application/json
  1. response
data*
Example Request
curl -X PUT 'https://dev.dixa.io/beta/endusers/{userId}' \  -H 'Authorization: <API token>' \  -H 'Content-Type: application/json' \  -d '{  "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"}'
{
"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."
],
"avatarUrl": "https://files.dixa.io/public/image_id",
"externalId": "#12345678",
"customAttributes": [
{
"id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
"name": "My Attribute",
"identifier": "my_attribute",
"value": "My Attribute Value"
}
]
}
}

Patch end user

PATCH
/beta/endusers/{userId}

Patch an end user.

Authorization

ApiKeyAuth organization.member
headerAuthorization<token>

Scope: organization.member

Path Parameters

userId*string

The end user id to be patched

Formatuuid

Request Body

The end user patch

application/json
  1. body
displayName?string
email?string
phoneNumber?string
additionalEmails?array<string>
additionalPhoneNumbers?array<string>
firstName?string
lastName?string
middleNames?array<string>
avatarUrl?string
externalId?string

Response Body

The patched end user

application/json
  1. response
data*
Example Request
curl -X PATCH 'https://dev.dixa.io/beta/endusers/{userId}' \  -H 'Authorization: <API token>' \  -H 'Content-Type: application/json' \  -d '{  "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"}'
{
"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": [],
"avatarUrl": "https://files.dixa.io/public/image_id",
"externalId": "#12345678",
"customAttributes": [
{
"id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
"name": "My Attribute",
"identifier": "my_attribute",
"value": "My Attribute Value"
}
]
}
}

Anonymize end user

PATCH
/beta/endusers/{userId}/anonymize

Request the anonymization of an end user.

Authorization

ApiKeyAuth anonymization
headerAuthorization<token>

Scope: anonymization

Path Parameters

userId*string

The id of the end user to anonymize

Formatuuid

Query Parameters

force?boolean

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

Defaultfalse

Response Body

The end user's anonymization request status

application/json
  1. response
data*
Example Request
curl -X PATCH 'https://dev.dixa.io/beta/endusers/{userId}/anonymize' \  -H 'Authorization: <API token>'
{
"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"
}
}

Patch end user custom attributes

PATCH
/beta/endusers/{userId}/custom-attributes

Patch custom attributes of an end user

Authorization

ApiKeyAuth contact.custom_attribute
headerAuthorization<token>

Scope: contact.custom_attribute

Path Parameters

userId*string
Formatuuid

Request Body

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].

application/json
  1. body
[key: string]?array<string>|

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

Response Body

The patched end user attributes

application/json
  1. response
data?array<>
Example Request
curl -X PATCH 'https://dev.dixa.io/beta/endusers/{userId}/custom-attributes' \  -H 'Authorization: <API token>' \  -H 'Content-Type: application/json' \  -d '{  "274e5a2c-be0d-42c0-b725-3dd533729f68": "abcdef",  "befae0d9-9679-42b9-af76-e76f64e28429": [    "example1",    "example2"  ]}'
{
"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"
]
}
]
}

List end user conversations

GET
/beta/endusers/{userId}/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

Authorization

ApiKeyAuth
headerAuthorization<token>

Path Parameters

userId*string
Formatuuid

Query Parameters

pageLimit?integer

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

Formatint32
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.

Response Body

The list of conversations requested by an EndUser

application/json
  1. response
data?array<||||||||||>
meta?
Example Request
curl -X GET 'https://dev.dixa.io/beta/endusers/{userId}/conversations' \  -H 'Authorization: <API token>'
{
"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 AI agentsget

Previous Page

List end usersget

Next Page