Chatbots
Create an end user.
ApiKeyAuth organization.memberAuthorization<token>Scope: organization.member
The end user's details
application/json- body
displayName?stringThe contact's display name
email?stringThe contact's primary email address
phoneNumber?stringThe contact's primary phone number
additionalEmails?array<string>Additional email addresses for the contact
additionalPhoneNumbers?array<string>Additional phone numbers for the contact
firstName?stringThe contact's first name
lastName?stringThe contact's last name
middleNames?array<string>The contact's middle names
avatarUrl?stringThe url from which to load the contact's avatar
externalId?stringCustom external identifier for the contact
The created end user
application/json- response
data*curl -X POST 'https://dev.dixa.io/v1/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"}'Get an end user by id.
ApiKeyAuthAuthorization<token>userId*stringThe end user id
uuidThe end user
application/json- response
data*curl -X GET 'https://dev.dixa.io/v1/endusers/{userId}' \ -H 'Authorization: <API token>'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
ApiKeyAuthAuthorization<token>userId*stringuuidpageLimit?integerMaximum number of results per page. May be used in combination with pageKey to change the number of results in between page requests.
int32pageKey?stringBase64 encoded form of pagination query parameters. Do not try to construct or change programmatically as the internal structure may change without notice.
The list of conversations requested by an EndUser
application/json- response
data?array<||||||||||>meta?curl -X GET 'https://dev.dixa.io/v1/endusers/{userId}/conversations' \ -H 'Authorization: <API token>'Mark a conversation as closed by providing its id.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64An optional agent/admin to close the conversation
application/json- body
userId?stringuuidThe conversation was successfully closed
curl -X PUT 'https://dev.dixa.io/v1/conversations/{conversationId}/close' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "userId": "5a556159-9c21-4f3e-a44f-d323deb80d16"}'Empty
Follow up a conversation by providing its id and expiration timestamp.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64A request to followup the conversation
application/json- body
timestamp*stringA timestamp for when the followup should expire
date-timeuserId?stringAn optional agent/admin to followup the conversation
uuidThe conversation was successfully followed up
curl -X PUT 'https://dev.dixa.io/v1/conversations/{conversationId}/followup' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "timestamp": "2025-01-08T08:31:25Z", "userId": "5a556159-9c21-4f3e-a44f-d323deb80d16"}'Empty
Transfer a conversation to a target queue.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64Transfer conversation request
application/json- body
queueId*stringThe target queue for the conversation transfer
uuiduserId?stringAn optional agent/admin to originate the transfer of the conversation
uuidThe conversation was successfully transferred to the target queue
curl -X PUT 'https://dev.dixa.io/v1/conversations/{conversationId}/transfer/queue' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "queueId": "92f8d193-b26f-4a62-86a3-bb03ee0915e9", "userId": "a53b25da-f676-4c52-acac-58c9280aa23d"}'Empty
Create a rating result for a specific conversation.
ApiKeyAuth conversation.satisfactionAuthorization<token>Scope: conversation.satisfaction
conversationId*integerint64ratingId*stringThe ratingId parameter has to be the ID of the offer created via invoking the /conversations/{conversationId}/ratings/offer endpoint.
The rating result to be created for a conversation
application/json- body
userId?stringDeprecatedThe 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.
ratingResult*||comment?stringsubmittedAt?stringdate-timeThe created conversation rating result
application/json- response
data*curl -X POST 'https://dev.dixa.io/v1/conversations/{conversationId}/ratings/{ratingId}/submit' \ -H 'Authorization: <API token>' \ -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"}'Create a rating offer for a specific conversation.
ApiKeyAuth conversation.satisfactionAuthorization<token>Scope: conversation.satisfaction
conversationId*integerint64The rating offer to be created for a conversation
application/json- body
userId*stringagentId*stringPlease note that providing agentId that is not part of the conversation may skew metrics in Intelligence
ratingType*stringThe type of numeric rating. E.g.: 'Csat', 'ThumbsUpOrDown', 'Nps'.
offeredAt?stringdate-timeThe created conversation rating offer
application/json- response
data*curl -X POST 'https://dev.dixa.io/v1/conversations/{conversationId}/ratings/offer' \ -H 'Authorization: <API token>' \ -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"}'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.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
The conversation to create
application/json- body
requesterId*stringuuiddirection*stringvalues: [Inbound, Outbound]
contactEndpointId*stringqueueId*stringuuidThe id of the created conversation
application/json- response
data*curl -X POST 'https://dev.dixa.io/v1/conversations' \ -H 'Authorization: <API token>' \ -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"}'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.
ApiKeyAuth conversation.importAuthorization<token>Scope: conversation.import
The type of conversation to import
application/json- body
genericChannelName*stringThe conversation channel. Currently supported values are 'email' and 'genericapimessaging'. See payload examples for each case.
requesterId*stringuuidrequesterConnectionStatus?stringvalues: [Connected, Disconnected]
direction*stringvalues: [Inbound, Outbound]
messages?array<|>createdAt*stringdate-timeassignment?externalId?stringclosing?Triggers the closing of the conversation
attributes?unknownA set of dynamic attributes that are specific to the conversation channel, but not limited to it. See channel specific examples for your use case.
The id of the imported conversation
application/json- response
data*curl -X POST 'https://dev.dixa.io/v1/conversations/import' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "genericChannelName": "genericapimessaging", "requesterId": "9c2a2cce-699f-4a72-89d9-fda5bc8dec8b", "requesterConnectionStatus": "Connected", "direction": "Inbound", "messages": [ { "content": { "value": "Hi, I need help with my order", "_type": "Text" }, "attachments": [], "createdAt": "2021-12-01T13:00:00.003Z", "_type": "InboundImport" }, { "content": { "value": "Sure — what seems to be the problem?", "_type": "Text" }, "agentId": "cd4ceb58-bb3a-443c-9cd8-4f088feafe5b", "attachments": [], "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" }, "_type": "GenericConversationImport"}'Claim a conversation for a given agent. To avoid taking over assigned conversations, set the force paremeter to false
ApiKeyAuth conversation.claimAuthorization<token>Scope: conversation.claim
conversationId*integerint64application/json- body
agentId*stringThe id of the agent who is claiming the conversation
uuidforce?booleanSet as false to avoid taking over the conversation if it is already assigned to an agent
The conversation was successfully claimed
curl -X PUT 'https://dev.dixa.io/v1/conversations/{conversationId}/claim' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "agentId": "5a556159-9c21-4f3e-a44f-d323deb80d16", "force": false}'Empty
Get availability of supported channels for a given queue. Currently supported channels are adachat, kindlychat, digitalgeniuschat, genericapimessaging.
ApiKeyAuthAuthorization<token>queueId*stringuuidThe availability of supported channels for a given queue
application/json- response
data?array<|>curl -X GET 'https://dev.dixa.io/v1/queues/{queueId}/availability' \ -H 'Authorization: <API token>'Get the approximate position of a given conversation in its current queue.
ApiKeyAuthAuthorization<token>csid*integerint64The position of the conversation in the queue
application/json- response
data*curl -X GET 'https://dev.dixa.io/v1/queues/conversation-position/{csid}' \ -H 'Authorization: <API token>'