Endpoints - Search Session
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 rangeNote, 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 examplesFind 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 BySort by the call time, descending ordersession_start_time:desc
Sort by agent name ascending order, status descending order
agent_information:asc,status:desc
Project FieldRetrieve 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 queriesGet the first 100 agent queries, whose status has ended, sorted by session_start_time descending, that were made between the 15th and 17th of Septemberhttps://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
Comments
0 comments
Article is closed for comments.