Dixa Chatbots API
The Chatbots API from Dixa — 13 operation(s) for chatbots.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dixa Agents Chatbots API
version: beta
servers:
- url: https://dev.dixa.io
security:
- ApiKeyAuth: []
tags:
- name: Chatbots
paths:
/beta/endusers:
post:
tags:
- Chatbots
summary: Create end user
description: Create an end user.
operationId: postEndusers
requestBody:
description: The end user's details
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEndUserInput'
example:
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'
required: true
responses:
'201':
description: The created end user
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEndUserOutput'
example:
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
'400':
description: 'Invalid value extracted from request context, Invalid value for: body, Validation failure during enduser creation'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/endusers/{userId}:
get:
tags:
- Chatbots
summary: Get end user
description: Get an end user by id.
operationId: getEndusersUserid
parameters:
- name: userId
in: path
description: The end user id
required: true
schema:
type: string
format: uuid
responses:
'200':
description: The end user
content:
application/json:
schema:
$ref: '#/components/schemas/GetEndUserOutput'
example:
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
'400':
description: 'Invalid value for: path parameter userId, Invalid value extracted from request context'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Invalid value in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/endusers/{userId}/conversations:
get:
tags:
- Chatbots
summary: List end user conversations
description: 'Lists conversations requested by an end user. <br/> 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}](../Conversations/#tag/Conversations/operation/getConversationsConversationid) endpoint'
operationId: getEndusersUseridConversations
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
- name: pageLimit
in: query
description: Maximum number of results per page. May be used in combination with pageKey to change the number of results in between page requests.
required: false
schema:
type: integer
format: int32
- name: pageKey
in: query
description: Base64 encoded form of pagination query parameters. Do not try to construct or change programmatically as the internal structure may change without notice.
required: false
schema:
type: string
responses:
'200':
description: The list of conversations requested by an EndUser
content:
application/json:
schema:
$ref: '#/components/schemas/ListEndUserConversationsOutput'
example:
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
'400':
description: 'Invalid value for: path parameter userId, Invalid value extracted from request context, Invalid value for: query parameter pageLimit, Invalid value for: query parameter pageKey'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Invalid value in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/conversations/{conversationId}/close:
put:
tags:
- Chatbots
summary: Close conversation
description: Mark a conversation as closed by providing its id.
operationId: putConversationsConversationidClose
parameters:
- name: conversationId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
description: An optional agent/admin to close the conversation
content:
application/json:
schema:
$ref: '#/components/schemas/CloseConversationInput'
example:
userId: 5a556159-9c21-4f3e-a44f-d323deb80d16
required: false
responses:
'204':
description: The conversation was successfully closed
'400':
description: 'Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, User not found, User is not agent/admin'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
/beta/conversations/{conversationId}/followup:
put:
tags:
- Chatbots
summary: Followup conversation
description: Follow up a conversation by providing its id and expiration timestamp.
operationId: putConversationsConversationidFollowup
parameters:
- name: conversationId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
description: A request to followup the conversation
content:
application/json:
schema:
$ref: '#/components/schemas/FollowupConversationInput'
example:
timestamp: '2025-01-08T08:31:25Z'
userId: 5a556159-9c21-4f3e-a44f-d323deb80d16
required: true
responses:
'204':
description: The conversation was successfully followed up
'400':
description: 'Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body, User not found, User is not agent/admin'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
/beta/conversations/{conversationId}/transfer/queue:
put:
tags:
- Chatbots
summary: Transfer conversation
description: Transfer a conversation to a target queue.
operationId: putConversationsConversationidTransferQueue
parameters:
- name: conversationId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
description: Transfer conversation request
content:
application/json:
schema:
$ref: '#/components/schemas/TransferConversationInput'
example:
queueId: 92f8d193-b26f-4a62-86a3-bb03ee0915e9
userId: a53b25da-f676-4c52-acac-58c9280aa23d
required: true
responses:
'204':
description: The conversation was successfully transferred to the target queue
'400':
description: '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'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/conversations/{conversationId}/ratings/{ratingId}/submit:
post:
tags:
- Chatbots
summary: Create conversation rating result
description: Create a rating result for a specific conversation.
operationId: postConversationsConversationidRatingsRatingidSubmit
parameters:
- name: conversationId
in: path
required: true
schema:
type: integer
format: int64
- name: ratingId
in: path
description: The ratingId parameter has to be the ID of the offer created via invoking the /conversations/{conversationId}/ratings/offer endpoint.
required: true
schema:
type: string
requestBody:
description: The rating result to be created for a conversation
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRatingResultInput'
example:
userId: d3cf6f15-1497-4e71-92f2-9b3b228352bd
ratingResult:
value: 4
_type: Csat
comment: Best customer service ever!
submittedAt: '2024-03-11T16:39:30Z'
required: true
responses:
'201':
description: The created conversation rating result
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRatingResultOutput'
example:
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'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/conversations/{conversationId}/ratings/offer:
post:
tags:
- Chatbots
summary: Create conversation rating offer
description: Create a rating offer for a specific conversation.
operationId: postConversationsConversationidRatingsOffer
parameters:
- name: conversationId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
description: The rating offer to be created for a conversation
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRatingOfferInput'
example:
userId: b0323b42-c428-4afa-970e-20bf5bdeeec4
agentId: eeb3bbe5-0355-4ac1-8af5-20d42a3db24b
ratingType: Csat
offeredAt: '2024-03-11T16:39:30Z'
required: true
responses:
'201':
description: The created conversation rating offer
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRatingOfferOutput'
example:
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'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/conversations:
post:
tags:
- Chatbots
summary: Create conversation
description: 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.
operationId: postConversations
requestBody:
description: The conversation to create
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationInput'
example:
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
required: true
responses:
'201':
description: The id of the created conversation
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationOutput'
example:
data:
id: 100
'400':
description: 'Invalid value extracted from request context, Invalid value for: body, Invalid input for Message, Failure to download attachment, Duplicate externalId, Unsupported ConversationChannel'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/conversations/import:
post:
tags:
- Chatbots
summary: Import conversation
description: 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.
operationId: postConversationsImport
requestBody:
description: The type of conversation to import
content:
application/json:
schema:
$ref: '#/components/schemas/GenericConversationImport'
examples:
Generic API messaging conversation example:
summary: Generic API messaging conversation example
description: The following example demonstrates how to import a conversation for the **genericapimessaging** channel. The key part is setting **genericChannelName** to **genericapimessaging**. This channel does not require any channel-specific **attributes**.
value:
genericChannelName: genericapimessaging
requesterId: 9c2a2cce-699f-4a72-89d9-fda5bc8dec8b
requesterConnectionStatus: Connected
direction: Inbound
messages:
- content:
value: Hi, I need help with my order
_type: Text
attachments: []
createdAt: '2021-12-01T13:00:00.003Z'
_type: InboundImport
- content:
value: Sure — what seems to be the problem?
_type: Text
agentId: cd4ceb58-bb3a-443c-9cd8-4f088feafe5b
attachments: []
createdAt: '2021-12-01T14:00:00.004Z'
_type: OutboundImport
createdAt: '2021-12-01T11:00:00.001Z'
assignment:
agentId: cd4ceb58-bb3a-443c-9cd8-4f088feafe5b
assignedAt: '2021-12-01T12:00:00.002Z'
_type: GenericConversationImport
Email conversation example:
summary: Email conversation example
description: The following example demonstrates how to import an email conversation. The key parts is the **genericChannelName** and the **attributes** fields. Please note that the **cc**, **bcc** and **requesterId** fields are optional. **cc** and **bcc** are only relevant for outbound messages, while **requesterId** message attribute is only relevant for inbound messages.
value:
genericChannelName: email
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'
attributes:
emailIntegrationId: sample-integration@email.dixa.io
_type: InboundImport
- content:
value: Our bad, sorry
_type: Text
agentId: cd4ceb58-bb3a-443c-9cd8-4f088feafe5b
attachments:
- url: https://en.wikipedia.org/wiki/Shipwreck#/media/File:Titanic_wreck_bow.jpg
prettyName: shipwreck
createdAt: '2021-12-01T14:00:00.004Z'
attributes:
emailIntegrationId: sample-integration@email.dixa.io
cc:
- a@b.com
- b@c.com
bcc: []
_type: OutboundImport
- content:
value: Thank you!
_type: Text
attachments: []
createdAt: '2021-12-01T15:00:00.005Z'
attributes:
emailIntegrationId: sample-integration@email.dixa.io
requesterId: 4f1f3a86-6b90-411a-9a3b-cf2e4c4cd7cd
_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
attributes:
emailIntegrationId: sample-integration@email.dixa.io
subject: email subject
_type: GenericConversationImport
required: true
responses:
'201':
description: The id of the imported conversation
content:
application/json:
schema:
$ref: '#/components/schemas/ImportConversationOutput'
example:
data:
id: 100
partialErrors:
- message: The conversation could not be assigned
- message: 'Invalid attachment url in message. externalId: 42'
'400':
description: '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'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/conversations/{conversationId}/claim:
put:
tags:
- Chatbots
summary: Claim conversation
description: Claim a conversation for a given agent. To avoid taking over assigned conversations, set the `force` paremeter to false
operationId: putConversationsConversationidClaim
parameters:
- name: conversationId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimConversationInput'
example:
agentId: 5a556159-9c21-4f3e-a44f-d323deb80d16
force: false
required: true
responses:
'204':
description: The conversation was successfully claimed
'400':
description: 'Invalid value for: path parameter conversationId, Invalid value extracted from request context, Invalid value for: body'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Invalid value in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Conflict'
/beta/queues/{queueId}/availability:
get:
tags:
- Chatbots
summary: Get queue availability
description: Get availability of supported channels for a given queue. Currently supported channels are adachat, kindlychat, digitalgeniuschat, genericapimessaging.
operationId: getQueuesQueueidAvailability
parameters:
- name: queueId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: The availability of supported channels for a given queue
content:
application/json:
schema:
$ref: '#/components/schemas/QueueAvailabilityOutput'
example:
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
'400':
description: 'Invalid value for: path parameter queueId, Invalid value extracted from request context ,queue does not exist'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'409':
description: The request could not be completed due to no supported channels configured for this organization
content:
application/json:
schema:
$ref: '#/components/schemas/Conflict'
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
message: There was an internal server error while processing the request
/beta/queues/conversation-position/{csid}:
get:
tags:
- Chatbots
summary: Get the position of the conversation in its current queue
description: Get the approximate position of a given conversation in its current queue.
operationId: getQueuesConversation-positionCsid
parameters:
- name: csid
in: path
required: true
schema:
type: integer
format: int64
responses:
'200':
description: The position of the conversation in the queue
content:
application/json:
schema:
$ref: '#/components/schemas/GetQueuedConversationPositionOutput'
example:
data:
position: 10
queuedAt: '2021-12-01T13:00:00.003Z'
'400':
description: 'Invalid value for: path parameter csid, Invalid value extracted from request context'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'404':
description: An entity in this request could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
example:
message: The requested resource could not be found
'500':
description: Internal failure during request processing
content:
application/json:
schema:
$ref: '#/components/schema
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dixa/refs/heads/main/openapi/dixa-chatbots-api-openapi.yml