API interactions

If you are not using one of the integration options, you must write code that directly interacts with the end-user. You must also directly interact with Dialogflow's API for each conversational turn to send end-user expressions and receive intent matches. The following diagram shows the processing flow when interacting with the API.

Diagram showing flow for API
  1. The end-user types or speaks an expression.
  2. Your service sends this end-user expression to Dialogflow in a detect intent request message.
  3. Dialogflow sends a detect intent response message to your service. This message contains information about the matched intent, the action, the parameters, and the response defined for the intent.
  4. Your service performs actions as needed, like database queries or external API calls.
  5. Your service sends a response to the end-user.
  6. The end-user sees or hears the response.

Project setup and authentication

Before calling the API, you need to set up a GCP project and authentication. You can follow the steps in the Setup quickstart.

Agent building

In most cases you should use the Dialogflow ES Console (visit documentation, open console) to build agents. You can follow the steps in the console quickstart page to create an agent. You can also use the Dialogflow API to build agents for advanced scenarios. Many concept pages focus on using the console to build agents, but they also provide links to relevant API types.

REST, gRPC, and client libraries

You can access the Dialogflow API via REST, gRPC, or one of the provided client libraries. For the details on these options, see the API usage overview.


A session represents a conversation between a Dialogflow agent and an end-user. You create a session at the beginning of a conversation and use it for each turn of the conversation. Once the conversation has ended, you discontinue using the session.

You should not use the same session for concurrent conversations with different end-users. Dialogflow maintains the currently active contexts for each active session. Session data is stored by Dialogflow for 20 minutes.

Each session is determined unique by a session ID generated by your system. You create a new session by providing a new session ID in a detect intent request. A session ID is a string of at most 36 bytes in size. Your system is responsible for generating unique session IDs. They can be random numbers, hashed end-user identifiers, or any other values that are convenient for you to generate.

Detect intent

When you use the API for interactions, your service interacts directly with the end-user. For each conversational turn, your service sends end-user expressions to Dialogflow by calling the detectIntent or streamingDetectIntent method of the Sessions type. Dialogflow responds with information about the matched intent, the action, the parameters, and the response defined for the intent. Your service performs actions as needed (for example, database queries or external API calls) and sends a message to the end-user. This process continues until the conversation has ended.

You can find examples of calling detect intent in the API quickstart page and the how-to pages.