/query

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.

BaseURL

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

/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
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.
- lifespan Number Number of requests after which the context will expire. Optional.
- name String Context name. Optional.
- parameters Object Object consisting of "parameter_name":"parameter_value" pairs. 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.
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.
- data Object Object consisting of "parameter_name":"parameter_value" pairs. Optional.
- name String Event name. Required.
lang String Language tag, e.g., en, es etc.
See Languages for details.
Required.
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.
- data Object Request data. Optional.
- source String Request source name. Possible values:
google, facebook, kik, slack, line, skype, spark, telegram, tropo, twilio, twilio-ip, twitter
Optional.
query String Natural language text to be processed. Query length should not exceed 256 characters. Required unless an "event"/"e" parameter is submitted.
resetContexts Boolean If true, all current contexts in a session will be reset before the new ones are set. False by default. Optional.
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.
timezone String Time zone from IANA Time Zone Database Examples:
America/New_York, Europe/Paris
Optional.
v String Version of the protocol, e.g. v=20150910
Warning: Do not pass the current date to the v parameter. See Protocol Version for more details.
Required. Must be used as a URL parameter.

GET /query

Takes parameters or event name provided in URL and returns response as JSON.

GET /query sample

HTTP

GET https://api.dialogflow.com/v1/query?v=20150910&contexts=shop&lang=en&query=apple&sessionId=12345&timezone=America/New_York

Headers:
Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN
    

cURL

curl \
-H "Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN" \
"https://api.dialogflow.com/v1/query?v=20150910&contexts=shop&lang=en&query=apple&sessionId=12345&timezone=America/New_York"
    

POST /query

Takes parameters or event name in JSON format and returns response as JSON.

POST /query sample

HTTP

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

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

  POST body:
  {
    "contexts": [
      "shop"
    ],
    "lang": "en",
    "query": "I need apples",
    "sessionId": "12345",
    "timezone": "America/New_York"
  }
    

cURL

curl \
https://api.dialogflow.com/v1/query?v=20150910 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN' \
-d '{
  "contexts": [
    "shop"
  ],
  "lang": "en",
  "query": "I need apples",
  "sessionId": "12345",
  "timezone": "America/New_York"
}'
    

GET and POST responses

Both GET and POST methods return the same JSON response.