Query
Twilio Autopilot's Query API resource is the endpoint where Autopilot's natural language understanding analysis is performed.
The Query endpoint takes your user's natural language input (text or speech) and returns structured JSON output with the results.
This resource can behave in two different ways:
- It can be used in a RESTful manner, where POSTing creates a Query instance resource which logs the query that can be reviewed and used as additional training data if posted as a tagged Sample.
- It can also be used in an "ephemeral" mode, where POSTs to the Query resource returns results, but do not create a Query instance resource. You can specify whether to log the queries or not in the LogQuery property of an Assistant.
End-user queries can be a great source of training data. The Query resource not only enables you to log Queries but also keep track of whether a query was already reviewed and used as a Sample or not by updating the status and sample_sid fields.
Samples are not created automatically from Queries. You have to determine the task and tag the Sample with the Fields to create the Sample.
All Autopilot REST API resources use the following base URL:
https://autopilot.twilio.com/v1
Query properties
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that created the Query resource. |
date_created
|
The date and time in GMT when the resource was created specified in RFC 2822 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in RFC 2822 format. |
results
|
The natural language analysis results that include the Task recognized and a list of identified Fields. |
language
|
The ISO language-country string that specifies the language used by the Query. For example: |
model_build_sid
|
The SID of the Model Build queried. |
query
|
The end-user's natural language input. |
sample_sid
|
The SID of an optional reference to the Sample created from the query. |
assistant_sid
|
The SID of the Assistant that is the parent of the resource. |
sid
|
The unique string that we created to identify the Query resource. |
status
|
The status of the Query. Can be: |
url
|
The absolute URL of the Query resource. |
source_channel
|
The communication channel from where the end-user input came. |
dialogue_sid
|
The SID of the Dialogue. |
Create a Query resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Queries
Creates a Query against the Model Build for the Assistant identified by {AssistantSid}.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the new resource. |
language
Required
|
The ISO language-country string that specifies the language used for the new query. For example: |
query
Required
|
The end-user's natural language input. It can be up to 2048 characters long. |
tasks
Optional
|
The list of tasks to limit the new query to. Tasks are expressed as a comma-separated list of task |
model_build
Optional
|
The SID or unique name of the Model Build to be queried. |
Example 1
Fetch a Query resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Queries/{Sid}
Returns the Query instance identified by {QuerySid}.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resource to fetch. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Query resource to fetch. |
Example 1
Read multiple Query resources
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Queries
Returns a list of Queries for this Assistant. The list returned includes paging information.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resources to read. |
language
Optional
|
The ISO language-country string that specifies the language used by the Query resources to read. For example: |
model_build
Optional
|
The SID or unique name of the Model Build to be queried. |
status
Optional
|
The status of the resources to read. Can be: |
dialogue_sid
Optional
|
The SID of the Dialogue. |
Example 1
Update a Query resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Queries/{Sid}
Updates the Query identified by {QuerySid}.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resource to update. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Query resource to update. |
sample_sid
Optional
|
The SID of an optional reference to the Sample created from the query. |
status
Optional
|
The new status of the resource. Can be: |
Example 1
Delete a Query resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Queries/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resources to delete. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Query resource to delete. |
Example 1
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
