The Twilio Assistant API is designed to help businesses create conversational AI interfaces that enable customers to interact with applications through natural language. The API uses machine learning and natural language processing to understand and respond to user queries, allowing for personalized and automated customer interactions.
components:
schemas:
CreateUnderstandModelBuildRequest:
type: object
properties:
StatusCallback:
type: string
format: uri
description: ''
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long. For
example: v0.1
UpdateUnderstandQueryRequest:
type: object
properties:
SampleSid:
type: string
minLength: 34
maxLength: 34
pattern: ^UF[0-9a-fA-F]{32}$
description: An optional reference to the Sample created from this query.
Status:
type: string
description: >-
A string that described the query status. The values can be:
pending_review, reviewed, discarded
CreateUnderstandQueryRequest:
type: object
required:
- Language
- Query
properties:
Language:
type: string
description: An ISO language-country string of the sample.
Query:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. It can be up to 2048 characters long.
Tasks:
type: string
description: >-
Constraints the query to a set of tasks. Useful when you need to
constrain the paths the user can take. Tasks should be comma
separated *task-unique-name-1*, *task-unique-name-2*
ModelBuild:
type: string
description: The Model Build Sid or unique name of the Model Build to be queried.
Field:
type: string
description: >-
Constraints the query to a given Field with an task. Useful when you
know the Field you are expecting. It accepts one field in the format
*task-unique-name-1*:*field-unique-name*
UpdateUnderstandSampleRequest:
type: object
properties:
Language:
type: string
description: An ISO language-country string of the sample.
TaggedText:
type: string
description: >-
The text example of how end-users may express this task. The sample
may contain Field tag blocks.
SourceChannel:
type: string
description: >-
The communication channel the sample was captured. It can be:
*voice*, *sms*, *chat*, *alexa*, *google-assistant*, or *slack*. If
not included the value will be null
CreateUnderstandSampleRequest:
type: object
required:
- Language
- TaggedText
properties:
Language:
type: string
description: An ISO language-country string of the sample.
TaggedText:
type: string
description: >-
The text example of how end-users may express this task. The sample
may contain Field tag blocks.
SourceChannel:
type: string
description: >-
The communication channel the sample was captured. It can be:
*voice*, *sms*, *chat*, *alexa*, *google-assistant*, or *slack*. If
not included the value will be null
UpdateUnderstandStyleSheetRequest:
type: object
properties:
StyleSheet:
description: The JSON Style sheet string
UpdateUnderstandTaskRequest:
type: object
properties:
FriendlyName:
type: string
description: >-
A user-provided string that identifies this resource. It is
non-unique and can up to 255 characters long.
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
Actions:
description: >-
A user-provided JSON object encoded as a string to specify the
actions for this task. It is optional and non-unique.
ActionsUrl:
type: string
format: uri
description: User-provided HTTP endpoint where from the assistant fetches actions
CreateUnderstandTaskRequest:
type: object
required:
- UniqueName
properties:
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
FriendlyName:
type: string
description: >-
A user-provided string that identifies this resource. It is
non-unique and can up to 255 characters long.
Actions:
description: >-
A user-provided JSON object encoded as a string to specify the
actions for this task. It is optional and non-unique.
ActionsUrl:
type: string
format: uri
description: User-provided HTTP endpoint where from the assistant fetches actions
UpdateUnderstandTaskActionsRequest:
type: object
properties:
Actions:
description: >-
The JSON actions that instruct the Assistant how to perform this
task.
UpdateUnderstandModelBuildRequest:
type: object
properties:
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long. For
example: v0.1
CreateUnderstandFieldValueRequest:
type: object
required:
- Language
- Value
properties:
Language:
type: string
description: An ISO language-country string of the value.
Value:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
SynonymOf:
type: string
description: >-
A value that indicates this field value is a synonym of. Empty if
the value is not a synonym.
CreateUnderstandFieldTypeRequest:
type: object
required:
- UniqueName
properties:
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
FriendlyName:
type: string
description: >-
A user-provided string that identifies this resource. It is
non-unique and can up to 255 characters long.
UpdateUnderstandFieldTypeRequest:
type: object
properties:
FriendlyName:
type: string
description: >-
A user-provided string that identifies this resource. It is
non-unique and can up to 255 characters long.
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
CreateUnderstandFieldRequest:
type: object
required:
- FieldType
- UniqueName
properties:
FieldType:
type: string
description: >-
The unique name or sid of the FieldType. It can be any [Built-in
Field
Type](https://www.twilio.com/docs/assistant/api/built-in-field-types)
or the unique_name or the Field Type sid of a custom Field Type.
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
UpdateUnderstandAssistantInitiationActionsRequest:
type: object
properties:
InitiationActions:
description: ''
UpdateUnderstandAssistantFallbackActionsRequest:
type: object
properties:
FallbackActions:
description: ''
UpdateUnderstandAssistantRequest:
type: object
properties:
FriendlyName:
type: string
description: >-
A text description for the Assistant. It is non-unique and can up to
255 characters long.
LogQueries:
type: boolean
description: >-
A boolean that specifies whether queries should be logged for 30
days further training. If false, no queries will be stored, if true,
queries will be stored for 30 days and deleted thereafter. Defaults
to true if no value is provided.
UniqueName:
type: string
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
CallbackUrl:
type: string
format: uri
description: A user-provided URL to send event callbacks to.
CallbackEvents:
type: string
description: Space-separated list of callback events that will trigger callbacks.
FallbackActions:
description: >-
The JSON actions to be executed when the user's input is not
recognized as matching any Task.
InitiationActions:
description: >-
The JSON actions to be executed on inbound phone calls when the
Assistant has to say something first.
StyleSheet:
description: The JSON object that holds the style sheet for the assistant
model_build_enum_status:
type: string
enum:
- enqueued
- building
- completed
- failed
- canceled
preview.understand.assistant:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Assistant.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated
friendly_name:
type: string
nullable: true
description: >-
A text description for the Assistant. It is non-unique and can up to
255 characters long.
latest_model_build_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UG[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique ID (Sid) of the latest model build. Null if no model has
been built.
links:
type: object
format: uri-map
nullable: true
log_queries:
type: boolean
nullable: true
description: >-
A boolean that specifies whether queries should be logged for 30
days further training. If false, no queries will be stored, if true,
queries will be stored for 30 days and deleted thereafter.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
unique_name:
type: string
nullable: true
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. You can use the unique name in the URL path.
Unique up to 64 characters long.
url:
type: string
format: uri
nullable: true
callback_url:
type: string
format: uri
nullable: true
description: A user-provided URL to send event callbacks to.
callback_events:
type: string
nullable: true
description: Space-separated list of callback events that will trigger callbacks.
preview.understand.assistant.assistant_fallback_actions:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
url:
type: string
format: uri
nullable: true
data:
nullable: true
preview.understand.assistant.assistant_initiation_actions:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
url:
type: string
format: uri
nullable: true
data:
nullable: true
preview.understand.assistant.dialogue:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Field.
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the parent Assistant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UK[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Dialogue
data:
nullable: true
description: The dialogue memory object as json
url:
type: string
format: uri
nullable: true
preview.understand.assistant.task.field:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Field.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated
field_type:
type: string
nullable: true
description: >-
The Field Type of this field. It can be any [Built-in Field
Type](https://www.twilio.com/docs/assistant/api/built-in-field-types)
or the unique_name or sid of a custom Field Type.
task_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UD[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Task associated with this Field.
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the parent Assistant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UE[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
unique_name:
type: string
nullable: true
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
url:
type: string
format: uri
nullable: true
ListUnderstandFieldResponse:
type: object
properties:
fields:
type: array
items:
$ref: '#/components/schemas/preview.understand.assistant.task.field'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
preview.understand.assistant.field_type:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Field Type.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated
friendly_name:
type: string
nullable: true
description: >-
A user-provided string that identifies this resource. It is
non-unique and can up to 255 characters long.
links:
type: object
format: uri-map
nullable: true
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Assistant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UB[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
unique_name:
type: string
nullable: true
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
url:
type: string
format: uri
nullable: true
ListUnderstandFieldTypeResponse:
type: object
properties:
field_types:
type: array
items:
$ref: '#/components/schemas/preview.understand.assistant.field_type'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
preview.understand.assistant.field_type.field_value:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Field Value.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated
field_type_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UB[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Field Type associated with this Field Value.
language:
type: string
nullable: true
description: An ISO language-country string of the value.
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Assistant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UC[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
value:
type: string
nullable: true
description: The Field Value itself.
url:
type: string
format: uri
nullable: true
synonym_of:
type: string
minLength: 34
maxLength: 34
pattern: ^UC[0-9a-fA-F]{32}$
nullable: true
description: >-
A value that indicates this field value is a synonym of. Empty if
the value is not a synonym.
ListUnderstandFieldValueResponse:
type: object
properties:
field_values:
type: array
items:
$ref: >-
#/components/schemas/preview.understand.assistant.field_type.field_value
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
preview.understand.assistant.model_build:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Model Build.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the parent Assistant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UG[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
status:
type: string
$ref: '#/components/schemas/model_build_enum_status'
nullable: true
description: >-
A string that described the model build status. The values can be:
enqueued, building, completed, failed
unique_name:
type: string
nullable: true
description: >-
A user-provided string that uniquely identifies this resource as an
alternative to the sid. Unique up to 64 characters long.
url:
type: string
format: uri
nullable: true
build_duration:
type: integer
nullable: true
description: The time in seconds it took to build the model.
error_code:
type: integer
nullable: true
ListUnderstandModelBuildResponse:
type: object
properties:
model_builds:
type: array
items:
$ref: '#/components/schemas/preview.understand.assistant.model_build'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
preview.understand.assistant.query:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Query.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated
results:
nullable: true
description: >-
The natural language analysis results which include the Task
recognized, the confidence score and a list of identified Fields.
language:
type: string
nullable: true
description: An ISO language-country string of the sample.
model_build_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UG[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Model Build queried.
query:
type: string
nullable: true
description: The end-user's natural language input.
x-twilio:
pii:
handling: standard
deleteSla: 30
sample_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UF[0-9a-fA-F]{32}$
nullable: true
description: An optional reference to the Sample created from this query.
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the parent Assistant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UH[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
status:
type: string
nullable: true
description: >-
A string that described the query status. The values can be:
pending_review, reviewed, discarded
url:
type: string
format: uri
nullable: true
source_channel:
type: string
nullable: true
description: The communication channel where this end-user input came from
ListUnderstandQueryResponse:
type: object
properties:
queries:
type: array
items:
$ref: '#/components/schemas/preview.understand.assistant.query'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
preview.understand.assistant.task.sample:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Sample.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
date_updated:
type: string
format: date-time
nullable: true
description: The date that this resource was last updated
task_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UD[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Task associated with this Sample.
language:
type: string
nullable: true
description: An ISO language-country string of the sample.
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Assistant.
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UF[0-9a-fA-F]{32}$
nullable: true
description: A 34 character string that uniquely identifies this resource.
tagged_text:
type: string
nullable: true
description: >-
The text example of how end-users may express this task. The sample
may contain Field tag blocks.
url:
type: string
format: uri
nullable: true
source_channel:
type: string
nullable: true
description: >-
The communication channel the sample was captured. It can be:
*voice*, *sms*, *chat*, *alexa*, *google-assistant*, or *slack*. If
not included the value will be null
ListUnderstandSampleResponse:
type: object
properties:
samples:
type: array
items:
$ref: '#/components/schemas/preview.understand.assistant.task.sample'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
preview.understand.assistant.style_sheet:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Assistant
assistant_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^UA[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Assistant
url:
type: string
format: uri
nullable: true
data:
nullable: true
description: The JSON style sheet object
preview.understand.assistant.task:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique ID of the Account that created this Task.
date_created:
type: string
format: date-time
nullable: true
description: The date that this resource was created
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twilio/refs/heads/main/openapi/assistant-openapi-original.yml