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.