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

/query

Overview

The query endpoint is used to process natural language in the form of text. The query requests return structured data in JSON format with an action and parameters for that action.

Base URL

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

URLs

The following URLs are available:

Method Definition
GET /query Takes natural language text and information as query parameters and returns information as JSON.
POST /query Takes natural language text and information as JSON in the POST body and returns information as JSON.

Query Parameters and JSON Fields

The following parameters are used as either query parameters in the URL or JSON keys in the POST body:

Name Type Description Required
query String Natural language text to be processed.
Query length should not exceed 256 characters.		 Required unless an "event"/"e" parameter is submitted.
event (for POST)
e (for GET)		 Object Object containing event name and additional data. The "data" parameter can be submitted only in POST requests. Required unless a "query" parameter is submitted.
name String Event name. Required.
data Object Object consisting of "parameter_name":"parameter_value" pairs. Optional.
v String Version of the protocol, e.g. v=20150910
Warning: Do not pass the current date to the v parameter. See Versioning for more details.		 Required. Must be used as a URL parameter.
sessionId String A string token up to 36 symbols long, used to identify the client and to manage session parameters (including contexts) per client. Required.
lang String Language tag, e.g., en, es etc.
See Languages for details.		 Required.
contexts Array Array of additional context objects. Should be sent via a POST /query request. Contexts sent in a query are activated before the query.
See Contexts.		 Optional.
name String Context name. Optional.
parameters Object Object consisting of "parameter_name":"parameter_value" pairs. Optional.
lifespan Number Number of requests after which the context will expire. Optional.
resetContexts Boolean If true, all current contexts in a session will be reset before the new ones are set. False by default. Optional.
entities Array Array of entities that replace developer defined entities for this request only. The entity(ies) need to exist in the developer console. Entities JSON format follows the format used in the /entities endpoint. Optional.
timezone String Time zone from IANA Time Zone Database
Examples: America/New_York, Europe/Paris		 Optional.
location Object Latitude and longitude values.
Example:{"latitude": 37.4256293, "longitude": -122.20539}		 Optional.
latitude Number Latitude value. Optional.
longitude Number Longitude value. Optional.
originalRequest Object Full request coming from the integrated platform (Facebook Messenger, Slack, etc.)
Example: {“originalRequest”:{“source”:”facebook”, “data”:{ … }}		 Optional.
source String Request source name.
Possible values: "google", "facebook", "kik", "slack", "slack_testbot", "line", "skype", "spark", "telegram", "tropo", "twilio", "twilio-ip", "twitter"		 Optional.
data Object Request data. Optional.

GET /query

Takes natural language text and information as query parameters and returns information as JSON.

GET /query Sample Request

The following query processes the word "weather" for the Paris time zone with the contexts of weather and Europe.

GET https://api.dialogflow.com/v1/query?v=20150910&query=weather&timezone=Europe/Paris&lang=en&contexts=weather&contexts=europe&latitude=37.459157&longitude=-122.17926&sessionId=1234567890

Headers:
Authorization: Bearer YOUR_ACCESS_TOKEN

GET /query cURL Sample Request

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://api.dialogflow.com/v1/query?v=20150910&query=weather&timezone=Europe/Paris&lang=en&contexts=weather&contexts=europe&latitude=37.459157&longitude=-122.17926&sessionId=1234567890"

You can use the 'COPY CURL' option to copy a sample query curl request identical to the one sent from the Dialogflow test console.

POST /query

Takes natural language text and information as JSON in the POST body and returns information as JSON.

POST /query Sample Request

The following query sets the context "weather" and processes the phrase "and for tomorrow" for the America/New_York time zone for the English language.

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

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

POST body:
{
    "query": "and for tomorrow",
    "contexts": [{
        "name": "weather",
        "lifespan": 4
    }],
    "location": {
        "latitude": 37.459157,
        "longitude": -122.17926
    },
    "timezone": "America/New_York",
    "lang": "en",
    "sessionId": "1234567890"
}

POST /query cURL Sample Request

curl -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" --data "{'query':'and for tomorrow', 'timezone':'GMT-5', 'lang':'en', 'contexts':[{ 'name': 'weather', 'parameters':{'city': 'London'}, 'lifespan': 4}], 'sessionId':'1234567890'}" "https://api.dialogflow.com/v1/query?v=20150910"

Response

The response will be a JSON object with the following fields:

Name Type Description
id String Unique identifier of the result.
timestamp String Date and time of the request in UTC timezone using ISO-8601 format.
lang String Agent's language.
result Contains the results of the natual language processing.
source String Source of the answer. Could be "agent" if the response was retrieved from the agent.
resolvedQuery String The query that was used to produce this result.
action String An action to take.
Example: turn on
actionIncomplete Boolean true if the triggered intent has required parameters and not all the required parameter values have been collected
false if all required parameter values have been collected or if the triggered intent doesn't containt any required parameters
parameters Object Object consisting of "parameter_name":"parameter_value" pairs.
Example: {"device": "computer"}
contexts Array Array of context objects with the fields "name", "parameters", "lifespan".
name String Context name.
parameters Object Object consisting of "parameter_name":"parameter_value" and "parameter_name.original":"original_parameter_value" pairs.
lifespan Number Number of requests after which the context will expire.
fulfillment Data about text response(s), rich messages, response received from webhook.
speech String Text to be pronounced to the user / shown on the screen
messages Array Array of message objects
score Number between 0 and 1 Matching score for the intent.
metadata Contains data on intents and contexts.
intentId String ID of the intent that produced this result.
webhookUsed String Indicates wheather webhook functionaly is enabled in the triggered intent.
webhookForSlotFillingUsed String Indicates wheather in the triggered intent webhook functionaly is enabled for required parameters.
webhookResponseTime Number Webhook response time in milliseconds.
intentName String Name of the intent that produced this result.
status Status Object Contains data on how the request succeeded or failed.
sessionId String Session ID.

Message objects

Text response message object

Name Type Description
type Number Equals to 0 for the Text response message type.
speech String Agent's text reply. Line breaks are 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 String 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 Dialogflow 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 Response

{
  "id": "b340a1f7-abee-4e13-9bdd-5e8938a48b7d",
  "timestamp": "2017-02-09T15:38:26.548Z",
  "lang": "en",
  "result": {
    "source": "agent",
    "resolvedQuery": "my name is Sam and I live in Paris",
    "action": "greetings",
    "actionIncomplete": false,
    "parameters": {},
    "contexts": [],
    "metadata": {
      "intentId": "9f41ef7c-82fa-42a7-9a30-49a93e2c14d0",
      "webhookUsed": "false",
      "webhookForSlotFillingUsed": "false",
      "intentName": "greetings"
    },
    "fulfillment": {
      "speech": "Hi Sam! Nice to meet you!",
      "messages": [
        {
          "type": 0,
          "speech": "Hi Sam! Nice to meet you!"
        }
      ]
    },
    "score": 1
  },
  "status": {
    "code": 200,
    "errorType": "success"
  },
  "sessionId": "4b6a6779-b8ea-4094-b2ed-a302ba201815"
}