Sample
A Sample is the training data for your Assistant.
Samples capture how end users would naturally express a task when speaking or texting. Users may express what they would want to do in many different ways – this training data is what powers the natural language model to understand your user's intent.
All Autopilot REST API resources use the following base URL.
https://autopilot.twilio.com/v1/
Sample properties
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that created the Sample 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. |
task_sid
|
The SID of the Task associated with the resource. |
language
|
The ISO language-country string that specifies the language used for the sample. For example: |
assistant_sid
|
The SID of the Assistant that is the parent of the Task associated with the resource. |
sid
|
The unique string that we created to identify the Sample resource. |
tagged_text
|
The text example of how end users might express the task. The sample can contain Field tag blocks. |
url
|
The absolute URL of the Sample resource. |
source_channel
|
The communication channel from which the sample was captured. Can be: |
Create a Sample resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples
Creates a new Sample for the Task specified with {TaskSid}
Most samples will be words, phrases, or complete sentences that train your Assistant on what input to expect from a user asking for this task. For example, your task is tell-a-joke, you may add samples with the tagged text "joke", "tell a joke", or "I'd like to hear something funny".
We recommend using at least ten samples for any given task: this gives your assistant enough data to begin properly mapping user input to the task.
Samples may also contain tags in curly brackets. The body of the curly bracket must match a valid Field instance resource defined in this sample's task. See Field Tagging below for more information.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the Task associated with the new resource. |
task_sid
Path
|
The SID of the Task associated with the Sample resource to create. |
language
Required
|
The ISO language-country string that specifies the language used for the new sample. For example: |
tagged_text
Required
|
The text example of how end users might express the task. The sample can contain Field tag blocks. |
source_channel
Optional
|
The communication channel from which the new sample was captured. Can be: |
Example 1
Fetch a Sample resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples/{Sid}
Returns the Task Sample instance identified by {SampleSid}
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the Task associated with the resource to fetch. |
task_sid
Path
|
The SID of the Task associated with the Sample resource to create. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Sample resource to fetch. |
Example 1
Read multiple Sample resources
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples
Returns a list of Samples for a given Task specified by{TaskSid}. The list includes paging information.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the Task associated with the resources to read. |
task_sid
Path
|
The SID of the Task associated with the Sample resources to read. |
language
Optional
|
The ISO language-country string that specifies the language used for the sample. For example: |
Example 1
Update a Sample resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples/{Sid}
Updates the specific Sample.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the Task associated with the resource to update. |
task_sid
Path
|
The SID of the Task associated with the Sample resource to update. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Sample resource to update. |
language
Optional
|
The ISO language-country string that specifies the language used for the sample. For example: |
tagged_text
Optional
|
The text example of how end users might express the task. The sample can contain Field tag blocks. |
source_channel
Optional
|
The communication channel from which the sample was captured. Can be: |
Example 1
Delete a Sample resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the Task associated with the resources to delete. |
task_sid
Path
|
The SID of the Task associated with the Sample resource to delete. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Sample resource to delete. |
Example 1
Field Tagging
The Sample's TaggedText allows you to specify what part of the Sample corresponds to a Field if you are leveraging fields on a given task.
Fields are specified within the sample by using bracketed text blocks in the format {field_unique_name}. This enables Autopilot to associate the part of the sample that corresponds with the Field and train the machine learning model to identify that Field.
If using fields in your task, you must create the Fields before creating Samples.
Example 1: tag a single field
In the case your task is talk_to_sales and you have multiple products, you need a Field sales_product. With one of your products being shiny widgets, the TaggedText should look like:
Original Text: "I want to talk to sales about shiny widgets"
Tagged Text: "I want to talk to sales about {sales_product}"
Example 2: tag multiple fields
There can be multiple tags and a mix of tags. Each tag must reference the unique_name of a Field that exists in the same Assistant.
In the case where the task is order_pizza and the Fields are quantity, size, and ingredient, your TaggedText should look like:
Original Text: "I want two large pepperoni pizzas"
Tagged Text: "I want {quantity} {size} {ingredient} pizzas"
Example 3: tag multiple complex fields
You can build more advanced schemas depending on your business needs. For example, if your pizza shop supports split ingredient orders, meaning you can order with different ingredients on each half of the pizza.
Here the task would be order_split_ingredient_pizza and your Fields would be quantity, size, and split_ingredient_1, and split_ingredient_2. Your TaggedText would look like:
Original Text: "i would like a large pizza one half with pepperoni and mushrooms and the other half with vegetarian with anchovies"
Tagged Text: "i would like {quantity} {size} pizza one half with {split_1_ingredient} and {split_1_ingredient} and the other half {split_2_ingredient} and {split_2_ingredient}"
Tagging rules
- Tags cannot be nested.
- Tags cannot reference a non-existent Field.
- Once referenced, Fields cannot be deleted or renamed.
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.
