Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

Names in PHP format
accountSid
sid<AC> Not PII

The SID of the Account that created the Sample resource.

dateCreated
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in RFC 2822 format.

dateUpdated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

taskSid
sid<UD> Not PII

The SID of the Task associated with the resource.

language
string Not PII

The ISO language-country string that specifies the language used for the sample. For example: en-US.

assistantSid
sid<UA> Not PII

The SID of the Assistant that is the parent of the Task associated with the resource.

sid
sid<UF> Not PII

The unique string that we created to identify the Sample resource.

taggedText
string Not PII

The text example of how end users might express the task. The sample can contain Field tag blocks.

url
url Not PII

The absolute URL of the Sample resource.

sourceChannel
string Not PII

The communication channel from which the sample was captured. Can be: voice, sms, chat, alexa, google-assistant, slack, or null if not included.

Create a Sample resource

post
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
Names in None format
assistant_sid
Required
post sid_like<UA> Not PII

The SID of the Assistant that is the parent of the Task associated with the new resource.

task_sid
Required
post sid_like<UD> Not PII

The SID of the Task associated with the Sample resource to create.

language
Required
post string Not PII

The ISO language-country string that specifies the language used for the new sample. For example: en-US.

tagged_text
Required
post string Not PII

The text example of how end users might express the task. The sample can contain Field tag blocks.

source_channel
Optional
post string Not PII

The communication channel from which the new sample was captured. Can be: voice, sms, chat, alexa, google-assistant, slack, or null if not included.

Example 1
        
        
        
        

        Fetch a Sample resource

        get
        https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples/{Sid}

        Returns the Task Sample instance identified by {SampleSid}

        Parameters
        Names in None format
        assistant_sid
        Required
        get sid_like<UA> Not PII

        The SID of the Assistant that is the parent of the Task associated with the resource to fetch.

        task_sid
        Required
        get sid_like<UD> Not PII

        The SID of the Task associated with the Sample resource to create.

        sid
        Required
        get sid<UF> Not PII

        The Twilio-provided string that uniquely identifies the Sample resource to fetch.

        Example 1
              
              
              
              

              Read multiple Sample resources

              get
              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
              Names in None format
              assistant_sid
              Required
              get sid_like<UA> Not PII

              The SID of the Assistant that is the parent of the Task associated with the resources to read.

              task_sid
              Required
              get sid_like<UD> Not PII

              The SID of the Task associated with the Sample resources to read.

              language
              Optional
              get string Not PII

              The ISO language-country string that specifies the language used for the sample. For example: en-US.

              Example 1
                    
                    
                    
                    

                    Update a Sample resource

                    post
                    https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples/{Sid}

                    Updates the specific Sample.

                    Parameters
                    Names in None format
                    assistant_sid
                    Required
                    post sid_like<UA> Not PII

                    The SID of the Assistant that is the parent of the Task associated with the resource to update.

                    task_sid
                    Required
                    post sid_like<UD> Not PII

                    The SID of the Task associated with the Sample resource to update.

                    sid
                    Required
                    post sid<UF> Not PII

                    The Twilio-provided string that uniquely identifies the Sample resource to update.

                    language
                    Optional
                    post string Not PII

                    The ISO language-country string that specifies the language used for the sample. For example: en-US.

                    tagged_text
                    Optional
                    post string Not PII

                    The text example of how end users might express the task. The sample can contain Field tag blocks.

                    source_channel
                    Optional
                    post string Not PII

                    The communication channel from which the sample was captured. Can be: voice, sms, chat, alexa, google-assistant, slack, or null if not included.

                    Example 1
                          
                          
                          
                          

                          Delete a Sample resource

                          delete
                          https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Tasks/{TaskSid}/Samples/{Sid}
                          Parameters
                          Names in None format
                          assistant_sid
                          Required
                          delete sid_like<UA> Not PII

                          The SID of the Assistant that is the parent of the Task associated with the resources to delete.

                          task_sid
                          Required
                          delete sid_like<UD> Not PII

                          The SID of the Task associated with the Sample resource to delete.

                          sid
                          Required
                          delete sid<UF> Not PII

                          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.
                                Rate this page:

                                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 browsing the Twilio tag on Stack Overflow.