Dixa
    Nothing Found

Conversations

Add internal note

Create an internal note in a conversation by providing the conversation id.

SecurityApiKeyAuth
Request
path Parameters
conversationId
required
integer <int64>
Request Body schema: application/json
required

The internal note to create for a conversation

agentId
string <uuid>
createdAt
string <date-time>
message
required
string
Responses
200

The created internal note

400

Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, Agent was not found, Invalid date format

404

An entity in this request could not be found

500

Internal failure during request processing

post/v1/conversations/{conversationId}/notes
Request samples
application/json
{
  • "message": "A sample note",
  • "agentId": "a53b25da-f676-4c52-acac-58c9280aa23d",
  • "createdAt": "2021-12-01T12:46:36.581Z[GMT]"
}
Response samples
application/json
{
  • "data": {
    • "id": "eb31acbb-13f9-4ce7-abd3-44dd86266741",
    • "authorId": "5e8a300e-787e-47cd-af53-fc1ccc37933d",
    • "createdAt": "2021-12-01T12:46:36.581Z[GMT]",
    • "csid": 9456,
    • "message": "A sample note"
    }
}

Add internal notes

Create internal notes in a conversation by providing the conversation id.

SecurityApiKeyAuth
Request
path Parameters
conversationId
required
integer <int64>
Request Body schema: application/json
required

The list of internal notes to create for a conversation

Array of objects (CreateInternalNoteInput)
Responses
200

The created internal notes

400

Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body

404

An entity in this request could not be found

500

Internal failure during request processing

post/v1/conversations/{conversationId}/notes/bulk
Request samples
application/json
{
  • "data": [
    • {
      • "message": "A sample note",
      • "agentId": "a53b25da-f676-4c52-acac-58c9280aa23d",
      • "createdAt": "2021-12-01T12:46:36.581Z[GMT]"
      },
    • {
      • "message": "Another sample note"
      }
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "data": {
        • "id": "eb31acbb-13f9-4ce7-abd3-44dd86266741",
        • "authorId": "5e8a300e-787e-47cd-af53-fc1ccc37933d",
        • "createdAt": "2021-12-01T12:46:36.581Z[GMT]",
        • "csid": 9456,
        • "message": "A sample note"
        },
      • "_type": "BulkActionSuccess"
      },
    • {
      • "error": {
        • "message": "An agent with id:... cannot be found in org."
        },
      • "_type": "BulkActionFailure"
      }
    ]
}

Add message

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.
Supported channels are Chat, Messenger, Contact Form, Email, Sms(outbound only).

SecurityApiKeyAuth
Request
path Parameters
conversationId
required
integer <int64>
Request Body schema: application/json
required

The message to be added to a conversation

One of:

For Sms only Outbound messages are supported.

Array of objects (File)
required
Html (object) or Text (object) (Content)
externalId
string

Client generated identifier for external reference

integrationEmail
string

Internal email address registered for the integration with format: <email-address>@email.dixa.io

Responses
200

The added message

400

Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, Invalid input for Message, Failure to download attachment, Duplicate externalId, Unsupported ConversationChannel

404

An entity in this request could not be found

500

Internal failure during request processing

post/v1/conversations/{conversationId}/messages
Request samples
application/json
{
  • "content": {
    • "value": "I need some help!",
    • "_type": "Html"
    },
  • "attachments": [],
  • "_type": "Inbound"
}
Response samples
application/json
{
  • "data": {
    • "content": {
      • "value": "An amazing message",
      • "_type": "Html"
      },
    • "direction": "Outbound",
    • "authorId": "bac5a02c-15b3-44da-ae1e-ab7b9db4aa89",
    • "messageId": "87bac308-e49f-4134-84cc-96b868f1e1e4",
    • "createdAt": "2021-06-09T08:18:37.284Z"
    }
}

Anonymize conversation

Request the anonymization of a conversation.

SecurityApiKeyAuth
Request
path Parameters
conversationId
required
integer <int64>

the id of the conversation to anonymize

query Parameters
force
boolean
Default: false

Whether to force close the conversation if it is found in a non closed state.

Responses
202

The conversation's anonymization request status

400

Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: query parameter force

404
409
500
patch/v1/conversations/{conversationId}/anonymize
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "87bac308-e49f-4134-84cc-96b868f1e1e4",
    • "entityType": "ConversationAnonymizationType",
    • "_type": "Conversation",
    • "initiatedAt": "2021-12-01T12:46:36.581Z[GMT]",
    • "targetEntityId": "10749",
    • "requestedBy": "b165fdaa-51d6-44b0-bfcd-5f431d623fa7"
    }
}
Anonymize message
Request the anonymization of a single message in a conversation.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
the id of the conversation in which the message belongs


 
messageId
required
string <uuid> 
the id of the message to anonymize


 
Responses 
202
The message's anonymization request status


400
Invalid value for: path parameter conversationId, Invalid value for: path parameter messageId, Invalid value extracted from request context


404
409
500
patch/v1/conversations/{conversationId}/messages/{messageId}/anonymize
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "b165fdaa-51d6-44b0-bfcd-5f431d623fa7",
    • "entityType": "MessageAnonymizationType",
    • "_type": "Message",
    • "initiatedAt": "2021-12-01T12:46:36.581Z[GMT]",
    • "targetEntityId": "10749_1b9adc49-62f7-4056-a9c0-c18c1f25afdb",
    • "requestedBy": "4c7af391-b7fd-4560-9d82-b3464eef8776"
    }
}
Bulk tag conversation
Initiate bulk tag of a conversation and process it asynchronously. If a tag with corresponding name does not exist it will be created.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
required
The list of tags to add to a conversation


Array of objects (TagConversationInput) 
 
Responses 
202
The conversation bulk tag was initiated


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body


404
An entity in this request could not be found


500
Internal failure during request processing


post/v1/conversations/{conversationId}/tags/bulk
Request samples 
application/json
{
  • "data": [
    • {
      • "name": "Example #1"
      },
    • {
      • "name": "Example #2"
      }
    ]
}
Response samples 
application/json
{
  • "message": "Invalid value in request"
}
Claim conversation
Claim a conversation for a given agent. To avoid taking over assigned conversations, set the force paremeter to false


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
required
agentId
required
string <uuid> 
The id of the agent who is claiming the conversation


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


 
Responses 
204
The conversation was successfully claimed


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body


404
An entity in this request could not be found


500
Internal failure during request processing


put/v1/conversations/{conversationId}/claim
Request samples 
application/json
{
  • "agentId": "5a556159-9c21-4f3e-a44f-d323deb80d16",
  • "force": false
}
Response samples 
application/json
{
  • "message": "Invalid value in request"
}
Close conversation
Mark a conversation as closed by providing its id.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
optional
An optional agent/admin to close the conversation


userId
string <uuid> 
 
Responses 
204
The conversation was successfully closed


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, User not found, User is not agent/admin


404
An entity in this request could not be found


put/v1/conversations/{conversationId}/close
Request samples 
application/json
{
  • "userId": "5a556159-9c21-4f3e-a44f-d323deb80d16"
}
Response samples 
application/json
{
  • "message": "Decoding failure in request"
}
Create conversation
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.


SecurityApiKeyAuth 
Request 
Request Body schema: application/json
required
The conversation to create


One of:
contactEndpointId
required
string
 
direction
required
string
values: [Inbound, Outbound]


 
queueId
required
string <uuid> 
 
requesterId
required
string <uuid> 
 
Responses 
201
The id of the created conversation


400
Invalid value extracted from request context, Invalid value for: body, Invalid input for Message, Failure to download attachment, Duplicate externalId, Unsupported ConversationChannel


404
An entity in this request could not be found


500
Internal failure during request processing


post/v1/conversations
Request samples 
application/json
{
  • "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"
}
Response samples 
application/json
{
  • "data": {
    • "id": 100
    }
}
Create conversation rating offer
Create a rating offer for a specific conversation.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
required
The rating offer to be created for a conversation


agentId
required
string
 
offeredAt
string <date-time> 
 
ratingType
required
string
The type of numeric rating. E.g.: 'Csat', 'ThumbsUpOrDown'.


 
userId
required
string
 
Responses 
201
The created conversation rating offer


400
500
Internal failure during request processing


post/v1/conversations/{conversationId}/ratings/offer
Request samples 
application/json
{
  • "userId": "b0323b42-c428-4afa-970e-20bf5bdeeec4",
  • "agentId": "eeb3bbe5-0355-4ac1-8af5-20d42a3db24b",
  • "ratingType": "Csat",
  • "offeredAt": "2024-03-11T16:39:30Z"
}
Response samples 
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 rating result
Create a rating result for a specific conversation.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
ratingId
required
string
 
Request Body schema: application/json
required
The rating result to be created for a conversation


comment
string
 
required
Csat (object) or ThumbsUpOrDown (object) (SubmittedRatingResult) 
 
submittedAt
string <date-time> 
 
userId
required
string
 
Responses 
201
The created conversation rating result


400
500
Internal failure during request processing


post/v1/conversations/{conversationId}/ratings/{ratingId}/submit
Request samples 
application/json
{
  • "userId": "d3cf6f15-1497-4e71-92f2-9b3b228352bd",
  • "ratingResult": {
    • "value": 4,
    • "_type": "Csat"
    },
  • "comment": "Best customer service ever!",
  • "submittedAt": "2024-03-11T16:39:30Z"
}
Response samples 
application/json
{
  • "data": {
    • "ratingId": "33cf4e5e-9ce9-461c-b668-be9b712b717c",
    • "userId": "4c5f7efa-0822-4b75-bdf5-907fa7336e0c",
    • "ratingResult": {
      • "value": 5,
      • "_type": "Csat"
      },
    • "comment": "Excellent customer service!",
    • "submittedAt": "2024-03-11T16:39:30Z"
    }
}
Followup conversation
Follow up a conversation by providing its id and expiration timestamp.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
required
A request to followup the conversation


timestamp
required
string <date-time> 
A timestamp for when the followup should expire


 
userId
string <uuid> 
An optional agent/admin to followup the conversation


 
Responses 
204
The conversation was successfully followed up


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, User not found, User is not agent/admin


404
An entity in this request could not be found


put/v1/conversations/{conversationId}/followup
Request samples 
application/json
{
  • "timestamp": "2025-01-08T08:31:25Z",
  • "userId": "5a556159-9c21-4f3e-a44f-d323deb80d16"
}
Response samples 
application/json
{
  • "message": "Decoding failure in request"
}
Get conversation
Get a conversation by id.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
The conversation


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


get/v1/conversations/{conversationId}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": 1,
    • "requesterId": "d58c8b1c-85ad-4678-a6c8-7442945f3836",
    • "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"
      },
    • "customAttributes": [
      • {
        • "id": "e14708a6-eed9-495c-9d88-c72331e9e247",
        • "name": "My Attribute",
        • "identifier": "my_attribute",
        • "value": "My Attribute Value"
        }
      ],
    • "_type": "ChatConversation"
    }
}
Import conversation
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.


SecurityApiKeyAuth 
Request 
Request Body schema: application/json
required
The type of conversation to import


One of:
object (Assignment) 
 
attributes
any
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.


 
object (Closing) 
Triggers the closing of the conversation


 
createdAt
required
string <date-time> 
 
direction
required
string
values: [Inbound, Outbound]


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


 
Array of InboundImport (object) or OutboundImport (object) (ImportMessageInput) 
 
requesterConnectionStatus
string
values: [Connected, Disconnected]


 
requesterId
required
string <uuid> 
 
Responses 
201
The id of the imported conversation


400
Invalid value extracted from request context, Invalid value for: body, Invalid input for Message, Failure to download attachment, Unsupported ConversationChannel, Requester does not exist, Agent does not exist


404
An entity in this request could not be found


500
Internal failure during request processing


post/v1/conversations/import
Request samples 
application/json
{
  • "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"
      },
    • {}
    ],
  • "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"
}
Response samples 
application/json
{
  • "data": {
    • "id": 100,
    • "partialErrors": [
      • {
        • "message": "The conversation could not be assigned"
        },
      • {
        • "message": "Invalid attachment url in message. externalId: 42"
        }
      ]
    }
}
List activity log
Get the activity log for a conversation by providing the conversation id.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
Activity log entries for a conversation


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


500
Internal failure during request processing


get/v1/conversations/{conversationId}/activitylog
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "fca291e5-8670-41bd-b502-842fd9542e27",
      • "conversationId": 1,
      • "activityTimestamp": "2021-12-01T12:46:36.581Z[GMT]",
      • "activityType": "ConversationAssignedActivityType",
      • "_type": "ConversationAssigned",
      • "author": {
        • "id": "a53b25da-f676-4c52-acac-58c9280aa23d",
        • "name": "Dale Cooper",
        • "email": "dc@dixa.com",
        • "phoneNumber": "+4534343434"
        }
      }
    ]
}
List flows
List all conversations flows in an organization.


SecurityApiKeyAuth 
Request 
query Parameters
channel
string
An 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]


 
Responses 
200
The list of conversation flows


400
Invalid value extracted from request context, Invalid value for: query parameter channel


500
Internal failure during request processing


get/v1/conversations/flows
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "d546e9a8-82c2-409f-b688-e9199ea69f83",
      • "name": "Default call flow",
      • "channel": "PstnPhone",
      • "contactEndpointId": "+559912443333"
      }
    ]
}
List internal notes
Get all internal notes for a particular conversation by providing the conversation id.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
List of internal notes for a conversation sorted from oldest to newest


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


get/v1/conversations/{conversationId}/notes
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "3346b99c-8128-4276-ac40-5f30c959e5e7",
      • "authorId": "c68f42a5-1453-497a-940f-ff36ed4f1631",
      • "createdAt": "2021-01-20T09:00:00Z",
      • "csid": 7392,
      • "message": "A note to remember"
      },
    • {
      • "id": "22b8e6b6-4576-4dc0-ab05-60f81e8b0708",
      • "authorId": "124d54bb-92d6-41c9-a675-788d6a8c821e",
      • "createdAt": "2021-01-22T12:00:00Z",
      • "csid": 7392,
      • "message": "A note to forget"
      }
    ]
}
List linked conversations
Lists all linked child conversations for the given conversation ID, such as transcripts and side conversations.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
The list of conversations requested by an EndUser


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


get/v1/conversations/{conversationId}/linked
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 12341,
      • "requesterId": "7bcf1f2d-70c0-4f87-8c5b-bed2c8b247e9",
      • "channel": "WidgetChat",
      • "createdAt": "2022-07-26T12:09:21Z",
      • "direction": "Inbound",
      • "state": "Open",
      • "stateUpdatedAt": "2022-07-26T12:12:53Z",
      • "assignment": {
        • "agentId": "01107a2e-4ff0-4a87-bb48-a19af298394d",
        • "assignedAt": "2022-07-26T12:12:53Z"
        },
      • "queue": {
        • "id": "6b9087b3-9ab7-4af4-936d-3290996faedb",
        • "queuedAt": "2022-07-26T12:09:54Z"
        },
      • "toEmail": "something@email.dixa.com",
      • "fromEmail": "some.one@somewhere.com",
      • "integrationEmail": "something@email.dixa.com",
      • "language": "en",
      • "subject": "Important Request",
      • "link": {
        • "parentId": 1234,
        • "_type": "SideConversation"
        },
      • "_type": "EmailConversation"
      }
    ]
}
List messages
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.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
List of messages for a conversation sorted from oldest to newest


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


404
An entity in this request could not be found


get/v1/conversations/{conversationId}/messages
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "11b95893-0514-4606-a5d8-1880172b3a55",
      • "authorId": "41646d42-edc0-493e-ac7b-814d9ff40a2e",
      • "externalId": "13244",
      • "createdAt": "2021-12-01T12:46:36.581Z[GMT]",
      • "attributes": {}
      }
    ]
}
List organization activity log
List all activity logs for an organization.


SecurityApiKeyAuth 
Request 
query Parameters
fromDatetime
string <date-time> 
Starting date-time filter with ISO 8601 format: yyyy-MM-dd'T'HH:mm:sss'Z'


 
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.


 
toDatetime
string <date-time> 
Ending date-time filter with ISO 8601 format: yyyy-MM-dd'T'HH:mm:sss'Z'


 
Responses 
200
The full list of activity logs for an organization with pagination


400
Invalid value extracted from request context, Invalid value for: query parameter pageLimit, Invalid value for: query parameter pageKey, Invalid value for: query parameter fromDatetime, Invalid value for: query parameter toDatetime, Validation failure when retrieving data


500
Internal failure during request processing


get/v1/conversations/activitylog
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "d85a7bd7-79da-4f10-b021-12e4c2c20024",
      • "conversationId": 1,
      • "activityTimestamp": "2021-12-01T12:46:36.581Z[GMT]",
      • "activityType": "ConversationAssignedActivityType",
      • "_type": "ConversationAssigned",
      • "author": {
        • "id": "a53b25da-f676-4c52-acac-58c9280aa23d",
        • "name": "Dale Cooper",
        • "email": "dc@dixa.com",
        • "phoneNumber": "+4534343434"
        }
      },
    • {
      • "id": "324d0108-31b7-4678-8862-c8780a297f8f",
      • "conversationId": 2,
      • "activityTimestamp": "2021-12-01T12:46:36.581Z[GMT]",
      • "activityType": "ConversationAssignedActivityType",
      • "_type": "ConversationAssigned",
      • "author": {
        • "id": "67ff39b6-b1ee-4d5f-91ee-168d4668c4ba",
        • "name": "Bob Ross",
        • "email": "br@dixa.com",
        • "phoneNumber": "+4532323232"
        }
      }
    ]
}
List ratingDeprecated
Deprecated rating endpoint. Use '/ratings'.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
List of ratings for a conversation


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


get/v1/conversations/{conversationId}/rating
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "33cf4e5e-9ce9-461c-b668-be9b712b717c",
      • "ratingScore": 4,
      • "ratingType": "Csat",
      • "ratingComment": "Super good!",
      • "conversationChannel": "PstnPhone",
      • "agentId": "a53b25da-f676-4c52-acac-58c9280aa23d",
      • "userId": "6d0c5791-e40a-46d4-bba1-1364ce4578ed",
      • "ratingStatus": "Offered",
      • "language": "English",
      • "timestamps": { }
      }
    ]
}
List tags
Get the tags for a particular conversation by providing the conversation id.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
List of tags for a conversation


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


get/v1/conversations/{conversationId}/tags
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "b794a74a-625b-4303-8237-9b11668a9605",
      • "name": "example",
      • "state": "Active"
      },
    • {
      • "id": "b794a74a-625b-4303-8237-9b11668a9605",
      • "name": "example",
      • "state": "Active"
      },
    • {
      • "id": "b794a74a-625b-4303-8237-9b11668a9605",
      • "name": "example",
      • "state": "Active"
      },
    • {
      • "id": "b794a74a-625b-4303-8237-9b11668a9605",
      • "name": "example",
      • "state": "Active"
      }
    ]
}
List the ratings for a conversation
Get the ratings for a particular conversation by providing the conversation id.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Responses 
200
List of ratings for a conversation


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


get/v1/conversations/{conversationId}/ratings
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "33cf4e5e-9ce9-461c-b668-be9b712b717c",
      • "ratingScore": 4,
      • "ratingType": "Csat",
      • "ratingComment": "Super good!",
      • "conversationChannel": "PstnPhone",
      • "agentId": "a53b25da-f676-4c52-acac-58c9280aa23d",
      • "userId": "6d0c5791-e40a-46d4-bba1-1364ce4578ed",
      • "ratingStatus": "Offered",
      • "language": "English",
      • "timestamps": { }
      }
    ]
}
Patch conversation custom attributes
Patch custom attributes of a conversation


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
required
The 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].


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 conversation attributes


400
Invalid value for: path parameter conversationId, 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/conversations/{conversationId}/custom-attributes
Request samples 
application/json
{
  • "2f5515b6-7e98-4f4d-9010-bfd2a27d4f35": "012345",
  • "e14708a6-eed9-495c-9d88-c72331e9e247": [
    • "str1",
    • "str2"
    ]
}
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "2f5515b6-7e98-4f4d-9010-bfd2a27d4f35",
      • "name": "Conversation attribute",
      • "identifier": "conversation_attribute",
      • "value": "012345"
      },
    • {
      • "id": "e14708a6-eed9-495c-9d88-c72331e9e247",
      • "name": "Conversation attribute 2",
      • "identifier": "conversation_attribute_2",
      • "value": [
        • "str1",
        • "str2"
        ]
      }
    ]
}
Reopen conversation
Reopen a conversation and offer it in the same queue. Falls back to the default organization queue if the conversation has no target queue.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
optional
An optional agent/admin to reopen the conversation


userId
string <uuid> 
 
Responses 
204
The conversation was successfully reopened and offered in the same queue


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, User not found, User is not agent/admin


404
An entity in this request could not be found


500
Internal failure during request processing


put/v1/conversations/{conversationId}/reopen
Request samples 
application/json
{
  • "userId": "a53b25da-f676-4c52-acac-58c9280aa23d"
}
Response samples 
application/json
{
  • "message": "Decoding failure in request"
}
Search conversationsDeprecated
NOTE: This endpoint is deprecated and is replaced with POST /search/conversations. Search for conversations containing a particular text.


SecurityApiKeyAuth 
Request 
query Parameters
exactMatch
boolean
Return only exact matches. This value is false by default.


 
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.


 
query
required
string  non-empty 
The text by which to search conversations


 
 Example:  query=cancel my order
Responses 
200
The search results for the searched parameters


400
Invalid value extracted from request context, Invalid value for: query parameter pageLimit, Invalid value for: query parameter pageKey, Invalid value for: query parameter query, Invalid value for: query parameter exactMatch


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


500
Internal failure during request processing


get/v1/search/conversations
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1234,
      • "highlights": {
        • "subject": [
          • "<em class=\"highlight\">Cancel my order</em>"
          ]
        },
      • "innerHits": [
        • {
          • "id": "dadcaea0-4135-4e8a-a5bf-05d4658facba",
          • "highlight": {
            • "text": "I want to <em class=\"highlight\">cancel my order</em> as soon as possible"
            }
          }
        ]
      }
    ]
}
Search conversations with filters
Search for conversations containing a particular text or by filter or combine them both


SecurityApiKeyAuth 
Request 
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.


 
Request Body schema: application/json
optional
The filters to apply to the search


object (Filters) 
 
object (Query) 
 
Responses 
200
The search results for the searched parameters


400
Invalid value extracted from request context, Invalid value for: query parameter pageLimit, Invalid value for: query parameter pageKey, Invalid value for: body


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


500
Internal failure during request processing


post/v1/search/conversations
Request samples 
application/json
{
  • "filters": {
    • "strategy": "All",
    • "conditions": [
      • {
        • "field": {
          • "operator": {
            • "values": [
              • "177e7564-6434-4177-a25a-8530089196ad",
              • "7729e7564-9876-a637-b46b-8530038196b3"
              ],
            • "_type": "IncludesOne"
            },
          • "_type": "TagId"
          }
        }
      ]
    }
}
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1234,
      • "highlights": { }
      },
    • {
      • "id": 2345,
      • "highlights": { }
      },
    • {
      • "id": 3456,
      • "highlights": { }
      }
    ],
  • "meta": {
    • "next": "/beta/search/conversations/?pageKey=cGFnZUxpbWl0PTUwJnBhZ2U9MQ%3D%3D:"
    }
}
Tag conversation
Tag a conversation. You may only use active tags to tag conversations.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
tagId
required
string <uuid> 
 
Responses 
204
The conversation was successfully tagged


400
Invalid value for: path parameter conversationId, Invalid value for: path parameter tagId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


put/v1/conversations/{conversationId}/tags/{tagId}
Request samples 
Response samples 
application/json
{
  • "message": "Invalid value in request"
}
Transfer conversation
Transfer a conversation to a target queue.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
Request Body schema: application/json
required
Transfer conversation request


queueId
required
string <uuid> 
The target queue for the conversation transfer


 
userId
string <uuid> 
An optional agent/admin to originate the transfer of the conversation


 
Responses 
204
The conversation was successfully transferred to the target queue


400
Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, User not found, User is not agent/admin, Queue does not exist


404
An entity in this request could not be found


500
Internal failure during request processing


put/v1/conversations/{conversationId}/transfer/queue
Request samples 
application/json
{
  • "queueId": "92f8d193-b26f-4a62-86a3-bb03ee0915e9",
  • "userId": "a53b25da-f676-4c52-acac-58c9280aa23d"
}
Response samples 
application/json
{
  • "message": "Decoding failure in request"
}
Untag conversation
Untag a conversation. You may remove active or inactive tags from a conversation.


SecurityApiKeyAuth 
Request 
path Parameters
conversationId
required
integer <int64> 
 
tagId
required
string <uuid> 
 
Responses 
204
The conversation was successfully untagged


400
Invalid value for: path parameter conversationId, Invalid value for: path parameter tagId, Invalid value extracted from request context


404
An entity in this request could not be found


500
Internal failure during request processing


delete/v1/conversations/{conversationId}/tags/{tagId}
Request samples 
Response samples 
application/json
{
  • "message": "Invalid value in request"
}
Why Dixa
Product
Capabilities
Resources
Solutions
Company
Call us now 
© Dixa 2025