Typebot Integration

Typebot is a powerful open-source chatbot builder that lets you create advanced conversational flows with a visual interface. You can integrate Typebot with Evolution API to deliver these flows through WhatsApp.

What is Typebot?

Typebot allows you to build chatbots with a drag-and-drop interface, supporting:

Interactive conversation flows
Form collection and validation
Conditional logic and branching
Webhook integrations
Variable management
Multi-language support

Enable Typebot Integration

Add these environment variables to your .env file:

# Enable Typebot integration
TYPEBOT_ENABLED=true

# API version: "old" or "latest"
TYPEBOT_API_VERSION=latest

The TYPEBOT_API_VERSION determines which Typebot API endpoint format is used. Use “latest” for newer Typebot versions (v2.0+).

Configuration Settings

Create Default Settings

Before creating Typebot bots, configure default behavior settings for your instance.

curl -X POST https://your-api.com/typebot/settings/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "I did not understand your message.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10,
    "ignoreJids": [],
    "typebotIdFallback": ""
  }'

Settings Parameters

expire

number

required

Session expiration time in seconds. Default: 300 (5 minutes)

keywordFinish

string

required

Keyword to terminate the bot session. Example: “#EXIT”, “bye”

delayMessage

number

required

Delay in milliseconds between messages. Default: 1000

unknownMessage

string

required

Message sent when bot doesn’t understand user input

listeningFromMe

boolean

required

Whether bot responds to messages sent by the instance owner

stopBotFromMe

boolean

required

Whether instance owner can stop the bot session

keepOpen

boolean

required

Keep session open after completion. Default: false

debounceTime

number

required

Seconds to wait before processing rapid messages. Default: 10

ignoreJids

array

required

List of JIDs (phone numbers) to ignore

typebotIdFallback

string

Fallback Typebot ID to use when primary bot fails

Create a Typebot Bot

Configure your Typebot

Create and configure your bot flow in your Typebot instance. Note the Typebot URL and bot ID.

Create bot in Evolution API

Test the integration

Send a message matching your trigger to start the Typebot conversation.

curl -X POST https://your-api.com/typebot/create/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Customer Support Bot",
    "url": "https://typebot.yourdomain.com",
    "typebot": "my-bot-id-abc123",
    "triggerType": "keyword",
    "triggerOperator": "equals",
    "triggerValue": "support",
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "Sorry, I did not understand.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10
  }'

Request Parameters

enabled

boolean

required

Enable or disable this bot

description

string

required

Description of the bot purpose

url

string

required

Your Typebot instance URL (e.g., “https://typebot.yourdomain.com”)

typebot

string

required

Your Typebot flow ID from the Typebot dashboard

triggerType

string

required

Trigger type: “all”, “keyword”, or “advanced”

triggerOperator

string

For keyword triggers: “equals”, “contains”, “startsWith”, “endsWith”, “regex”

triggerValue

string

The keyword or regex pattern to trigger this bot

Trigger Types

All Messages

Respond to every message (only one “all” trigger allowed per instance):

{
  "triggerType": "all"
}

Keyword Trigger

Trigger based on specific keywords:

{
  "triggerType": "keyword",
  "triggerOperator": "equals",
  "triggerValue": "help"
}

Available operators:

equals - Exact match
contains - Contains the keyword
startsWith - Message starts with keyword
endsWith - Message ends with keyword
regex - Regular expression match

Advanced Trigger

Use regex for complex pattern matching:

{
  "triggerType": "advanced",
  "triggerValue": "^(hello|hi|hey)\\s"
}

Start Typebot from API

You can programmatically start a Typebot session for a specific contact:

curl -X POST https://your-api.com/typebot/start/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "[email protected]",
    "url": "https://typebot.yourdomain.com",
    "typebot": "my-bot-id-abc123",
    "startSession": true,
    "variables": [
      {
        "name": "customerName",
        "value": "John Doe"
      },
      {
        "name": "ticketId",
        "value": "TICKET-12345"
      }
    ]
  }'

remoteJid

string

required

WhatsApp JID of the recipient (format: [email protected])

startSession

boolean

required

Set to true to start a new session

variables

array

Prefilled variables to pass to Typebot flow

Update Typebot Bot

Modify an existing Typebot configuration:

curl -X PUT https://your-api.com/typebot/update/{instance}/{botId} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Updated Support Bot",
    "triggerValue": "help"
  }'

Delete Typebot Bot

Remove a Typebot bot from your instance:

curl -X DELETE https://your-api.com/typebot/delete/{instance}/{botId} \
  -H "apikey: your-api-key"

Fetch Typebot Bots

Retrieve all Typebot bots configured for your instance:

curl -X GET https://your-api.com/typebot/fetch/{instance} \
  -H "apikey: your-api-key"

Session Management

Change Session Status

Update the status of an active Typebot session:

curl -X POST https://your-api.com/typebot/changeStatus/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "[email protected]",
    "status": "closed"
  }'

Fetch Sessions

Get all active Typebot sessions:

curl -X GET https://your-api.com/typebot/fetchSessions/{instance} \
  -H "apikey: your-api-key"

Webhooks

Evolution API emits Typebot-specific webhook events:

TYPEBOT_START

Triggered when a Typebot session begins:

{
  "event": "typebot.start",
  "instance": "my-instance",
  "data": {
    "remoteJid": "[email protected]",
    "url": "https://typebot.yourdomain.com",
    "typebot": "my-bot-id",
    "variables": {},
    "sessionId": "session-123"
  }
}

TYPEBOT_CHANGE_STATUS

Triggered when session status changes:

{
  "event": "typebot.changeStatus",
  "instance": "my-instance",
  "data": {
    "remoteJid": "[email protected]",
    "status": "closed"
  }
}

Enable these events in your .env:

WEBHOOK_EVENTS_TYPEBOT_START=true
WEBHOOK_EVENTS_TYPEBOT_CHANGE_STATUS=true

Use Cases

Customer Support Automation

Create interactive support flows that:

Collect customer information
Categorize support requests
Route to appropriate departments
Provide automated responses to common questions

Lead Qualification

Build conversational flows to:

Qualify potential leads
Collect contact information
Schedule appointments
Send information to your CRM

Survey and Feedback Collection

Design surveys that:

Collect user feedback
Measure customer satisfaction
Gather product insights
Export data for analysis

Order Processing

Implement order flows that:

Display product catalogs
Process orders and payments
Confirm delivery details
Send order confirmations

Best Practices

Keep session expiration times reasonable (5-15 minutes) to prevent stale sessions from consuming resources.

Use the debounceTime setting to handle users who send multiple rapid messages, preventing duplicate processing.

Design clear exit points: Always provide users with a clear way to exit the bot (keyword finish)
Test your flows: Thoroughly test Typebot flows before deploying to production
Use variables: Leverage prefilled variables to personalize conversations
Monitor sessions: Regularly check active sessions and clean up stale ones
Handle errors gracefully: Configure meaningful unknown messages for better user experience

Troubleshooting

Bot not responding to messages

Verify TYPEBOT_ENABLED=true in your environment
Check that the bot is enabled (enabled: true)
Ensure trigger conditions match the incoming message
Verify Typebot URL is accessible from Evolution API server
Check that only one “all” trigger exists if using that type

Session expires too quickly

Increase the expire value in settings (in seconds)
Set keepOpen: true if you want sessions to persist
Check that users aren’t triggering the keyword finish accidentally

Duplicate messages being sent

Increase debounceTime to wait longer before processing messages
Check that you don’t have multiple bots with overlapping triggers
Verify listeningFromMe is set correctly based on your needs

Chatwoot - Customer support platform
OpenAI - AI-powered conversational bots
Dify - LLM application platform

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

Typebot Integration

Typebot Integration

What is Typebot?

Enable Typebot Integration

Configuration Settings

Create Default Settings

Settings Parameters

Create a Typebot Bot

Request Parameters

Trigger Types

All Messages

Keyword Trigger

Advanced Trigger

Start Typebot from API

Update Typebot Bot

Delete Typebot Bot

Fetch Typebot Bots

Session Management

Change Session Status

Fetch Sessions

Webhooks

TYPEBOT_START

TYPEBOT_CHANGE_STATUS

Use Cases

Best Practices

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

​Typebot Integration

​What is Typebot?

​Enable Typebot Integration

​Configuration Settings

​Create Default Settings

​Settings Parameters

​Create a Typebot Bot

​Request Parameters

​Trigger Types

​All Messages

​Keyword Trigger

​Advanced Trigger

​Start Typebot from API

​Update Typebot Bot

​Delete Typebot Bot

​Fetch Typebot Bots

​Session Management

​Change Session Status

​Fetch Sessions

​Webhooks

​TYPEBOT_START

​TYPEBOT_CHANGE_STATUS

​Use Cases

​Best Practices

​Troubleshooting

​Related Integrations

Build docs developers (and LLMs) love

Typebot Integration

What is Typebot?

Enable Typebot Integration

Configuration Settings

Create Default Settings

Settings Parameters

Create a Typebot Bot

Request Parameters

Trigger Types

All Messages

Keyword Trigger

Advanced Trigger

Start Typebot from API

Update Typebot Bot

Delete Typebot Bot

Fetch Typebot Bots

Session Management

Change Session Status

Fetch Sessions

Webhooks

TYPEBOT_START

TYPEBOT_CHANGE_STATUS

Use Cases

Best Practices

Troubleshooting

Related Integrations