We’ve changed our name! API.AI is now Dialogflow. Learn more here.

/intents

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.

BaseURL

https://api.dialogflow.com/v1/

Intent JSON object

Name Type Description
auto Boolean `true` if machine learning is enabled. `false` if machine learning is disabled.
contexts Array of objects A list of input contexts required in order for this intent to be triggered.
cortanaCommand Object Contains optional values for the Cortana integration.
- navigateOrService String `NAVIGATE` to define a page the app should navigate to when it launches, `SERVICE` to point to a service name that will handle the voice command.
- target String Page or service name related to `navigateOrService`.
events Array List of events that will trigger this intent.
fallbackIntent Boolean true if this is a fallback intent. false if it is a regular intent.
id String ID of the intent.
lastUpdate Number Unix time stamp for last recorded update to intent.
name String Name of the intent.
priority Number Intent priority.
responses Array of objects This contains key/value pairs and objects related to responses for the intent.
- action String The actions linked to the intent.
- affectedContexts Array of objects List of output contexts activated when intent is triggered.
-- lifespan Number The number of queries this context will remain active after being invoked.
-- name String The name of the output context.
-- parameters Array of key/value pairs These are the parameters being passed through the context.
- defaultResponsePlatforms Array of key/value pairs Keys are platforms like `google` and values are boolean to show which platform response is marked as the default.
- messages Array of objects Contains responses, for all platforms, in object form. More on message objects.
- parameters Array of objects List of parameters for the action.
-- dataType String Entity name prefixed with @. This field is mandatory if the parameter is required.
-- defaultValue String The default value of the parameter that should be returned when the "value" field returns an empty value.
-- isList Boolean Signifies if parameter is a list. Default is `false`.
-- name String The name of the parameter.
-- prompts Array of strings Questions that the agent will ask in order to collect a value for a required parameter.
-- required Boolean true if the action cannot be completed without collecting this parameter value. false otherwise.
-- value String The value of the parameter.
- resetContexts Boolean Indicates if all contexts will be reset when intent is triggered.
templates Array of strings These are the individual list items for the User Says examples in the intent.
userSays Array of objects Data to define User Says examples.
- count Number Equals to n-1 where n indicates how many times this example/template was added to this intent.
- data Object Contains the key/value pairs of information found in the parameter table.
-- alias String This represents the "Parameter Name" in the parameter table.
-- meta String starting with `@` This represents the "Entity" in the parameter table.
-- text String This represents the "Resolved Value" when defining parameters.
-- userDefined Boolean Signifies if User Says example was entered
- id String ID of the User Says example.
- isTemplate Boolean Defines whether User Says example is in template or example mode.
- updated Number Unix time stamp for last update to User Says example.
webhookForSlotFilling Boolean `true` if webhook is enabled for the intent's required parameters.
webhookUsed Boolean `true` if webhook is enabled for the intent.

GET /intents

Retrieves a list of all intents for the agent.

Intents with specific languages can be retrieved by adding the lang parameter and the language/locale code to the request URL.

For example, to get a list of all the intents under the Spanish language you would use the following request URL: https://api.dialogflow.com/v1/intents?v=20150910&lang=es

GET /intents sample

HTTP

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json
    

cURL

curl -X GET \
https://api.dialogflow.com/v1/intents?v=20150910 \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json'
    

GET /intents/{id}

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

One intent is used across all languages/locales and it uses the same name and ID. To retrieve an intent's content for a specific language, add the lang parameter and the language/locale code to the request URL.

For example, to get the Spanish content for a specified intent, you would use the following request URL: https://api.dialogflow.com/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910&lang=es

GET /intents/{id} sample

HTTP

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json
    

cURL

curl -X GET \
'https://api.dialogflow.com/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json'
    

GET responses

POST /intents

The POST request creates a new intent.

When you create an intent in a multi-lingual agent, the same intent is used across all languages. The contents, like User Says examples and responses, are customized per language.

To create an intent and include content for a specific language, add the lang parameter and the language/locale code to the request URL.

For example, to create a new intent and insert the content under the Spanish language, you would use the following request URL: https://api.dialogflow.com/v1/intents?v=20150910&lang=es

POST /intents sample

HTTP

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

POST body:
{
  "contexts": [
    "shop"
  ],
  "events": [],
  "fallbackIntent": false,
  "name": "add-to-list",
  "priority": 500000,
  "responses": [
    {
      "action": "add.list",
      "affectedContexts": [
        {
          "lifespan": 5,
          "name": "shop",
          "parameters": {}
        },
        {
          "lifespan": 5,
          "name": "chosen-fruit",
          "parameters": {}
        }
      ],
      "defaultResponsePlatforms": {
        "google": true
      },
      "messages": [
        {
          "platform": "google",
          "textToSpeech": "Okay. How many $fruit?",
          "type": "simple_response"
        },
        {
          "speech": "Okay how many $fruit?",
          "type": 0
        }
      ],
      "parameters": [
        {
          "dataType": "@fruit",
          "isList": true,
          "name": "fruit",
          "prompts": [
            "I didn't get that. What fruit did you want?"
          ],
          "required": true,
          "value": "$fruit"
        }
      ],
      "resetContexts": false
    }
  ],
  "templates": [
    "@fruit:fruit ",
    "Add @fruit:fruit ",
    "I need @fruit:fruit "
  ],
  "userSays": [
    {
      "count": 0,
      "data": [
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "oranges",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "Add "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "bananas",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "I need "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "apples",
          "userDefined": true
        }
      ]
    }
  ],
  "webhookForSlotFilling": false,
  "webhookUsed": false
}
    

cURL

curl -X POST \
'https://api.dialogflow.com/v1/intents?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '{
  "contexts": [
    "shop"
  ],
  "events": [],
  "fallbackIntent": false,
  "name": "add-to-list",
  "priority": 500000,
  "responses": [
    {
      "action": "add.list",
      "affectedContexts": [
        {
          "lifespan": 5,
          "name": "shop",
          "parameters": {}
        },
        {
          "lifespan": 5,
          "name": "chosen-fruit",
          "parameters": {}
        }
      ],
      "defaultResponsePlatforms": {
        "google": true
      },
      "messages": [
        {
          "platform": "google",
          "textToSpeech": "Okay. How many $fruit?",
          "type": "simple_response"
        },
        {
          "speech": "Okay how many $fruit?",
          "type": 0
        }
      ],
      "parameters": [
        {
          "dataType": "@fruit",
          "isList": true,
          "name": "fruit",
          "prompts": [
            "I didn't get that. What fruit did you want?"
          ],
          "required": true,
          "value": "$fruit"
        }
      ],
      "resetContexts": false
    }
  ],
  "templates": [
    "@fruit:fruit ",
    "Add @fruit:fruit ",
    "I need @fruit:fruit "
  ],
  "userSays": [
    {
      "count": 0,
      "data": [
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "oranges",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "Add "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "bananas",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "I need "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "apples",
          "userDefined": true
        }
      ]
    }
  ],
  "webhookForSlotFilling": false,
  "webhookUsed": false
}'
    

PUT /intents/{id}

Updates the intent related to the provided {id}.

To update language specific content (User Says examples, responses, etc), add the lang parameter and the language/locale code to the request URL.

For example, to update a specified intent and insert the content under the Spanish language, you would use the following request URL: https://api.dialogflow.com/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910&lang=es

PUT /intents/{id} sample

HTTP

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

PUT body:
{
  "contexts": [
    "shop"
  ],
  "events": [],
  "fallbackIntent": false,
  "name": "add-to-list",
  "priority": 500000,
  "responses": [
    {
      "action": "add.list",
      "affectedContexts": [
        {
          "lifespan": 5,
          "name": "shop",
          "parameters": {}
        },
        {
          "lifespan": 5,
          "name": "chosen-fruit",
          "parameters": {}
        }
      ],
      "defaultResponsePlatforms": {
        "google": true
      },
      "messages": [
        {
          "platform": "google",
          "textToSpeech": "Okay. How many $fruit?",
          "type": "simple_response"
        },
        {
          "speech": "Okay how many $fruit?",
          "type": 0
        }
      ],
      "parameters": [
        {
          "dataType": "@fruit",
          "isList": true,
          "name": "fruit",
          "prompts": [
            "I didn't get that. What fruit did you want?"
          ],
          "required": true,
          "value": "$fruit"
        }
      ],
      "resetContexts": false
    }
  ],
  "templates": [
    "@fruit:fruit ",
    "Add @fruit:fruit ",
    "I need @fruit:fruit "
  ],
  "userSays": [
    {
      "count": 0,
      "data": [
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "oranges",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "Add "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "bananas",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "I need "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "apples",
          "userDefined": true
        }
      ]
    }
  ],
  "webhookForSlotFilling": false,
  "webhookUsed": false
}
    

cURL

curl -X PUT \
'https://api.dialogflow.com/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '{
  "contexts": [
    "shop"
  ],
  "events": [],
  "fallbackIntent": false,
  "name": "add-to-list",
  "priority": 500000,
  "responses": [
    {
      "action": "add.list",
      "affectedContexts": [
        {
          "lifespan": 5,
          "name": "shop",
          "parameters": {}
        },
        {
          "lifespan": 5,
          "name": "chosen-fruit",
          "parameters": {}
        }
      ],
      "defaultResponsePlatforms": {
        "google": true
      },
      "messages": [
        {
          "platform": "google",
          "textToSpeech": "Okay. How many $fruit?",
          "type": "simple_response"
        },
        {
          "speech": "Okay how many $fruit?",
          "type": 0
        }
      ],
      "parameters": [
        {
          "dataType": "@fruit",
          "isList": true,
          "name": "fruit",
          "prompts": [
            "I didn't get that. What fruit did you want?"
          ],
          "required": true,
          "value": "$fruit"
        }
      ],
      "resetContexts": false
    }
  ],
  "templates": [
    "@fruit:fruit ",
    "Add @fruit:fruit ",
    "I need @fruit:fruit "
  ],
  "userSays": [
    {
      "count": 0,
      "data": [
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "oranges",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "Add "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "bananas",
          "userDefined": true
        }
      ]
    },
    {
      "count": 0,
      "data": [
        {
          "text": "I need "
        },
        {
          "alias": "fruit",
          "meta": "@fruit",
          "text": "apples",
          "userDefined": true
        }
      ]
    }
  ],
  "webhookForSlotFilling": false,
  "webhookUsed": false
}'
    

DELETE /intents/{id}

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

DELETE /intents/{id} sample

HTTP

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json
    

cURL

curl -X DELETE \
'https://api.dialogflow.com/v1/intents/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json'
    

POST, PUT and DELETE responses