> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

# Typebot Integration

> Connect Typebot chatbot builder to WhatsApp through Evolution API for interactive conversational flows

# 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:

```bash theme={null}
# Enable Typebot integration
TYPEBOT_ENABLED=true

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

<Note>
  The `TYPEBOT_API_VERSION` determines which Typebot API endpoint format is used. Use "latest" for newer Typebot versions (v2.0+).
</Note>

## Configuration Settings

### Create Default Settings

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

<CodeGroup>
  ```bash cURL theme={null}
  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": ""
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://your-api.com/typebot/settings/{instance}', {
    method: 'POST',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      expire: 300,
      keywordFinish: '#EXIT',
      delayMessage: 1000,
      unknownMessage: 'I did not understand your message.',
      listeningFromMe: false,
      stopBotFromMe: false,
      keepOpen: false,
      debounceTime: 10,
      ignoreJids: [],
      typebotIdFallback: ''
    })
  });
  ```
</CodeGroup>

#### Settings Parameters

<ResponseField name="expire" type="number" required>
  Session expiration time in seconds. Default: 300 (5 minutes)
</ResponseField>

<ResponseField name="keywordFinish" type="string" required>
  Keyword to terminate the bot session. Example: "#EXIT", "bye"
</ResponseField>

<ResponseField name="delayMessage" type="number" required>
  Delay in milliseconds between messages. Default: 1000
</ResponseField>

<ResponseField name="unknownMessage" type="string" required>
  Message sent when bot doesn't understand user input
</ResponseField>

<ResponseField name="listeningFromMe" type="boolean" required>
  Whether bot responds to messages sent by the instance owner
</ResponseField>

<ResponseField name="stopBotFromMe" type="boolean" required>
  Whether instance owner can stop the bot session
</ResponseField>

<ResponseField name="keepOpen" type="boolean" required>
  Keep session open after completion. Default: false
</ResponseField>

<ResponseField name="debounceTime" type="number" required>
  Seconds to wait before processing rapid messages. Default: 10
</ResponseField>

<ResponseField name="ignoreJids" type="array" required>
  List of JIDs (phone numbers) to ignore
</ResponseField>

<ResponseField name="typebotIdFallback" type="string">
  Fallback Typebot ID to use when primary bot fails
</ResponseField>

## Create a Typebot Bot

<Steps>
  <Step title="Configure your Typebot">
    Create and configure your bot flow in your Typebot instance. Note the Typebot URL and bot ID.
  </Step>

  <Step title="Create bot in Evolution API">
    Register the Typebot with Evolution API using the endpoint below.
  </Step>

  <Step title="Test the integration">
    Send a message matching your trigger to start the Typebot conversation.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  const typebot = await fetch('https://your-api.com/typebot/create/{instance}', {
    method: 'POST',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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
    })
  });
  ```
</CodeGroup>

### Request Parameters

<ResponseField name="enabled" type="boolean" required>
  Enable or disable this bot
</ResponseField>

<ResponseField name="description" type="string" required>
  Description of the bot purpose
</ResponseField>

<ResponseField name="url" type="string" required>
  Your Typebot instance URL (e.g., "[https://typebot.yourdomain.com](https://typebot.yourdomain.com)")
</ResponseField>

<ResponseField name="typebot" type="string" required>
  Your Typebot flow ID from the Typebot dashboard
</ResponseField>

<ResponseField name="triggerType" type="string" required>
  Trigger type: "all", "keyword", or "advanced"
</ResponseField>

<ResponseField name="triggerOperator" type="string">
  For keyword triggers: "equals", "contains", "startsWith", "endsWith", "regex"
</ResponseField>

<ResponseField name="triggerValue" type="string">
  The keyword or regex pattern to trigger this bot
</ResponseField>

## Trigger Types

### All Messages

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

```json theme={null}
{
  "triggerType": "all"
}
```

### Keyword Trigger

Trigger based on specific keywords:

```json theme={null}
{
  "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:

```json theme={null}
{
  "triggerType": "advanced",
  "triggerValue": "^(hello|hi|hey)\\s"
}
```

## Start Typebot from API

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api.com/typebot/start/{instance} \
    -H "apikey: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "remoteJid": "5511999999999@s.whatsapp.net",
      "url": "https://typebot.yourdomain.com",
      "typebot": "my-bot-id-abc123",
      "startSession": true,
      "variables": [
        {
          "name": "customerName",
          "value": "John Doe"
        },
        {
          "name": "ticketId",
          "value": "TICKET-12345"
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const session = await fetch('https://your-api.com/typebot/start/{instance}', {
    method: 'POST',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      remoteJid: '5511999999999@s.whatsapp.net',
      url: 'https://typebot.yourdomain.com',
      typebot: 'my-bot-id-abc123',
      startSession: true,
      variables: [
        { name: 'customerName', value: 'John Doe' },
        { name: 'ticketId', value: 'TICKET-12345' }
      ]
    })
  });
  ```
</CodeGroup>

<ResponseField name="remoteJid" type="string" required>
  WhatsApp JID of the recipient (format: [number@s.whatsapp.net](mailto:number@s.whatsapp.net))
</ResponseField>

<ResponseField name="startSession" type="boolean" required>
  Set to true to start a new session
</ResponseField>

<ResponseField name="variables" type="array">
  Prefilled variables to pass to Typebot flow
</ResponseField>

## Update Typebot Bot

Modify an existing Typebot configuration:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://your-api.com/typebot/update/{instance}/{botId}', {
    method: 'PUT',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      enabled: true,
      description: 'Updated Support Bot',
      triggerValue: 'help'
    })
  });
  ```
</CodeGroup>

## Delete Typebot Bot

Remove a Typebot bot from your instance:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://your-api.com/typebot/delete/{instance}/{botId} \
    -H "apikey: your-api-key"
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://your-api.com/typebot/delete/{instance}/{botId}', {
    method: 'DELETE',
    headers: {
      'apikey': 'your-api-key'
    }
  });
  ```
</CodeGroup>

## Fetch Typebot Bots

Retrieve all Typebot bots configured for your instance:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://your-api.com/typebot/fetch/{instance} \
    -H "apikey: your-api-key"
  ```

  ```javascript JavaScript theme={null}
  const bots = await fetch('https://your-api.com/typebot/fetch/{instance}', {
    headers: {
      'apikey': 'your-api-key'
    }
  }).then(res => res.json());
  ```
</CodeGroup>

## Session Management

### Change Session Status

Update the status of an active Typebot session:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api.com/typebot/changeStatus/{instance} \
    -H "apikey: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "remoteJid": "5511999999999@s.whatsapp.net",
      "status": "closed"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://your-api.com/typebot/changeStatus/{instance}', {
    method: 'POST',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      remoteJid: '5511999999999@s.whatsapp.net',
      status: 'closed'
    })
  });
  ```
</CodeGroup>

### Fetch Sessions

Get all active Typebot sessions:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://your-api.com/typebot/fetchSessions/{instance} \
    -H "apikey: your-api-key"
  ```

  ```javascript JavaScript theme={null}
  const sessions = await fetch('https://your-api.com/typebot/fetchSessions/{instance}', {
    headers: {
      'apikey': 'your-api-key'
    }
  }).then(res => res.json());
  ```
</CodeGroup>

## Webhooks

Evolution API emits Typebot-specific webhook events:

### TYPEBOT\_START

Triggered when a Typebot session begins:

```json theme={null}
{
  "event": "typebot.start",
  "instance": "my-instance",
  "data": {
    "remoteJid": "5511999999999@s.whatsapp.net",
    "url": "https://typebot.yourdomain.com",
    "typebot": "my-bot-id",
    "variables": {},
    "sessionId": "session-123"
  }
}
```

### TYPEBOT\_CHANGE\_STATUS

Triggered when session status changes:

```json theme={null}
{
  "event": "typebot.changeStatus",
  "instance": "my-instance",
  "data": {
    "remoteJid": "5511999999999@s.whatsapp.net",
    "status": "closed"
  }
}
```

Enable these events in your `.env`:

```bash theme={null}
WEBHOOK_EVENTS_TYPEBOT_START=true
WEBHOOK_EVENTS_TYPEBOT_CHANGE_STATUS=true
```

## Use Cases

<Accordion title="Customer Support Automation">
  Create interactive support flows that:

  * Collect customer information
  * Categorize support requests
  * Route to appropriate departments
  * Provide automated responses to common questions
</Accordion>

<Accordion title="Lead Qualification">
  Build conversational flows to:

  * Qualify potential leads
  * Collect contact information
  * Schedule appointments
  * Send information to your CRM
</Accordion>

<Accordion title="Survey and Feedback Collection">
  Design surveys that:

  * Collect user feedback
  * Measure customer satisfaction
  * Gather product insights
  * Export data for analysis
</Accordion>

<Accordion title="Order Processing">
  Implement order flows that:

  * Display product catalogs
  * Process orders and payments
  * Confirm delivery details
  * Send order confirmations
</Accordion>

## Best Practices

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

<Note>
  Use the `debounceTime` setting to handle users who send multiple rapid messages, preventing duplicate processing.
</Note>

* **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

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

## Related Integrations

* [Chatwoot](/integrations/chatwoot) - Customer support platform
* [OpenAI](/integrations/openai) - AI-powered conversational bots
* [Dify](/integrations/dify) - LLM application platform