Endpoints - Search Session – Vonage API Support

Objective

Search Session

Applies To

Vonage AI Studio

Procedure

Any request to this endpoint must contain X-Vgai-Key header with a valid API key

Endpoint- https://studio-api-<REGION>ai.vonage.com/insights/sessions

For <REGION> please fill in the region of your agent, which will be either EU or US.

Method: GET

This is a flexible, low-level endpoint that allows you to provide ElasticSearch syntax requests to get fine-grained results.

Parameters:

from_date - isoformatted datetime, presents the start of the search range

to_date - isoformatted datetime, presents the end of the search range

Note, the system only supports date ranges up to 60 days apart

page_number - int - pagination page number (starts from 0)

page_size - int - pagination page size

sort_by - array of strings - a comma-separated list of <document attribute>:<asc/desc>. Any attributes in the document are valid here.

Example uses: "session_start_time:desc,agent_information.id:asc"

sort by session start time descending order, agent id ascending order after that

project_fields - string - a string list of the fields to retrieve from the document.

Example uses: ["session_start_time","source","destination","agent_id","channel_data.duration","id"]

Only get the following fields from the document:

session_start_time

source

destination

agent_id

channel_data.duration

id

filter_by - dictionary - a dictionary containing elasticsearch boolean query components.

This dictionary can contain the following three keys, whose value will be explained below:

must - All the search patterns in the "must" array must be present in the returned document.

must_not - All the search patterns in the "must_not" array must not be present in the returned document.

should. - A document must contain at least one value in the "should" array, if it has no value in the "should" array, it will not match.

Each of these keys is a list of dictionaries. Each dictionary contains a query component that looks like this:

{"term": {"request_ids": "12345"}}

This tells elasticsearch to do an exact match on request_ids and only return documents that have a value in request_ids that's equal to "12345"

{"match": {"transcription.client": "i love this agent!"}}

This tells elasticsearch to do a match search on all documents in order to find all the documents in which the client has at one point said something in the spirit of "I love this agent".

It's important to remember the distinction between term and match.

Term searches perform an exact comparison, and so they're useful for searching ids, dates, and numbers.

Match searches perform a search engine style search that look for a match in the value like a search engine would do, rather than an exact 1-1 match. This is useful for scanning conversations.

Any ID field can only be searched using term searches, match searches will not work. The following fields are considered ID fields:

`api_key`	The agent's nexmo api key (not yet implemented)
`id`	Session ID
`source`	Caller phone number
`destination`	Agent phone number
`account_id`
`channel`	Telephony/ Whatsapp/ http
`agent_information.id`	Agent ID
`agent_information.version_id`	Published Version
`agent_information.name`	Agent Name
`agent_information.voice`	Voice name
`agent_information.language`	Agent Language
`flow_data.collected_tags.tag`	Collected tags during the call, can have duplication in case the same tag was collected multiple times
`flow_data.collected_tags.category`
`flow_data.collected_parameters.name`	Collected parameters, can have duplication in case the same parameter was collected multiple times
`flow_data.collected_parameters.type`	Entity type
`flow_data.collected_parameters.audio_url`	Recording URL
`flow_path.node_id`
`flow_path.request_id`	Request ID made by the node
`flow_path.type`	Node type
`flow_path.tags.tag`	Tags collected by the node
`flow_path.tags.category`	Tag category collected by the node
`flow_path.context.execution_parameters.name`	Parameter information
`flow_path.context.execution_parameters.type`	Parameter information
`flow_path.context.execution_parameters.audio_url`	Parameter information
`flow_path.context.url`	If the node send a webhook request to another URL, this is that URL
`flow_path.request.payload`	The payload sent to the webhook
`flow_path.request.url`	Same URL as above
`flow_path.request.headers`	Headers sent to the URL
`flow_path.request.verb`	POST/GET/UPDATE etc
`flow_path.response.payload`	Response provided by the API
`tags_list.tag`	Tags collected by session, no duplication here, one entry per tag
`tags_list.category`	Tag Category
`tags_list.count`	Amount of times the tag was collected
`params_list.name`	Parameters collected by the session, no duplication here, only the last value is set per parameter
`params_list.type`
`params_list.value`
`params_list.audio_url`	Recording url of the parameter
`flow_path.context.altered_parameters.alteration_source`	What caused this parameter's value to change? It can be injected/completed/classified
`flow_path.context.altered_parameters.audio_duration`
`flow_path.context.altered_parameters.audio_url`
`flow_path.context.altered_parameters.entity`
`flow_path.context.altered_parameters.name`
`flow_path.context.altered_parameters.value`
`flow_path.context.altered_parameters.value_text`
`channel_data.audio_url`	Recording URL for the call
`channel_data.call_status`	The call's status (in_progress/ended)
`channel_data.duration`	Call's duration (in milliseconds)
`channel_data.status_code`	The call's status in terms of if it had errors or not. 0 = successful, 100 = warning, 200 = erroneous
`parameters.<parameter_name>`	A way to get the parameter's last set value in a nicer way
`tags.<tag_name>`	A way to get the tag's amount of times collected

Parameter usage examples

Find all calls from agent id 1234567, in which the client has said at one point "shut up"

{
"must": [
{"term": {"agent_information.id": "1234567"}},
{"match": {"transcription.client": "shut up"}}
]
}

Find all calls that were tagged as tag "cat", "dog" and "rat"

{
"must": [
{"term": {"flow_data.collected_tags.tag": "cat"}},
{"term": {"flow_data.collected_tags.tag": "dog"}},
{"term": {"flow_data.collected_tags.tag": "rat"}}
]
}

Find all the calls from phone number "9726666666" that had either request id "22" or request id "44"

{
"must": [
{"term": {"source": "9726666666"}}
],
"should": [
{"term": {"request_ids": "22"}},
{"term": {"request_ids": "44"}}
]
}

Find all the calls except for calls that were tagged as "invalid"

{
"must_not": [
{"term": {"flow_data.collected_tags.tag": "invalid"}}
]
}

Sort By

Sort by the call time, descending order

session_start_time:desc

Sort by agent name ascending order, status descending order

agent_information:asc,status:desc

Project Field

Retrieve only the agent information fields and the flow_data fields (This will return all the contents of these fields, so all the agent information and all the flow data)

["agent_information","flow_data"]

Retrieve the agent name, all the collected tags, and status

["agent_information.name","flow_data.collected_tags","status"]

Example queries

Get the first 100 agent queries, whose status has ended, sorted by session_start_time descending, that were made between the 15th and 17th of September

https://studio-api-<REGION>.ai.vonage.com/insights/sessions?from_date=2020-09-15&to_date=2020-09-17&page_number=0&page_size=100&sort_by=session_start_time:desc&filter_by={"must": [{"term": {"status":"ended"}}]}&project_fields=["agent_information"]

Get results 30-40 of all calls that happened on the 20th August 2020

https://stairway.ai.vonage.com/insights/sessions?from_date=2020-08-20&to_date=2020-08-20&page_number=3&page_size=10

General call logs

from_date = <isoformatted from date>
to_date = <isoformatted to date>
page_size = <page size>
page_number = <page number> // starts from 0
project_fields = ["session_start_time", "agent_id", "source", "channel_data.duration"]

Call logs for one or more agent

from_date = <isoformatted from date>
to_date = <isoformatted to date>
page_size = <page size>
page_number = <page number>
project_fields = ["session_start_time", "agent_id", "source", "channel_data.duration"]
filter_by = {"should" [
{"term": {"agent_id": "<agent_id_1>"}},
{"term": {"agent_id": "<agent_id_2>"}}
]}

Call logs for one or more agent, sorted by the longest call duration

from_date = <isoformatted from date>
to_date = <isoformatted to date>
page_size = <page size>
page_number = <page number>
project_fields = ["session_start_time", "agent_id", "source", "channel_data.duration"]
sort_by = "channel_data.duration:desc"
filter_by = {"should" [
{"term": {"agent_id": "<agent_id_1>"}},
{"term": {"agent_id": "<agent_id_2>"}}
]}

Expected Errors:

401 Errors in case invalid parameters are provided (such as invalid date ranges, invalid filters, etc)

404 Errors in case searching for a specific session yields no result

API Support Help Center

Search

Menu

Endpoints - Search Session

Objective

Applies To

Procedure

Parameters:

Expected Errors:

Comments

API Support Help Center

Search

Menu

Objective

Applies To

Procedure

Parameters:

Expected Errors:

Related articles