Conversations
Request the anonymization of a conversation.
ApiKeyAuth anonymizationAuthorization<token>Scope: anonymization
conversationId*integerthe id of the conversation to anonymize
int64force?booleanWhether to force close the conversation if it is found in a non closed state.
falseThe conversation's anonymization request status
application/json- response
data*curl -X PATCH 'https://dev.dixa.io/beta/conversations/{conversationId}/anonymize' \ -H 'Authorization: <API token>'Request the anonymization of a single message in a conversation.
ApiKeyAuth anonymizationAuthorization<token>Scope: anonymization
conversationId*integerthe id of the conversation in which the message belongs
int64messageId*stringthe id of the message to anonymize
uuidThe message's anonymization request status
application/json- response
data*curl -X PATCH 'https://dev.dixa.io/beta/conversations/{conversationId}/messages/{messageId}/anonymize' \ -H 'Authorization: <API token>'Mark a conversation as closed by providing its id.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64Specify the acting user for the close
application/json- body
userId?stringAn optional agent/admin/AI agent to close the conversation. If not provided, the System User will be used.
uuidThe conversation was successfully closed
curl -X PUT 'https://dev.dixa.io/beta/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*integerint64Specify the follow-up timestamp and acting user
application/json- body
timestamp*stringA timestamp for when the followup should expire
date-timeuserId?stringAn optional agent/admin/AI agent to followup the conversation. If not provided, the System User will be used.
uuidThe conversation was successfully followed up
curl -X PUT 'https://dev.dixa.io/beta/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
Reopen a conversation and offer it in the same queue. Falls back to the default organization queue if the conversation has no target queue.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64Specify the acting user for the reopen
application/json- body
userId?stringAn optional agent/admin/AI agent to reopen the conversation. If not provided, the System User will be used.
uuidThe conversation was successfully reopened and offered in the same queue
curl -X PUT 'https://dev.dixa.io/beta/conversations/{conversationId}/reopen' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "userId": "a53b25da-f676-4c52-acac-58c9280aa23d"}'Empty
Transfer a conversation to a target queue.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64Specify the target queue and acting user
application/json- body
queueId*stringThe target queue for the conversation transfer
uuiduserId?stringAn optional agent/admin/AI agent to originate the transfer of the conversation. If not provided, the System User will be used.
uuidThe conversation was successfully transferred to the target queue
curl -X PUT 'https://dev.dixa.io/beta/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 internal notes in a conversation by providing the conversation id.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64The list of internal notes to create for a conversation
application/json- body
data?array<>The created internal notes
application/json- response
data?array<|>curl -X POST 'https://dev.dixa.io/beta/conversations/{conversationId}/notes/bulk' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "data": [ { "message": "A sample note", "agentId": "a53b25da-f676-4c52-acac-58c9280aa23d", "createdAt": "2021-12-01T12:46:36.581Z[GMT]" }, { "message": "Another sample note" } ]}'Get all internal notes for a particular conversation by providing the conversation id.
ApiKeyAuthAuthorization<token>conversationId*integerint64List of internal notes for a conversation sorted from oldest to newest
application/json- response
data?array<>curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}/notes' \ -H 'Authorization: <API token>'Create an internal note in a conversation by providing the conversation id.
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64The internal note to create for a conversation
application/json- body
message*stringagentId?stringuuidcreatedAt?stringdate-timeThe created internal note
application/json- response
data*curl -X POST 'https://dev.dixa.io/beta/conversations/{conversationId}/notes' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "message": "A sample note", "agentId": "a53b25da-f676-4c52-acac-58c9280aa23d", "createdAt": "2021-12-01T12:46:36.581Z[GMT]"}'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/beta/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?stringIf userId is not provided, the conversation requester will be picked.
agentId?stringIf an agentId is not provided, the agent that is most likely to be the target will be picked. Please note that providing an 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/beta/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"}'List rating
DeprecatedDeprecated rating endpoint. Use '/ratings'.
ApiKeyAuthAuthorization<token>conversationId*integerint64List of ratings for a conversation
application/json- response
data?array<>curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}/rating' \ -H 'Authorization: <API token>'Lists latest ratings statuses for a particular conversation by providing the conversation ID. For surveys with multiple questions, rating status will be reported for each individual question of the survey. For example, a response for a 3 question survey that was answered will be 3 elements with status "Rated". Additionally, a multiple question survey can be partially answered, therefore a response of such case will be a mix of "Offered" and "Rated" statuses. Note that the IDs of multiple questions response elements will be the same, because they are part of the same survey.
ApiKeyAuthAuthorization<token>conversationId*integerint64List of ratings for a conversation
application/json- response
data?array<>curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}/ratings' \ -H 'Authorization: <API token>'List all activity logs for an organization.
ApiKeyAuthAuthorization<token>pageLimit?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.
fromDatetime?stringStarting date-time filter with ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
date-timetoDatetime?stringEnding date-time filter with ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
date-timeThe full list of activity logs for an organization with pagination
application/json- response
data?array<>meta?curl -X GET 'https://dev.dixa.io/beta/conversations/activitylog' \ -H 'Authorization: <API token>'List all conversations flows in an organization.
ApiKeyAuthAuthorization<token>channel?stringAn optional ConversationChannel can be specified to filter the flows. If not provided, the default channel is PstnPhone. Possible values: [WhatsApp, Voicemail, WidgetChat, FacebookMessenger, Email, ContactForm, Callback, PstnPhone, Messenger]
The list of conversation flows
application/json- response
data?array<>curl -X GET 'https://dev.dixa.io/beta/conversations/flows' \ -H 'Authorization: <API token>'Tag a conversation. You may only use active tags to tag conversations.
ApiKeyAuth conversation.tagAuthorization<token>Scope: conversation.tag
conversationId*integerint64tagId*stringuuidThe conversation was successfully tagged
curl -X PUT 'https://dev.dixa.io/beta/conversations/{conversationId}/tags/{tagId}' \ -H 'Authorization: <API token>'Empty
Untag a conversation. You may remove active or inactive tags from a conversation.
ApiKeyAuth conversation.tagAuthorization<token>Scope: conversation.tag
conversationId*integerint64tagId*stringuuidThe conversation was successfully untagged
curl -X DELETE 'https://dev.dixa.io/beta/conversations/{conversationId}/tags/{tagId}' \ -H 'Authorization: <API token>'Empty
Initiate bulk tag of a conversation and process it asynchronously. If a tag with corresponding name does not exist it will be created.
ApiKeyAuth conversation.tagAuthorization<token>Scope: conversation.tag
conversationId*integerint64The list of tags to add to a conversation
application/json- body
data?array<>The conversation bulk tag was initiated
curl -X POST 'https://dev.dixa.io/beta/conversations/{conversationId}/tags/bulk' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "data": [ { "name": "Example #1" }, { "name": "Example #2" } ]}'Empty
Get the tags for a particular conversation by providing the conversation id.
ApiKeyAuthAuthorization<token>conversationId*integerint64List of tags for a conversation
application/json- response
data?array<>curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}/tags' \ -H 'Authorization: <API token>'Get all messages for a particular conversation by providing the conversation id. Note that messages in ContactForm conversations can have attributes of "_type": "EmailAttributes" if they are created through a webform, or "_type": "ContactFormAttributes" when created through a chat widget.
ApiKeyAuthAuthorization<token>conversationId*integerint64List of messages for a conversation sorted from oldest to newest
application/json- response
data?array<>curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}/messages' \ -H 'Authorization: <API token>'Add a message to 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.
If attachments are added to the message, they will be copied and stored in Dixa.
Content in outbound message is required except for Whatsapp messages.
Supported channels are Chat, Messenger, Contact Form, Email, Sms (outbound only), Whatsapp (outbound and Markdown only).
Supported Markdown syntax for Markdown content: bold **text**, italic *text*, bold & italic ***text***, strikethrough ~text~, blockquote > Quoted text. \n Message about quoted text, ordered list List:\n1. Item\n2. Item\n3. Item, unordered list List:\n* Item\n* Item\n* Item, inline code This is code``.
Whatsapp channel:
Only one attachment is allowed per WhatsApp message.
Supports adding a message with attachment only (no content).
Supports the following file types for attachments: .jpg, .jpeg, .png, .pdf, .doc, .docx, .pptx, .xlsx
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64The message to be added to a conversation
application/json- body
Only Outbound messages are supported for Sms and Whatsapp.
content*||attachments?array<>integrationEmail?stringInternal email address registered for the integration with format: <email-address>@email.dixa.io
externalId?stringClient generated identifier for external reference
The added message
application/json- response
data*curl -X POST 'https://dev.dixa.io/beta/conversations/{conversationId}/messages' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "content": { "value": "I need some help!", "_type": "Html" }, "attachments": [ { "url": "http://attachment.url", "prettyName": "Filename" } ], "_type": "Inbound"}'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*stringThe end user's userId
uuiddirection*stringvalues: [Inbound, Outbound]
contactEndpointId*stringqueueId*stringuuidThe id of the created conversation
application/json- response
data*curl -X POST 'https://dev.dixa.io/beta/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/beta/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"}'Patch custom attributes of a conversation
ApiKeyAuth conversation.custom_attributeAuthorization<token>Scope: conversation.custom_attribute
conversationId*integerint64The custom attributes of an conversation to be patched. This should map the custom attribute id to the desired attribute value. Format: Map[UUID, Option[AttributeValue].
application/json- 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
The patched conversation attributes
application/json- response
data?array<>curl -X PATCH 'https://dev.dixa.io/beta/conversations/{conversationId}/custom-attributes' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "2f5515b6-7e98-4f4d-9010-bfd2a27d4f35": "012345", "e14708a6-eed9-495c-9d88-c72331e9e247": [ "str1", "str2" ]}'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/beta/conversations/{conversationId}/claim' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "agentId": "5a556159-9c21-4f3e-a44f-d323deb80d16", "force": false}'Empty
Get the activity log for a conversation by providing the conversation id.
ApiKeyAuthAuthorization<token>conversationId*integerint64Activity log entries for a conversation
application/json- response
data?array<>curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}/activitylog' \ -H 'Authorization: <API token>'Get a conversation by id.
ApiKeyAuthAuthorization<token>conversationId*integerint64The conversation
application/json- response
data*||||||||||curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}' \ -H 'Authorization: <API token>'Links the specified conversation to a parent conversation with the specified link type.
Limitations:
- Maximum of 100 child conversations per parent
- Only 1 parent per child conversation
- A child conversation cannot have its own child conversations
ApiKeyAuth conversation.replyAuthorization<token>Scope: conversation.reply
conversationId*integerint64The parent conversation ID and link type
application/json- body
parentId*integerint64linkType*stringvalues: [Related, SideConversation]
curl -X PUT 'https://dev.dixa.io/beta/conversations/{conversationId}/link' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "parentId": 12345, "linkType": "SideConversation"}'Empty
Lists all linked child conversations for the given conversation ID, such as transcripts and side conversations.
ApiKeyAuthAuthorization<token>conversationId*integerint64The list of conversations requested by an EndUser
application/json- response
data?array<||||||||||>curl -X GET 'https://dev.dixa.io/beta/conversations/{conversationId}/linked' \ -H 'Authorization: <API token>'Search conversations
DeprecatedNOTE: This endpoint is deprecated and is replaced with POST /search/conversations. Search for conversations containing a particular text.
ApiKeyAuthAuthorization<token>pageLimit?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.
query*stringThe text by which to search conversations
1 <= lengthexactMatch?booleanReturn only exact matches. This value is false by default.
The search results for the searched parameters
application/json- response
data?array<>meta?curl -X GET 'https://dev.dixa.io/beta/search/conversations?query=cancel+my+order' \ -H 'Authorization: <API token>'Search for conversations containing a particular text or by filter or combine them both
ApiKeyAuthAuthorization<token>pageLimit?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 filters to apply to the search
application/json- body
query?filters?The search results for the searched parameters
application/json- response
data?array<>meta?curl -X POST 'https://dev.dixa.io/beta/search/conversations' \ -H 'Authorization: <API token>' \ -H 'Content-Type: application/json' \ -d '{ "filters": { "strategy": "All", "conditions": [ { "field": { "operator": { "values": [ "177e7564-6434-4177-a25a-8530089196ad", "7729e7564-9876-a637-b46b-8530038196b3" ], "_type": "IncludesOne" }, "_type": "TagId" } } ] }}'