Skip to content
Dixa API/
/
Claim conversation

Dixa API (v1)

Download OpenAPI description
v1.json
v1.yaml
Languages
Servers
Mock server
https://docs.dixa.io/_mock/openapi/dixa-api/v1
https://dev.dixa.io

Analytics

Operations

Agents

Operations

End Users

Operations

Chatbots

Operations

Create end user

Request

Create an end user.

Security
ApiKeyAuth
Bodyapplication/jsonrequired

The end user's details

displayNamestring

The contact's display name

emailstring

The contact's primary email address

phoneNumberstring

The contact's primary phone number

additionalEmailsArray of stringsunique

Additional email addresses for the contact

additionalPhoneNumbersArray of stringsunique

Additional phone numbers for the contact

firstNamestring

The contact's first name

lastNamestring

The contact's last name

middleNamesArray of strings

The contact's middle names

avatarUrlstring

The url from which to load the contact's avatar

externalIdstring

Custom external identifier for the contact

curl -i -X POST \
  https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/endusers \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -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"
  }'

Responses

The created end user

Bodyapplication/json
dataobject(EndUser)required
data.​idstring(uuid)required

Unique identifier for the contact

data.​createdAtstring(date-time)required

Time when the contact was created

data.​displayNamestring

The contact's display name

data.​emailstring

The contact's primary email address

data.​phoneNumberstring

The contact's primary phone number

data.​additionalEmailsArray of stringsunique

Additional email addresses for the contact

data.​additionalPhoneNumbersArray of stringsunique

Additional phone numbers for the contact

data.​firstNamestring

The contact's first name

data.​lastNamestring

The contact's last name

data.​middleNamesArray of strings

The contact's middle names

data.​avatarUrlstring

The url from which to load the contact's avatar

data.​externalIdstring

Custom external identifier for the contact

data.​customAttributesArray of objects(CustomAttribute)

Custom attributes for the contact

Response
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": [ … ],
    "additionalPhoneNumbers": [ … ],
    "firstName": "Alice",
    "lastName": "Brown",
    "middleNames": [],
    "avatarUrl": "https://files.dixa.io/public/image_id",
    "externalId": "#12345678",
    "customAttributes": [ … ]
  }
}

Get end user

Request

Get an end user by id.

Security
ApiKeyAuth
Path
userIdstring(uuid)required

The end user id

curl -i -X GET \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/endusers/{userId}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

The end user

Bodyapplication/json
dataobject(EndUser)required
data.​idstring(uuid)required

Unique identifier for the contact

data.​createdAtstring(date-time)required

Time when the contact was created

data.​displayNamestring

The contact's display name

data.​emailstring

The contact's primary email address

data.​phoneNumberstring

The contact's primary phone number

data.​additionalEmailsArray of stringsunique

Additional email addresses for the contact

data.​additionalPhoneNumbersArray of stringsunique

Additional phone numbers for the contact

data.​firstNamestring

The contact's first name

data.​lastNamestring

The contact's last name

data.​middleNamesArray of strings

The contact's middle names

data.​avatarUrlstring

The url from which to load the contact's avatar

data.​externalIdstring

Custom external identifier for the contact

data.​customAttributesArray of objects(CustomAttribute)

Custom attributes for the contact

Response
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": [ … ],
    "additionalPhoneNumbers": [ … ],
    "firstName": "Alice",
    "lastName": "Brown",
    "middleNames": [],
    "avatarUrl": "https://files.dixa.io/public/image_id",
    "externalId": "#12345678",
    "customAttributes": [ … ]
  }
}

List end user conversations

Request

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

Security
ApiKeyAuth
Path
userIdstring(uuid)required
Query
pageLimitinteger(int32)

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

pageKeystring

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

curl -i -X GET \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/endusers/{userId}/conversations?pageLimit=0&pageKey=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

The list of conversations requested by an EndUser

Bodyapplication/json
dataArray of AnonymizedConversation (object) or ChatConversation (object) or ContactFormConversation (object) or EmailConversation (object) or FacebookMessengerConversation (object) or GenericConversation (object) or MessengerConversation (object) or PstnPhoneConversation (object) or SmsConversation (object) or TwitterConversation (object) or WhatsAppConversation (object)(Conversation)
metaobject(PaginationLinks)
Response
application/json
{
  "data": [
    { … }
  ]
}

Close conversation

Request

Mark a conversation as closed by providing its id.

Security
ApiKeyAuth
Path
conversationIdinteger(int64)required
Bodyapplication/json

An optional agent/admin to close the conversation

userIdstring(uuid)
curl -i -X PUT \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations/{conversationId}/close' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "5a556159-9c21-4f3e-a44f-d323deb80d16"
  }'

Responses

The conversation was successfully closed

Response
No content

Followup conversation

Request

Follow up a conversation by providing its id and expiration timestamp.

Security
ApiKeyAuth
Path
conversationIdinteger(int64)required
Bodyapplication/jsonrequired

A request to followup the conversation

timestampstring(date-time)required

A timestamp for when the followup should expire

userIdstring(uuid)

An optional agent/admin to followup the conversation

curl -i -X PUT \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations/{conversationId}/followup' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "timestamp": "2025-01-08T08:31:25Z",
    "userId": "5a556159-9c21-4f3e-a44f-d323deb80d16"
  }'

Responses

The conversation was successfully followed up

Response
No content

Transfer conversation

Request

Transfer a conversation to a target queue.

Security
ApiKeyAuth
Path
conversationIdinteger(int64)required
Bodyapplication/jsonrequired

Transfer conversation request

queueIdstring(uuid)required

The target queue for the conversation transfer

userIdstring(uuid)

An optional agent/admin to originate the transfer of the conversation

curl -i -X PUT \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations/{conversationId}/transfer/queue' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "queueId": "92f8d193-b26f-4a62-86a3-bb03ee0915e9",
    "userId": "a53b25da-f676-4c52-acac-58c9280aa23d"
  }'

Responses

The conversation was successfully transferred to the target queue

Response
No content

Create conversation rating result

Request

Create a rating result for a specific conversation.

Security
ApiKeyAuth
Path
conversationIdinteger(int64)required
ratingIdstringrequired

The ratingId parameter has to be the ID of the offer created via invoking the /conversations/{conversationId}/ratings/offer endpoint.

Bodyapplication/jsonrequired

The rating result to be created for a conversation

ratingResultCsat (object) or Nps (object) or ThumbsUpOrDown (object)(SubmittedRatingResult)required
One of:
ratingResult.​valueinteger(int32)required

Numeric value between 1 and 5 representing the customer's satisfaction level.

commentstring
submittedAtstring(date-time)
userIdstringDeprecated

The userId property is no longer used so it's made optional to keep backwards compatibility. A null value can be provided instead of an actual ID.

curl -i -X POST \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations/{conversationId}/ratings/{ratingId}/submit' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "d3cf6f15-1497-4e71-92f2-9b3b228352bd",
    "ratingResult": {
      "value": 4,
      "_type": "Csat"
    },
    "comment": "Best customer service ever!",
    "submittedAt": "2024-03-11T16:39:30Z"
  }'

Responses

The created conversation rating result

Bodyapplication/json
dataobject(RatingResult)required
data.​ratingIdstringrequired
data.​userIdstring
data.​ratingResultCsat (object) or Nps (object) or ThumbsUpOrDown (object)(SubmittedRatingResult)required
One of:
data.​ratingResult.​valueinteger(int32)required

Numeric value between 1 and 5 representing the customer's satisfaction level.

data.​commentstring
data.​submittedAtstring(date-time)
Response
application/json
{
  "data": {
    "ratingId": "33cf4e5e-9ce9-461c-b668-be9b712b717c",
    "userId": "4c5f7efa-0822-4b75-bdf5-907fa7336e0c",
    "ratingResult": { … },
    "comment": "Excellent customer service!",
    "submittedAt": "2024-03-11T16:39:30Z"
  }
}

Create conversation rating offer

Request

Create a rating offer for a specific conversation.

Security
ApiKeyAuth
Path
conversationIdinteger(int64)required
Bodyapplication/jsonrequired

The rating offer to be created for a conversation

userIdstringrequired
agentIdstringrequired

Please note that providing agentId that is not part of the conversation may skew metrics in Intelligence

ratingTypestringrequired

The type of numeric rating. E.g.: 'Csat', 'ThumbsUpOrDown', 'Nps'.

offeredAtstring(date-time)
curl -i -X POST \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations/{conversationId}/ratings/offer' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "b0323b42-c428-4afa-970e-20bf5bdeeec4",
    "agentId": "eeb3bbe5-0355-4ac1-8af5-20d42a3db24b",
    "ratingType": "Csat",
    "offeredAt": "2024-03-11T16:39:30Z"
  }'

Responses

The created conversation rating offer

Bodyapplication/json
dataobject(RatingOffer)required
data.​idstringrequired
data.​userIdstringrequired
data.​agentIdstringrequired
data.​ratingTypestringrequired

values: [Csat, Nps, ThumbsUpOrDown]

data.​offeredAtstring(date-time)
Response
application/json
{
  "data": {
    "id": "2f0122db-0824-44d7-b39a-e1f722b8c38c",
    "userId": "7a65c963-b3ca-4bd4-996e-bdbcaa620219",
    "agentId": "db7f0b41-b779-4726-a673-07b2a59a550d",
    "ratingType": "Csat",
    "offeredAt": "2024-03-11T16:39:30Z"
  }
}

Create conversation

Request

Create a conversation. For inbound messages the author is assumed to be the requester of the conversation (end user). For outbound messages the author is specified using the agentId field.

Security
ApiKeyAuth
Bodyapplication/jsonrequired

The conversation to create

One of:
requesterIdstring(uuid)required
directionstringrequired

values: [Inbound, Outbound]

contactEndpointIdstringrequired
queueIdstring(uuid)required
curl -i -X POST \
  https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "requesterId": "9c2a2cce-699f-4a72-89d9-fda5bc8dec8b",
    "emailIntegrationId": "my-integration@email.dixa.io",
    "subject": "order #123",
    "message": {
      "content": {
        "value": "My order hasn'\''t shipped",
        "_type": "Text"
      },
      "attachments": [],
      "_type": "Inbound"
    },
    "language": "en",
    "_type": "Email"
  }'

Responses

The id of the created conversation

Bodyapplication/json
dataobject(ConversationResponse)required
data.​idinteger(int64)required
Response
application/json
{
  "data": {
    "id": 100
  }
}

Import conversation

Request

Import a previously created conversation into Dixa. For inbound messages the author is assumed to be the requester of the conversation (end user), unless the specific channel supports overriding the message author through its attributes. For outbound messages the author is specified using the agentId field.

Security
ApiKeyAuth
Bodyapplication/jsonrequired

The type of conversation to import

genericChannelNamestringrequired

The conversation channel. Currently supported values are 'email' and 'widgetchat'. See payload examples for each case.

requesterIdstring(uuid)required
requesterConnectionStatusstring

values: [Connected, Disconnected]

directionstringrequired

values: [Inbound, Outbound]

messagesArray of InboundImport (object) or OutboundImport (object)(ImportMessageInput)
createdAtstring(date-time)required
assignmentobject(Assignment)
externalIdstring
closingobject(Closing)

Triggers the closing of the conversation

attributesany

A set of dynamic attributes that are specific to the conversation channel, but not limited to it. See channel specific examples for your use case.

curl -i -X POST \
  https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations/import \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "genericChannelName": "MyCustomChat",
    "requesterId": "9c2a2cce-699f-4a72-89d9-fda5bc8dec8b",
    "requesterConnectionStatus": "Connected",
    "direction": "Inbound",
    "messages": [
      {
        "content": {
          "value": "My order hasn'\''t shipped",
          "_type": "Text"
        },
        "attachments": [],
        "createdAt": "2021-12-01T13:00:00.003Z",
        "_type": "InboundImport"
      },
      {
        "content": {
          "value": "Our bad, sorry",
          "_type": "Text"
        },
        "agentId": "cd4ceb58-bb3a-443c-9cd8-4f088feafe5b",
        "attachments": [
          {
            "url": "https://en.wikipedia.org/wiki/Shipwreck#/media/File:Titanic_wreck_bow.jpg",
            "prettyName": "shipwreck"
          }
        ],
        "createdAt": "2021-12-01T14:00:00.004Z",
        "_type": "OutboundImport"
      }
    ],
    "createdAt": "2021-12-01T11:00:00.001Z",
    "assignment": {
      "agentId": "cd4ceb58-bb3a-443c-9cd8-4f088feafe5b",
      "assignedAt": "2021-12-01T12:00:00.002Z"
    },
    "closing": {
      "closedAt": "2021-12-01T15:00:00.005Z",
      "closedBy": "cd4ceb58-bb3a-443c-9cd8-4f088feafe5b"
    },
    "_type": "GenericConversationImport"
  }'

Responses

The id of the imported conversation

Bodyapplication/json
dataobject(ImportConversationResponse)required
data.​idinteger(int64)required

The id of the newly imported conversation

data.​partialErrorsArray of objects(PartialError)

List of errors that do not prevent the conversation from being created

Response
application/json
{
  "data": {
    "id": 100,
    "partialErrors": [ … ]
  }
}

Claim conversation

Request

Claim a conversation for a given agent. To avoid taking over assigned conversations, set the force paremeter to false

Security
ApiKeyAuth
Path
conversationIdinteger(int64)required
Bodyapplication/jsonrequired
agentIdstring(uuid)required

The id of the agent who is claiming the conversation

forceboolean

Set as false to avoid taking over the conversation if it is already assigned to an agent

curl -i -X PUT \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/conversations/{conversationId}/claim' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "5a556159-9c21-4f3e-a44f-d323deb80d16",
    "force": false
  }'

Responses

The conversation was successfully claimed

Response
No content

Get queue availability

Request

Get availability of supported channels for a given queue. Currently supported channels are adachat, kindlychat, digitalgeniuschat.

Security
ApiKeyAuth
Path
queueIdstring(uuid)required
curl -i -X GET \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/queues/{queueId}/availability' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

The availability of supported channels for a given queue

Bodyapplication/json
dataArray of Failure (object) or Success (object)(ChannelAvailabilityOutcome)
Response
application/json
{
  "data": [
    { … },
    { … }
  ]
}

Get the position of the conversation in its current queue

Request

Get the approximate position of a given conversation in its current queue.

Security
ApiKeyAuth
Path
csidinteger(int64)required
curl -i -X GET \
  'https://docs.dixa.io/_mock/openapi/dixa-api/v1/v1/queues/conversation-position/{csid}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

The position of the conversation in the queue

Bodyapplication/json
dataobject(QueuedConversation)required
data.​positioninteger(int32)

Approximate position of the conversation in the current queue

data.​queuedAtstring(date-time)required
Response
application/json
{
  "data": {
    "position": 10,
    "queuedAt": "2021-12-01T13:00:00.003Z"
  }
}

Anonymization

Operations

Custom Attributes

Operations

Teams

Operations

Conversations

Operations

Messages

Operations

Internal Notes

Operations

Ratings

Operations

Tags

Operations

Queues

Operations

Contact Endpoints

Operations

Webhooks

Operations

Templates

Operations

Business Hours

Operations

Knowledge

Operations

Organization

Operations