/intents

Overview

The intents endpoint is used to create, retrieve, update, and delete intent objects. Intents convert a number of user expressions or patterns into an action. An action is essentially an extraction of the user command or sentence semantics.

See Intents Overview for detailed information on intents.

URLs and Objects

The following URLs are available:

URL Definition
GET /intents Retrieves a list of all intents for the agent.
GET /intents/{id} Retrieves the specified intent.
POST /intents Creates a new intent.
PUT /intents/{id} Updates the specified intent.
DELETE /intents/{id} Deletes the specified intent.

The intent object contains information on which action to return, based on contexts and parameters.

GET /intents

Retrieves a list of all intents for the agent.

GET /intents Sample Request

The following request returns all intents for the agent that is associated with the access token.

GET https://api.api.ai/v1/intents?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN

GET /intents Sample cURL Request

curl -k -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" "https://api.api.ai/v1/intents?v=20150910"

GET /intents Response

The response will be a JSON object that is an array of objects with the following fields:

Name Type Description
id String ID of the intent.
name String Name of the intent.
contextIn Array of context names List of input contexts. These contexts serve as a prerequisite for this intent to be triggered.
contextOut Array of context names List of output contexts that are set after this intent is executed.
name String The name of the output context.
lifespan Number The number of queries this context will remain active after being invoked.
actions Array of strings List of actions set by all responses of this intent.
parameters Array of objects List of parameters for the action.
name String The name of the parameter.
value String The value of the parameter.
defaultValue String The default value of the parameter that should be returned when the "value" field returns an empty value.
required Boolean true if the action cannot be completed without collecting this parameter value. false otherwise.
dataType String Entity name prefixed with @. This field is mandatory if the parameter is required.
prompts Array of strings Questions that the agent will ask in order to collect a value for a required parameter.
priority Number Intent priority.
fallbackIntent Boolean true if this is a fallback intent. false if it is a regular intent.

GET /intents Sample Response

This example shows the JSON response to a GET /intents request. It represents an array of two intent objects corresponding to the intents titled "hobby" and "greetings".

[
   {
      "id": "8ce9a60f-4a1e-468c-9718-5030de11eb91",
      "name": "hobby",
      "contextIn": [
         "hobby"
      ],
      "parameters": [
         {
            "dataType": "@hobby",
            "name": "hobby",
            "value": "$hobby"
         }
      ],
      "contextOut": [
         {
            "name": "hobby",
            "lifespan": 0
         }
      ],
      "actions": [
         "hobby"
      ],
      "priority": 500000,
      "fallbackIntent": false
   },
   {
      "id": "c261cb5f-4b31-4390-af4a-1e58620d462c",
      "name": "greetings",
      "contextIn": [
         "greetings"
      ],
      "parameters": [
         {
            "required": true,
            "dataType": "@sys.given-name",
            "name": "name",
            "value": "$name",
            "prompts": [
               "Hi! What is your name?"
            ]
         },
         {
            "dataType": "@sys.number",
            "name": "age",
            "value": "$age",
            "prompts": [],
            "defaultValue": "unknown"
         }
      ],
      "contextOut": [
         {
            "name": "greetings",
            "lifespan": 10
         },
         {
            "name": "hobby",
            "lifespan": 5
         }
      ],
      "actions": [
         "greetings"
      ],
      "priority": 500000,
      "fallbackIntent": false
   }
]

GET /intents/{id}

Retrieves the specified intent.

{id} is the ID of the intent to retrieve.

GET /intents/{id} Sample Request

The following request returns the intent with ID of 33868522-5747-4a31-88fb-3cd13bd18684.

GET https://api.api.ai/v1/intents/1502edd3-e0be-4a4b-97f1-950550fbfcc3?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN

GET /intents/{id} Sample cURL Request

curl -k -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" "https://api.api.ai/v1/intents/1502edd3-e0be-4a4b-97f1-950550fbfcc3?v=20150910"

GET /intents/{id} Response

The response is an intent object.

POST /intents

Creates a new intent.

POST /intents Request

The POST body is an intent object without the "id" element.

POST /intents Sample Request

The following request creates an intent for setting the state of an appliance using the entities @appliance and @state.

POST https://api.api.ai/v1/intents?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json; charset=utf-8

POST body:
{
   "name": "change appliance state",
   "auto": true,
   "contexts": [],
   "templates": [
      "turn @state:state the @appliance:appliance ",
      "switch the @appliance:appliance @state:state "
   ],
   "userSays": [
      {
         "data": [
            {
               "text": "turn "
            },
            {
               "text": "on",
               "alias": "state",
               "meta": "@state"
            },
            {
               "text": " the "
            },
            {
               "text": "kitchen lights",
               "alias": "appliance",
               "meta": "@appliance"
            }
         ],
         "isTemplate": false,
         "count": 0
      },
      {
         "data": [
            {
               "text": "switch the "
            },
            {
               "text": "heating",
               "alias": "appliance",
               "meta": "@appliance"
            },
            {
               "text": " "
            },
            {
               "text": "off",
               "alias": "state",
               "meta": "@state"
            }
         ],
         "isTemplate": false,
         "count": 0
      }
   ],
   "responses": [
      {
         "resetContexts": false,
         "action": "set-appliance",
         "affectedContexts": [
            {
               "name": "house",
               "lifespan": 10
            }
         ],
         "parameters": [
            {
               "dataType": "@appliance",
               "name": "appliance",
               "value": "\$appliance"
            },
            {
               "dataType": "@state",
               "name": "state",
               "value": "\$state"
            }
         ],
         "speech": "Turning the \$appliance \$state\!"
      }
   ],
   "priority": 500000
}

POST /intents Sample cURL Request

curl -k -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" --data "{'name':'change appliance state 1','auto':true,'contexts':[],'templates':['turn @state:state the @appliance:appliance ','switch the @appliance:appliance @state:state '],'userSays':[{'data':[{'text':'turn '},{'text':'on','alias':'state','meta':'@state'},{'text':' the '},{'text':'bug report','alias':'report','meta':'@report'}],'isTemplate':false,'count':0},{'data':[{'text':'switch the '},{'text':'heating','alias':'appliance','meta':'@appliance'},{'text':' '},{'text':'off','alias':'state','meta':'@state'}],'isTemplate':false,'count':0}],'responses':[{'resetContexts':false,'action':'set-appliance','affectedContexts':[{'name':'house','lifespan':10}],'parameters':[{'dataType':'@appliance','name':'appliance','value':'\$appliance'},{'dataType':'@state','name':'state','value':'\$state'}],'speech':'Turning the \$appliance \$state\!'}],'priority':500000}" "https://api.api.ai/v1/intents?v=20150910"

POST /intents Response

POST /intents response has the following fields:

Name Type Description
id String The ID of the new intent.
status Status object Contains data on how the request succeeded or failed.

POST /intents Sample Response

{
  "id": "613de225-65b2-4fa8-9965-c14ae7673826",
  "status": {
    "code": 200,
    "errorType": "success"
  }
}

PUT /intents/{id}

Updates the specified intent.

{id} is the ID of the intent to update.

PUT /intents/{id} Request

The PUT body is an intent object.

PUT /intents/{id} Sample Request

The following request updates the intent of ID 613de225-65b2-4fa8-9965-c14ae7673826, changing its name to "set appliance on or off".

PUT https://api.api.ai/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json; charset=utf-8

PUT body:
{
   "name": "set appliance on or off",
   "auto": true,
   "contexts": [],
   "templates": [
      "turn @state:state the @appliance:appliance ",
      "switch the @appliance:appliance @state:state "
   ],
   "userSays": [
      {
         "data": [
            {
               "text": "turn "
            },
            {
               "text": "on",
               "alias": "state",
               "meta": "@state"
            },
            {
               "text": " the "
            },
            {
               "text": "kitchen lights",
               "alias": "appliance",
               "meta": "@appliance"
            }
         ],
         "isTemplate": false,
         "count": 0
      },
      {
         "data": [
            {
               "text": "switch the "
            },
            {
               "text": "heating",
               "alias": "appliance",
               "meta": "@appliance"
            },
            {
               "text": " "
            },
            {
               "text": "off",
               "alias": "state",
               "meta": "@state"
            }
         ],
         "isTemplate": false,
         "count": 0
      }
   ],
   "responses": [
      {
         "resetContexts": false,
         "action": "set-appliance",
         "affectedContexts": [
            {
               "name": "house",
               "lifespan": 10
            }
         ],
         "parameters": [
            {
               "dataType": "@appliance",
               "name": "appliance",
               "value": "\$appliance"
            },
            {
               "dataType": "@state",
               "name": "state",
               "value": "\$state"
            }
         ],
         "speech": "Turning the \$appliance \$state\!"
      }
   ],
   "priority": 500000
}

PUT /intents/{id} Sample cURL request

curl -k -X PUT -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" --data "{'name':'set appliance on or off','auto':true,'contexts':[],'templates':['turn @state:state the @appliance:appliance ','switch the @appliance:appliance @state:state '],'userSays':[{'data':[{'text':'turn '},{'text':'on','alias':'state','meta':'@state'},{'text':' the '},{'text':'kitchen lights','alias':'appliance','meta':'@appliance'}],'isTemplate':false,'count':0},{'data':[{'text':'switch the '},{'text':'heating','alias':'appliance','meta':'@appliance'},{'text':' '},{'text':'off','alias':'state','meta':'@state'}],'isTemplate':false,'count':0}],'responses':[{'resetContexts':false,'action':'set-appliance','affectedContexts':[{'name':'house','lifespan':10}],'parameters':[{'dataType':'@appliance','name':'appliance','value':'\$appliance'},{'dataType':'@state','name':'state','value':'\$state'}],'speech':'Turning the \$appliance \$state\!'}],'priority':500000}" "https://api.api.ai/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910"

PUT /intents/{id} Response

Name Type Description
status Status object Contains data on how the request succeeded or failed.

DELETE /intents/{id}

Deletes the specified intent.

{id} is the ID of the intent to delete.

DELETE /intents/{id} Sample Request

The following request deletes the intent of ID 613de225-65b2-4fa8-9965-c14ae7673826.

DELETE https://api.api.ai/v1/intents/80f817e8-23fb-4e8e-ba62-eca1fcef7c3a?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN

DELETE /intents/{id} Sample cURL Request

curl -k -X DELETE -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" "https://api.api.ai/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910"

DELETE /intents/{id} Response

Name Type Description
status Status object Contains data on how the request succeeded or failed.

Intent Object

The intent JSON object contains information about intent. It has the following fields:

Name Type Description
id String A unique identifier for the intent.
name String The name of the intent.
auto Boolean true if Machine learning is on in this intent.
false if Machine learning is off in this intent.
contexts Array of context names A list of contexts required in order for this intent to be triggered (input contexts).
templates Array of strings Array of templates this intent will match. Each template is a string that may contain legal names corresponding to words and phrases, entity names prefixed with @, accompanied or not by aliases. In addition to alphanumerical characters, it may contain the symbols ? and ,.
userSays Array of objects Each object corresponds to one example/template from the 'User says' field in the UI.
id String The id of the example/template.
data Array of objects Information about the text of the example/template and its annotation.
text String Text corresponding to the entire example/template (for examples without annotation and templates) or to one of example's parts (only for annotated examples).
meta String Entity name prefixed with @. This field is required for the annotated part of the text and applies only to examples.
alias String Parameter name for the annotated part of example.
userDefined Boolean true if the text was annotated by developer.
false in the case of automatic annotation.
isTemplate Boolean true for template mode.
false for example mode.
count Number Equals to n-1 where n indicates how many times this example/template was added to this intent.
responses Array of objects A list of responses for this intent.
action String The name of the action.
resetContexts Boolean true indicates that all contexts will be reset when this intent is triggered. Otherwise the value is false.
affectedContexts Array of objects A list of contexts that are activated when this intent is triggered (output contexts).
name String The name of the context.
lifespan Number Indicates the number of requests the context will be active until expired.
parameters Array of objects A list of parameters for the action.
name String The name of the parameter.
value String The value of the parameter. It can be:
  • a constant string
  • a variable defined as the parameter name prefixed with $. Example: $date
  • original value defined as $parameter_name.original
  • a value from a context defined as #context_name.parameter_name
defaultValue String Default value to use when the "value" field returns an empty value.
Default value can be extracted from a context by using the format #context_name.parameter_name.
required Boolean true if the action cannot be completed without collecting this parameter value. false otherwise.
dataType String Entity name prefixed with @. This field is mandatory if the parameter is required.
prompts Array of strings Questions that the agent will ask in order to collect a value for a required parameter.
isList Boolean If true, the parameter value will be returned as a list.
If false, the parameter value can be a string, number, or object.
messages Array of objects Agent response corresponding to the 'Response' field in the UI. Array of message objects
priority Number Intent priority.
webhookUsed Boolean true if webhook is enabled in the agent and in the intent. false otherwise.
webhookForSlotFilling Boolean true if webhook is enabled for the intent required parameters. false otherwise.
fallbackIntent Boolean true if this is a fallback intent. false if it is a regular intent.
cortanaCommand Object Object containing optional values for Cortana integration.
navigateOrService String "NAVIGATE" – for a page that the app should navigate to when it launches
"SERVICE" – for an app service name that must handle voice command.
target String Page or service name.
events Array Array containing event objects.
name String Event name.

Message objects

Text response message object

Name Type Description
type Number Equals to 0 for the Text response message type.
speech String or Array Agent's text response(s). String in case of one variation per one 'Text response' element, array of strings in case of multiple variations. Line breaks (\n) are currently supported for Facebook Messenger, Kik, Slack, and Telegram one-click integrations.

Image message object

Name Type Description
type Number Equals to 3 for the Image message type.
imageUrl String Public URL to the image file.

Card message object

Name Type Description
type Number Equals to 1 for the Card message type.
title Strig Card title.
subtitle String Card subtitle.
buttons Array Array of objects corresponding to card buttons.
text String Button text.
postback String A text sent back to API.AI or a URL to open.

Quick replies message object

Name Type Description
type Number Equals to 2 for the Quick replies message type.
title String Quick replies title. Required for the Facebook Messenger, Kik, and Telegram one-click integrations.
replies Array Array of strings corresponding to quick replies.

Custom payload message object

Name Type Description
type Number Equals to 4 for the Custom payload message type.
payload Object Developer defined JSON. It is sent without modifications.

Sample Intent Object

The following intent will be triggered if the context "greetings" has been already activated and if a user says phrases like "Hi", "Hi, my name is Lucy", "Hi, I am Bob and I'm 15", or similar.

If the parameter "name" value was not provided by the user in the first phrase, the agent will ask to inform it: "Hi! What is your name?" since the property "required" for the parameter "name" is defined as true.

If the age was not provided by the user, the "age" parameter value will be returned as unknown (as defined in the "defaultValue" field).

{
  "id": "51ee06e9-9ff5-428b-aafd-733bbd7e9978",
  "name": "greetings",
  "auto": true,
  "contexts": [
    "greetings"
  ],
  "templates": [
    "hi I am @sys.given-name:name and I am @sys.number:age ",
    "hi my name is @sys.given-name:name and yours",
    "hi"
  ],
  "userSays": [
    {
      "id": "a4fd3a1d-fa7b-4b45-8fb8-f8b1f556872d",
      "data": [
        {
          "text": "hi I am "
        },
        {
          "text": "Alex",
          "alias": "name",
          "meta": "@sys.given-name",
          "userDefined": false
        },
        {
          "text": " and I am "
        },
        {
          "text": "15",
          "alias": "age",
          "meta": "@sys.number",
          "userDefined": false
        }
      ],
      "isTemplate": false,
      "count": 1
    },
    {
      "id": "e16ec309-e2b2-4218-b515-d90832ca74e3",
      "data": [
        {
          "text": "hi my name is "
        },
        {
          "text": "Sam",
          "alias": "name",
          "meta": "@sys.given-name",
          "userDefined": false
        },
        {
          "text": " and yours"
        }
      ],
      "isTemplate": false,
      "count": 1
    },
    {
      "id": "4d2c6dcc-6b8d-47b5-bc68-39b4f5aa1184",
      "data": [
        {
          "text": "hi"
        }
      ],
      "isTemplate": false,
      "count": 0
    }
  ],
  "responses": [
    {
      "resetContexts": false,
      "action": "greetings",
      "affectedContexts": [],
      "parameters": [
        {
          "required": true,
          "dataType": "@sys.given-name",
          "name": "name",
          "value": "$name",
          "defaultValue": "unknown"
          "prompts": [
            "Hi! What is your name?"
          ],
          "isList": false
        },
        {
          "dataType": "@sys.number",
          "name": "age",
          "value": "$age",
          "isList": false
        }
      ],
      "messages": [
        {
          "type": 0,
          "speech": "Hi! Nice to meet you, $name! What is your hobby?"
        }
      ]
    }
  ],
  "priority": 500000,
  "cortanaCommand": {
    "navigateOrService": "NAVIGATE",
    "target": ""
  },
  "webhookUsed": false,
  "fallbackIntent": false
}