Dixa Search API
The Search API from Dixa — 1 operation(s) for search.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dixa Agents Search API
version: beta
servers:
- url: https://dev.dixa.io
security:
- ApiKeyAuth: []
tags:
- name: Search
paths:
/beta/search/conversations:
get:
tags:
- Search
summary: Search conversations
description: 'NOTE: This endpoint is deprecated and is replaced with POST /search/conversations. Search for conversations containing a particular text.'
operationId: getSearchConversations
parameters:
- 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
- name: query
in: query
description: The text by which to search conversations
required: true
schema:
type: string
minLength: 1
example: cancel my order
- name: exactMatch
in: query
description: Return only exact matches. This value is false by default.
required: false
schema:
type: boolean
responses:
'200':
description: The search results for the searched parameters
content:
application/json:
schema:
$ref: '#/components/schemas/SearchOutput'
example:
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
'400':
description: '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'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'401':
description: The user who issued the access token used in the request is not authorized to perform the operation
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
example:
message: User is unauthorized to perform an underlying operation
'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
deprecated: true
post:
tags:
- Search
summary: Search conversations with filters
description: Search for conversations containing a particular text or by filter or combine them both
operationId: postSearchConversations
parameters:
- 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
requestBody:
description: The filters to apply to the search
content:
application/json:
schema:
$ref: '#/components/schemas/SearchParametersInput'
examples:
Find conversations that include one of two tags:
value:
filters:
strategy: All
conditions:
- field:
operator:
values:
- 177e7564-6434-4177-a25a-8530089196ad
- 7729e7564-9876-a637-b46b-8530038196b3
_type: IncludesOne
_type: TagId
Find conversations that contain any tags:
value:
query:
value: order 12345
exactMatch: true
filters:
strategy: All
conditions:
- field:
operator:
_type: IsNotEmpty
_type: TagId
Find conversations that contain all specified tags and contains specific text:
value:
query:
value: order 12345
exactMatch: true
filters:
strategy: All
conditions:
- field:
operator:
values:
- 177e7564-6434-4177-a25a-8530089196ad
- 7729e7564-9876-a637-b46b-8530038196b3
_type: IncludesAll
_type: TagId
Find conversations with custom attribute of type Text:
value:
query:
value: delivery
exactMatch: true
filters:
strategy: All
conditions:
- field:
operator:
values:
- - PK461926232
- - PK461926233
- - PK461926234
_type: IsOneOf
attributeId: 1fba54c0-3ef6-48c8-bf00-912c5c9890fd
_type: CustomAttribute
Find conversations with custom attribute of type Select:
value:
filters:
strategy: All
conditions:
- field:
operator:
values:
- - cookies
- - chocolate
- chocolate_bar
- with_nuts
- peanuts
- - tart
- nut_tart
- hazelnuts
_type: IsOneOf
attributeId: 30cd8aa4-3b58-4d70-a716-887dd6f348b4
_type: CustomAttribute
Find conversations where custom attribute is not set:
value:
filters:
strategy: All
conditions:
- field:
operator:
_type: IsEmpty
attributeId: 1fba54c0-3ef6-48c8-bf00-912c5c9890fd
_type: CustomAttribute
Find conversations with duration between 10 and 20 seconds:
value:
filters:
strategy: All
conditions:
- field:
operator:
min: 10000
max: 20000
_type: Between
_type: Duration
Find conversations with last message since specified time:
value:
filters:
strategy: All
conditions:
- field:
operator:
timestamp: '2023-02-11T22:59:59.999Z'
_type: Since
_type: LastMessage
Find conversations in a specific queue and with last activity until certain date:
value:
filters:
strategy: All
conditions:
- field:
operator:
values:
- 6f2e0d7f-d7e2-408e-93df-3c43f0a070c3
_type: IsOneOf
_type: QueueId
- field:
operator:
timestamp: '2023-02-11T22:59:59.999Z'
_type: Until
_type: LastActivity
Find conversations with creation date between two timestamps or closed date between two timestamps:
value:
filters:
strategy: Any
conditions:
- field:
operator:
timestampFrom: '2023-02-11T22:59:59.999Z'
timestampTo: '2023-02-11T23:59:59.999Z'
_type: Between
_type: CreationDate
- field:
operator:
timestampFrom: '2023-02-11T22:59:59.999Z'
timestampTo: '2023-02-11T23:59:59.999Z'
_type: Between
_type: ClosedDate
Find conversations with direction Inbound and channel Phone or SMS:
value:
filters:
strategy: All
conditions:
- field:
operator:
values:
- inbound
_type: IsOneOf
_type: Direction
- field:
operator:
values:
- phone
- sms
_type: IsOneOf
_type: Channel
required: false
responses:
'200':
description: The search results for the searched parameters
content:
application/json:
schema:
$ref: '#/components/schemas/SearchConversationsWithFiltersOutput'
examples:
Results when query was not provided and next page is available:
value:
data:
- id: 1234
highlights: {}
- id: 2345
highlights: {}
- id: 3456
highlights: {}
meta:
next: '/<api-version>/search/conversations/?pageKey=cGFnZUxpbWl0PTUwJnBhZ2U9MQ%3D%3D:'
Results when query was provided and no more pages are available:
value:
data:
- id: 1212
highlights:
subject:
- <em class="highlight">Cancel my order</em>
- id: 1234
highlights:
subject:
- <em class="highlight">Cancel my order</em>
'400':
description: 'Invalid value extracted from request context, Invalid value for: query parameter pageLimit, Invalid value for: query parameter pageKey, Invalid value for: body'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
message: Decoding failure in request
'401':
description: The user who issued the access token used in the request is not authorized to perform the operation
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
example:
message: User is unauthorized to perform an underlying operation
'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
components:
schemas:
IsNotOneOf2:
title: IsNotOneOf
type: object
properties:
values:
description: 'Array of arrays of strings. Each inner array represents a possible custom attribute value.<br>If custom attribute is of type Select, either a parent value can be provided or a child value, but with a whole path to its parent value. Example: [["parent"], ["parent", "child1", "child2", "child3"], ["parent", "child1"]].<br>If custom attribute is of type Text, each search value must be wrapped in an array too. Example: [["value1"]]'
type: array
items:
type: array
items:
type: string
Between:
title: Between
description: 'Timestamps in ISO-8601 format: yyyy-MM-dd''T''HH:mm:ss''Z'' '
type: object
required:
- timestampFrom
- timestampTo
properties:
timestampFrom:
type: string
format: date-time
timestampTo:
type: string
format: date-time
LongerThanOrEqualTo:
title: LongerThanOrEqualTo
description: 'In milliseconds; for example: ''10800000'' (3 hours)'
type: object
required:
- duration
properties:
duration:
type: integer
format: int64
Filters:
title: Filters
type: object
required:
- strategy
properties:
strategy:
description: 'values: [All, Any]'
type: string
conditions:
type: array
items:
$ref: '#/components/schemas/Condition'
CreationDate:
title: CreationDate
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/TimestampOperator'
SearchField:
title: SearchField
oneOf:
- $ref: '#/components/schemas/AgentId'
- $ref: '#/components/schemas/AssignedDate'
- $ref: '#/components/schemas/Channel'
- $ref: '#/components/schemas/ClosedDate'
- $ref: '#/components/schemas/ContactId'
- $ref: '#/components/schemas/ConversationId'
- $ref: '#/components/schemas/CreationDate'
- $ref: '#/components/schemas/CustomAttribute1'
- $ref: '#/components/schemas/Direction'
- $ref: '#/components/schemas/Duration'
- $ref: '#/components/schemas/LastActivity'
- $ref: '#/components/schemas/LastMessage'
- $ref: '#/components/schemas/QueueId'
- $ref: '#/components/schemas/Status1'
- $ref: '#/components/schemas/TagId'
IsEmpty:
title: IsEmpty
type: object
ConversationId:
title: ConversationId
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/FieldHasSingleValueOperator'
IsOneOf4:
title: IsOneOf
type: object
required:
- values
properties:
values:
description: 'values: [open, closed, pending]'
type: array
items:
type: string
IncludesAll:
title: IncludesAll
type: object
properties:
values:
type: array
items:
type: string
ConversationSearchWithFiltersHit:
title: ConversationSearchWithFiltersHit
type: object
required:
- id
- highlights
properties:
id:
description: Identifier of a Conversation where a match was found
type: integer
format: int64
highlights:
$ref: '#/components/schemas/Map_Vector_String'
Duration:
title: Duration
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/DurationOperator'
IsNotEmpty:
title: IsNotEmpty
type: object
IsOneOf3:
title: IsOneOf
type: object
required:
- values
properties:
values:
description: 'values: [inbound, outbound, internal]'
type: array
items:
type: string
SearchParametersInput:
title: SearchParametersInput
type: object
properties:
query:
$ref: '#/components/schemas/Query'
filters:
$ref: '#/components/schemas/Filters'
ExcludesOne:
title: ExcludesOne
type: object
properties:
values:
type: array
items:
type: string
Status1:
title: Status
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/StatusOperator'
QueueId:
title: QueueId
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/FieldCanHaveSingleValueOrBeEmptyOperator'
Query:
title: Query
type: object
required:
- value
properties:
value:
type: string
exactMatch:
type: boolean
CustomAttribute1:
title: CustomAttribute
type: object
required:
- operator
- attributeId
properties:
operator:
$ref: '#/components/schemas/CustomAttributeOperator'
attributeId:
type: string
PaginationLinks:
title: PaginationLinks
type: object
properties:
previous:
description: url
type: string
next:
description: url
type: string
ServerError:
title: ServerError
type: object
required:
- message
properties:
message:
type: string
BadRequest:
title: BadRequest
type: object
required:
- message
properties:
message:
type: string
Map_Vector_String:
title: Map_Vector_String
description: Snippet of text where a match was found. Matched text will be wrapped in \<em\> tags.
type: object
additionalProperties:
type: array
items:
type: string
SearchOutput:
title: SearchOutput
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ConversationSearchHit'
meta:
$ref: '#/components/schemas/PaginationLinks'
ContactId:
title: ContactId
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/FieldHasSingleValueOperator'
CustomAttributeOperator:
title: CustomAttributeOperator
oneOf:
- $ref: '#/components/schemas/IsEmpty'
- $ref: '#/components/schemas/IsNotEmpty'
- $ref: '#/components/schemas/IsNotOneOf2'
- $ref: '#/components/schemas/IsOneOf2'
AgentId:
title: AgentId
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/FieldCanHaveSingleValueOrBeEmptyOperator'
StatusOperator:
title: StatusOperator
oneOf:
- $ref: '#/components/schemas/IsNotOneOf4'
- $ref: '#/components/schemas/IsOneOf4'
ShorterThanOrEqualTo:
title: ShorterThanOrEqualTo
description: 'In milliseconds; for example: ''10800000'' (3 hours)'
type: object
required:
- duration
properties:
duration:
type: integer
format: int64
Between1:
title: Between
description: 'min and max in milliseconds; for example: ''10800000'' (3 hours)'
type: object
required:
- min
- max
properties:
min:
type: integer
format: int64
max:
type: integer
format: int64
TimestampOperator:
title: TimestampOperator
oneOf:
- $ref: '#/components/schemas/Between'
- $ref: '#/components/schemas/Since'
- $ref: '#/components/schemas/Until'
ConversationSearchInnerHit:
title: ConversationSearchInnerHit
type: object
required:
- id
- highlight
properties:
id:
description: Identifier of a sub-entity (such as a Message) where a match was found
type: string
highlight:
$ref: '#/components/schemas/Map_String'
description: Snippet of text where a match was found. Matched text will be wrapped in \<em\> tags
AssignedDate:
title: AssignedDate
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/TimestampOperator'
Map_String:
title: Map_String
type: object
additionalProperties:
type: string
IsNotOneOf1:
title: IsNotOneOf
type: object
required:
- values
properties:
values:
description: 'values: [email, contactform, chat, dixamessenger, phone, voicemail, callback, sms, facebookmessenger, whatsapp, adachat, digitalgeniuschat, kindlychat, genericapimessaging, trustpilot, yotpo]'
type: array
items:
type: string
IsNotOneOf4:
title: IsNotOneOf
type: object
required:
- values
properties:
values:
description: 'values: [open, closed, pending]'
type: array
items:
type: string
LastActivity:
title: LastActivity
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/TimestampOperator'
Condition:
title: Condition
type: object
required:
- field
properties:
field:
$ref: '#/components/schemas/SearchField'
Since:
title: Since
description: 'Timestamp in ISO-8601 format: yyyy-MM-dd''T''HH:mm:ss''Z'' '
type: object
required:
- timestamp
properties:
timestamp:
type: string
format: date-time
Direction:
title: Direction
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/DirectionOperator'
ExcludesAll:
title: ExcludesAll
type: object
properties:
values:
type: array
items:
type: string
SearchConversationsWithFiltersOutput:
title: SearchConversationsWithFiltersOutput
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ConversationSearchWithFiltersHit'
meta:
$ref: '#/components/schemas/PaginationLinks'
IsOneOf:
title: IsOneOf
type: object
properties:
values:
type: array
items:
type: string
Unauthorized:
title: Unauthorized
type: object
required:
- message
properties:
message:
type: string
FieldCanHaveSingleValueOrBeEmptyOperator:
title: FieldCanHaveSingleValueOrBeEmptyOperator
oneOf:
- $ref: '#/components/schemas/IsEmpty'
- $ref: '#/components/schemas/IsNotEmpty'
- $ref: '#/components/schemas/IsNotOneOf'
- $ref: '#/components/schemas/IsOneOf'
ChannelOperator:
title: ChannelOperator
oneOf:
- $ref: '#/components/schemas/IsNotOneOf1'
- $ref: '#/components/schemas/IsOneOf1'
FieldCanHaveMultipleValuesOrBeEmptyOperator:
title: FieldCanHaveMultipleValuesOrBeEmptyOperator
oneOf:
- $ref: '#/components/schemas/ExcludesAll'
- $ref: '#/components/schemas/ExcludesOne'
- $ref: '#/components/schemas/IncludesAll'
- $ref: '#/components/schemas/IncludesOne'
- $ref: '#/components/schemas/IsEmpty'
- $ref: '#/components/schemas/IsNotEmpty'
IsOneOf2:
title: IsOneOf
type: object
properties:
values:
description: 'Array of arrays of strings. Each inner array represents a possible custom attribute value.<br>If custom attribute is of type Select, either a parent value can be provided or a child value, but with a whole path to its parent value. Example: [["parent"], ["parent", "child1", "child2", "child3"], ["parent", "child1"]].<br>If custom attribute is of type Text, each search value must be wrapped in an array too. Example: [["value1"]]'
type: array
items:
type: array
items:
type: string
IncludesOne:
title: IncludesOne
type: object
properties:
values:
type: array
items:
type: string
IsOneOf1:
title: IsOneOf
type: object
required:
- values
properties:
values:
description: 'values: [email, contactform, chat, dixamessenger, phone, voicemail, callback, sms, facebookmessenger, whatsapp, adachat, digitalgeniuschat, kindlychat, genericapimessaging, trustpilot, yotpo]'
type: array
items:
type: string
Channel:
title: Channel
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/ChannelOperator'
TagId:
title: TagId
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/FieldCanHaveMultipleValuesOrBeEmptyOperator'
DurationOperator:
title: DurationOperator
oneOf:
- $ref: '#/components/schemas/Between1'
- $ref: '#/components/schemas/LongerThanOrEqualTo'
- $ref: '#/components/schemas/ShorterThanOrEqualTo'
DirectionOperator:
title: DirectionOperator
oneOf:
- $ref: '#/components/schemas/IsNotOneOf3'
- $ref: '#/components/schemas/IsOneOf3'
Until:
title: Until
description: 'Timestamp in ISO-8601 format: yyyy-MM-dd''T''HH:mm:ss''Z'' '
type: object
required:
- timestamp
properties:
timestamp:
type: string
format: date-time
IsNotOneOf3:
title: IsNotOneOf
type: object
required:
- values
properties:
values:
description: 'values: [inbound, outbound, internal]'
type: array
items:
type: string
ConversationSearchHit:
title: ConversationSearchHit
type: object
required:
- id
- highlights
properties:
id:
description: Identifier of a Conversation where a match was found
type: integer
format: int64
highlights:
$ref: '#/components/schemas/Map_Vector_String'
innerHits:
description: List of sub-entities (such as Messages) where a match was found
deprecated: true
type: array
items:
$ref: '#/components/schemas/ConversationSearchInnerHit'
ClosedDate:
title: ClosedDate
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/TimestampOperator'
IsNotOneOf:
title: IsNotOneOf
type: object
properties:
values:
type: array
items:
type: string
LastMessage:
title: LastMessage
type: object
required:
- operator
properties:
operator:
$ref: '#/components/schemas/TimestampOperator'
FieldHasSingleValueOperator:
title: FieldHasSingleValueOperator
oneOf:
- $ref: '#/components/schemas/IsNotOneOf'
- $ref: '#/components/schemas/IsOneOf'
securitySchemes:
ApiKeyAuth:
type: apiKey
name: Authorization
in: header