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

/userEntities

Overview

Entities can be redefined on a user (session ID) level. A good scenario could be when you have a @playlist entity that has generic playlist. As playlists are user-specific, @playlist entity could be defined in a request or for a given session. If user entities are submitted via the /userEntities endpoint, they live in the session for 30 minutes.

Base URL

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

User Entity Object

Field name Type Description
sessionId String Session ID for a user.
name Entity Name Name of the entity.
extend boolean A flag identifying whether the additional data should extend or replace the default entity definition.
Optional field. If not defined, the default value is `false`.
entries Array of Entity Entry objects

For example:

{
   "sessionId":"12345",
   "name":"city",
   "extend":false,
   "entries":[
      {
         "value":"New York",
         "synonyms":[
            "New York",
            "Big Apple"
         ]
      }
   ]
}

POST /userEntities

Adds one or multiple user entities for a session.

Entities JSON:

{
   "sessionId":"12345",
   "entities":[
      {
         "name":"city",
         "entries":[
            {
               "value":"New York",
               "synonyms":[
                  "New York",
                  "Big Apple"
               ]
            }
         ]
      },
      {
         "name":"country",
         "entries":[
            {
               "value":"USA",
               "synonyms":[
                  "USA"
               ]
            }
         ]
      }
   ]
}
curl -X POST -k -H "Content-Type: application/json" -H "Authorization: Bearer CLIENT_ACCESS_TOKEN" "https://api.api.ai/v1/userEntities?v=20150910&sessionId=12345" -d @entities.json

PUT /userEntities/{name}

Updates user entity specified by name.

Accepts user entity object.

GET /userEntities/{name}

Gets a user entity object by name.

GET /userEntities/{name} Sample cURL Request

The following request retrieves the user entity object for the @items user entity for the sessionId "12345".

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN" "https://api.api.ai/v1/userEntities/items?v=20150910&sessionId=12345"

DELETE /userEntities/{name}

Deletes a user entity object with a specified name.