When using curly braces in the query parameters, make sure you encode the content of your curly braces. If sent without the encoding, your request will return empty.
Endpoints
Search Session - Requires API Key
Any request to this endpoint must contain X-Vgai-Key header with a valid API key.Please make sure not to add any spaces after or within the endpoint.
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
Paramters collected by the session, no duplication here, only the last value is set per parameter
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
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
For <REGION> please fill in the region of your agent, which will be either EU or US.
Method: GET
Searches for the provided session ID in a wide range of dates. Please note that the nature of this query is much slower than the standard get session provided above, so only use it if you are unsure when the session took place.
Delete Session - Requires API Key
Any request to this endpoint must contain X-Vgai-Key header with a valid APIkey
For <REGION> please fill in the region of your agent, which will be either EU or US.
Method: DELETE
Tries to delete a conversation from the database. If the session id does not exist in the provided date this query will fail.
Parameters:
session_start_time: isoformatted datetime string denoting when the session started.
Example: 2021-01-15T08:09:43.377776
Note: This does not have to be precise, if you know the day in which the session occurred, you can use that day, i.e. 2021-01-15
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
Models
Below is an example model of our insights conversation model. Each conversation will have one such model. Every conversation has a flow path, which is composed of one or more flow steps, each step being a node execution in the agent.
All the fields that are marked with a <> are queryable. If they are wrapped with a “ ” then that means that the field is a string field, otherwise, it’s a number or a boolean.
When you enable "Public Recordings", the Call Recording URL received through the Insights API, will be available publicly. Once queried, simply take the audio URL and paste it into your browser's address bar.
You will find the audio URL in the response as displayed below:
