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

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 for: body, Invalid value extracted from request context, 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

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 for: body, Invalid value extracted from request context

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. Currently Email, WidgetChat and Messenger channels are supported.

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

The message to be added to a conversation

One of:
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.dixa.io

Responses
200

The added message

400

Invalid value for: path parameter conversationId, Invalid value for: body, Invalid value extracted from request context, 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

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"
    }
}
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
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
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
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 for: body, Invalid value extracted from request context, 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
    }
}
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"
      },
    • "_type": "ChatConversation"
    }
}
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 rating
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}/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"
      }
    ]
}
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
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 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"
            }
          }
        ],
      • "_type": "ConversationSearchHit"
      }
    ]
}
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
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


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 2023