Dixa
    Nothing Found

Chatbots

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

Create end user

Create an end user.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required

The end user's details

additionalEmails
Array of strings unique

Additional email addresses for the contact

additionalPhoneNumbers
Array of strings unique

Additional phone numbers for the contact

avatarUrl
string

The url from which to load the contact's avatar

displayName
string

The contact's display name

email
string

The contact's primary email address

externalId
string

Custom external identifier for the contact

firstName
string

The contact's first name

lastName
string

The contact's last name

middleNames
Array of strings

The contact's middle names

phoneNumber
string

The contact's primary phone number

Responses
201

The created end user

400

Invalid value extracted from request context, Invalid value for: body, Validation failure during enduser creation

500

Internal failure during request processing

post/beta/endusers
Request samples
application/json
{
  • "displayName": "Alice Brown",
  • "email": "alice@brown.com",
  • "phoneNumber": "+551155256325",
  • "additionalEmails": [
    • "alice@secondary.email"
    ],
  • "additionalPhoneNumbers": [
    • "+5566778899"
    ],
  • "firstName": "Alice",
  • "lastName": "Brown",
  • "middleNames": [ ],
  • "avatarUrl": "http://avatar.url",
  • "externalId": "#12345678"
}
Response samples
application/json
{
  • "data": {
    • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
    • "createdAt": "2020-12-16T09:41:43Z",
    • "displayName": "Alice Brown",
    • "email": "alice@brown.com",
    • "phoneNumber": "+551155256325",
    • "additionalEmails": [
      • "alice@secondary.email"
      ],
    • "additionalPhoneNumbers": [
      • "+5566778899"
      ],
    • "firstName": "Alice",
    • "lastName": "Brown",
    • "middleNames": [ ],
    • "avatarUrl": "https://files.dixa.io/public/image_id",
    • "externalId": "#12345678",
    • "customAttributes": [
      • {
        • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
        • "name": "My Attribute",
        • "identifier": "my_attribute",
        • "value": "My Attribute Value"
        }
      ]
    }
}

Get end user

Get an end user by id.

SecurityApiKeyAuth
Request
path Parameters
userId
required
string <uuid>

The end user id

Responses
200

The end user

400

Invalid value for: path parameter userId, Invalid value extracted from request context

404

An entity in this request could not be found

500

Internal failure during request processing

get/beta/endusers/{userId}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "434ce9f5-14c8-4be1-a0a8-f755010deb9b",
    • "createdAt": "2020-12-16T09:41:43Z",
    • "displayName": "Alice Brown",
    • "email": "alice@brown.com",
    • "phoneNumber": "+551155256325",
    • "additionalEmails": [
      • "alice@secondary.email"
      ],
    • "additionalPhoneNumbers": [
      • "+5566778899"
      ],
    • "firstName": "Alice",
    • "lastName": "Brown",
    • "middleNames": [ ],
    • "avatarUrl": "https://files.dixa.io/public/image_id",
    • "externalId": "#12345678",
    • "customAttributes": [
      • {
        • "id": "4baa78bc-4815-4122-9c99-f71cd742d37b",
        • "name": "My Attribute",
        • "identifier": "my_attribute",
        • "value": "My Attribute Value"
        }
      ]
    }
}
Get queue availability
Get availability of supported channels for a given queue. Currently supported channels are adachat, kindlychat, digitalgeniuschat.


SecurityApiKeyAuth 
Request 
path Parameters
queueId
required
string <uuid> 
 
Responses 
200
The availability of supported channels for a given queue


400
Invalid value for: path parameter queueId, Invalid value extracted from request context ,queue does not exist


409
The request could not be completed due to no supported channels configured for this organization


500
Internal failure during request processing


get/beta/queues/{queueId}/availability
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "channelAvailability": {
        • "genericChannelName": "adachat",
        • "availability": "NotAvailable",
        • "queueSize": 10,
        • "_type": "GenericChannel"
        },
      • "_type": "Success"
      },
    • {
      • "error": {
        • "channel": "kindlychat",
        • "message": "Could not get availability for channel",
        • "_type": "UnexpectedError"
        },
      • "_type": "Failure"
      }
    ]
}
Get the position of the conversation in its current queue
Get the approximate position of a given conversation in its current queue.


SecurityApiKeyAuth 
Request 
path Parameters
csid
required
integer <int64> 
 
Responses 
200
The position of the conversation in the queue


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


404
An entity in this request could not be found


500
Internal failure during request processing


get/beta/queues/conversation-position/{csid}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "position": 10,
    • "queuedAt": "2021-12-01T13:00:00.003Z"
    }
}
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). 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
 
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/beta/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 end user conversations
Lists conversations requested by an end user. 
 Note: Custom attributes are not part of the response at this point. If you need to get custom attributes for a conversation use the GET /conversations/{conversationId} endpoint


SecurityApiKeyAuth 
Request 
path Parameters
userId
required
string <uuid> 
 
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.


 
Responses 
200
The list of conversations requested by an EndUser


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


404
An entity in this request could not be found


500
Internal failure during request processing


get/beta/endusers/{userId}/conversations
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "requesterId": "9deb936b-52e5-4c44-828d-4c8d48fe0c7e",
      • "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"
      }
    ]
}
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/beta/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"
}
Why Dixa
Product
Capabilities
Resources
Solutions
Company
Call us now 
© Dixa 2024