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.

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": [
    • {
      • "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

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"
}

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"
}