Use Queries in Search

When reviewing conversations in the Insights section or NLU Inbox, or while browsing skills in the Skill Store, you can use the search bar to narrow the results. You can perform basic searches using natural language or you can write queries in query language. This kind of query is built with three basic parts:

  • Parameter
  • Operator
  • Value

To build a simple query, start with a parameter and your desired value and place the appropriate operator in between. You can build more complex queries by using an additional operator to combine two or more simple queries.

Akela wants to find all conversations that ended with a handover to an agent. She uses the parameter action, value handover, and operator =.

Her full query looks like this:

action = handover

Unfortunately, this query returned too many results for Akela to easily comb through. She decides that she wants to narrow this search to only see results from the past two weeks. She adds a second simple query to her original and combines them with the operator AND.

Her full query now looks like this:

action = handover AND datetime > -14 days

Supported Parameters and Values

The following table details all supported parameters, how to use them, and which sections of Bot Builder support each one.

Parameter Details Supported in
action

The name that Bot Builder uses for an action. Supported values are:

  • integration
  • handover
  • core_fallback
  • fill_slot
bot_message_count How many outbound messages are in the conversation. Values for this parameter must be in numeral format.
category Allows you to filter the bot skills that are listed by the category they are tagged with.
channel

The name, type, or ID of a channel. You will only get results for channels you have configured in Digital Experience.

Supported values are:

  • apple-business
  • facebook-dm
  • twitter-dm
  • vkontakte-dm
  • live-chat
  • chat
  • line
  • slack
  • sms
  • teams
  • telegram
  • viber
  • whatsapp
  • talk-to-your-bot
  • talk-to-your-bot-public
conversation The ID of a conversation.
customer The name or ID of a customer.
customer_contact The contact ID (also called case ID) from CXoneDigital Experience.
customer_message_count How many inbound messages are in the conversation. Values for this parameter must be in numeral format.
date

Date that does not include a specific time. When this parameter is used, any value for time is automatically set to 00:00:00. Values for this parameter can be absolute or relative.

datetime

Date and time. Values for this parameter can be absolute or relative.

Supported formats for absolute dates are:

  • United States — 2nd of January is written numerically as 01/02/2023
  • Europe — 2nd of January is written numerically as 02/01/2023
  • Written format — 2nd January 2023 or 2 January 2023

Supported values for relative dates are:

  • now
  • - (subtract) — seconds, minutes, days, months, years
  • + (add) — seconds, minutes, days, months, years
  • previous — second, minute, hour, day, month, year, weekday, week, fortnight, day name in format Monday or Mon
  • next — second, minute, hour, day, month, year, weekday, week, fortnight, day name in format Monday or Mon
  • tomorrow (now + 24 hours)
  • yesterday (now - 24 hours)
  • noon
  • afternoon
  • midnight
  • last — day name in format Monday or Mon
  • first day of this/next — month
  • last day of this/next — month
fulltext If you are building a query with query language, this parameter allows you to add natural language to it.

intent

The name of an intent you've created.

intent_confidence

How confident Bot Builder is that the intent is classified correctly. Supported values range from 0 to 0.99, just like when designing fallback.

is_reviewed Review status of a conversation. Values for this parameter are true (has been reviewed) or false (has not been reviewed).
language Allows you to filter the bot skills that are listed by the language they are set for.
message_count How many total messages are in the conversation. This number includes both inbound and outbound messages. Values for this parameter must be in numeral format.
tag Displays conversations based on tags that are or are not applied. This parameter works with every available operator.

Supported Operators

The following table displays all supported operators and describes what they stand for.

Operator Description
= Represents "equal to"
!= Represents "not equal to"
< Represents "less than"
<= Represents "less than or equal to"
> Represents "greater than"
>= Represents "greater than or equal to"
AND

Return conversations where values on both sides are matched.

For example, the following query returns SMS conversations that were handed over to an agent:

channel = sms AND action = handover

OR

Return conversations where at least one value from either side is matched.

For example, the following query returns all SMS conversations and all WhatsApp conversations:

channel = sms OR channel = whatsapp

NOT

Return conversations where the value is not matched.

For example, the following query returns all conversations that were not in the SMS channel:

NOT channel = sms

IN

Return conversations where the value is matched with at least one option from the list.

For example, the following query returns all conversations in the SMS and WhatsApp channels:

channel IN (sms, whatsapp)

( )

Help you organize a complex query and assign priority based on the general math concept that items inside parentheses are processed first.

For example, the following query returns both SMS conversations that were handed over to an agent and WhatsApp conversations with more than four messages:

(action = handover AND channel = sms) OR (message_count < 4 AND channel = whatsapp)

Additional Query Examples

All conversations from today:

datetime > midnight

All conversations from a specific day:

datetime >= 2nd Jan 2021 AND datetime < 3rd Jan 2021

All conversations on the SMS channels where handed over to a live agent occurred:

channel = sms AND action = handover

All conversations from SMS or Whatsapp channels:

channel = sms OR channel = whatsapp

All conversations on WhatsApp or SMS channels, from the last 30 days, and they are considered abandoned (less than 3 messages) or they were escalated to live agent:

channel IN (whatsapp, sms) AND datetime > -30 days AND (message_count < 3 OR action = handover)