Dialogflow Integration
Integrate Google Dialogflow ES (Essentials) with BuilderBot to add natural language understanding to your chatbot conversations.
Installation
Install the package
Install the Dialogflow context package:npm install @builderbot/contexts-dialogflow
Install Google Cloud dependencies
The package requires Google Cloud Dialogflow SDK:npm install @google-cloud/dialogflow
This dependency is included automatically when you install @builderbot/contexts-dialogflow
Get Google Cloud credentials
- Go to Google Cloud Console
- Create or select a project
- Enable the Dialogflow API
- Create a service account
- Download the JSON key file
- Save it as
google-key.json in your project root
Configuration
Setup Google Credentials
Place your google-key.json file in your project root directory:
{
"type": "service_account",
"project_id": "your-project-id",
"private_key_id": "key-id",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
"client_email": "[email protected]",
"client_id": "123456789",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/..."
}
Never commit google-key.json to version control. Add it to your .gitignore file.
Initialize Dialogflow Context
Create an instance of DialogFlowContext in your bot:
const { createBot, createProvider, createFlow } = require('@builderbot/bot')
const { DialogFlowContext } = require('@builderbot/contexts-dialogflow')
const { MemoryDB } = require('@builderbot/bot')
const { BaileysProvider } = require('@builderbot/provider-baileys')
const main = async () => {
const adapterFlow = createFlow([])
const adapterProvider = createProvider(BaileysProvider)
const adapterDB = new MemoryDB()
// Initialize Dialogflow
const dialogflow = new DialogFlowContext(
adapterDB,
adapterProvider,
{
language: 'es' // Set your language code
}
)
const bot = await createBot({
flow: adapterFlow,
provider: adapterProvider,
database: adapterDB,
})
}
main()
Configuration Options
Language code for Dialogflow agent (e.g., ‘en’, ‘es’, ‘fr’, ‘pt’)
Usage
Handle Messages with Dialogflow
Process incoming messages through Dialogflow:
const welcomeFlow = addKeyword(['hello', 'hi'])
.addAction(async (ctx, { flowDynamic }) => {
// Send message to Dialogflow
await dialogflow.handleMsg({
from: ctx.from,
body: ctx.body
})
})
Complete Example with Flows
const { createBot, createProvider, createFlow, addKeyword } = require('@builderbot/bot')
const { DialogFlowContext } = require('@builderbot/contexts-dialogflow')
const { MemoryDB } = require('@builderbot/bot')
const { BaileysProvider } = require('@builderbot/provider-baileys')
const main = async () => {
const adapterDB = new MemoryDB()
const adapterProvider = createProvider(BaileysProvider)
// Initialize Dialogflow
const dialogflow = new DialogFlowContext(
adapterDB,
adapterProvider,
{ language: 'es' }
)
// Create flow that uses Dialogflow
const aiFlow = addKeyword(['.*'], { regex: true })
.addAction(async (ctx) => {
await dialogflow.handleMsg({
from: ctx.from,
body: ctx.body
})
})
const adapterFlow = createFlow([aiFlow])
await createBot({
flow: adapterFlow,
provider: adapterProvider,
database: adapterDB,
})
}
main()
Response Types
Dialogflow can send different types of responses:
Text Responses
Simple text messages from Dialogflow intents:
// Dialogflow returns text response
// BuilderBot automatically sends: "Hello! How can I help you?"
Dialogflow Custom Payload
{
"answer": "Here's our product catalog",
"media": "https://example.com/image.jpg",
"buttons": [
{ "body": "View Products" },
{ "body": "Contact Sales" },
{ "body": "Support" }
]
}
Session Management
Dialogflow Context automatically manages user sessions:
- Each user (identified by
from number) gets their own session
- Sessions maintain conversation context
- Dialogflow tracks intents and entities per session
Environment Variables (Optional)
Alternatively, you can use environment variables for credentials:
GOOGLE_KEY_JSON={"type":"service_account","project_id":"..."}
process.env.GOOGLE_KEY_JSON = JSON.stringify(credentials)
TypeScript Support
Full TypeScript definitions are included:
import type {
DialogFlowContextOptions,
MessageContextIncoming,
Credential
} from '@builderbot/contexts-dialogflow'
const options: DialogFlowContextOptions = {
language: 'en'
}
const message: MessageContextIncoming = {
from: '1234567890',
body: 'Hello'
}
Best Practices
- Never commit
google-key.json to version control
- Use environment variables in production
- Restrict service account permissions to only Dialogflow API
- Set the correct language code for your Dialogflow agent
- Ensure Dialogflow agent supports the configured language
- Use language codes like: ‘en’, ‘es’, ‘pt’, ‘fr’, ‘de’
- Wrap
handleMsg calls in try-catch blocks
- Handle missing credentials gracefully
- Monitor Dialogflow API quotas and usage
- Test with various intents in Dialogflow console first
- Verify custom payloads work correctly
- Test session context across multiple messages
Troubleshooting
Error: “No se encontró google-key.json”
Ensure your google-key.json file is in the project root directory.
Dialogflow not responding
- Verify your service account has Dialogflow API access
- Check that the project ID matches your Dialogflow agent
- Ensure the Dialogflow API is enabled in Google Cloud Console
Session issues
Sessions are created per user (from field). If experiencing session problems:
- Verify the
from field is consistent for each user
- Check Dialogflow session timeout settings