Skip to main content
The Evolution API provider connects to a self-hosted or cloud-hosted Evolution API instance, providing a robust HTTP API interface for WhatsApp automation.

​
Features

  • HTTP API interface for WhatsApp
  • Text and media messaging
  • Image, video, audio, and document support
  • Base64 media encoding
  • File size validation (10MB limit)
  • Message queuing
  • Session management via API
  • Connection state monitoring

​
Prerequisites

1

Evolution API Instance

Set up an Evolution API instance (self-hosted or cloud)
2

Create Instance

Create a WhatsApp instance in Evolution API
3

Get Credentials

Obtain:
  • API Key
  • Instance Name
  • Base URL
4

Connect WhatsApp

Connect your WhatsApp account to the instance

​
Installation

npm install @builderbot/bot @builderbot/provider-evolution-api

​
Configuration

​
Basic Setup

import { createBot, createProvider, createFlow } from '@builderbot/bot'
import { EvolutionProvider } from '@builderbot/provider-evolution-api'
import { MemoryDB } from '@builderbot/bot'

const provider = createProvider(EvolutionProvider, {
  apiKey: 'YOUR_API_KEY',
  instanceName: 'YOUR_INSTANCE_NAME',
  baseURL: 'http://localhost:8080',
  port: 3000
})

const { handleCtx, httpServer } = await createBot({
  flow: adapterFlow,
  provider: provider,
  database: new MemoryDB(),
})

httpServer(3000)

​
Environment Variables

EVOLUTION_API_KEY=your_api_key
EVOLUTION_INSTANCE_NAME=my-instance
EVOLUTION_BASE_URL=http://localhost:8080
PORT=3000

const provider = createProvider(EvolutionProvider, {
  apiKey: process.env.EVOLUTION_API_KEY,
  instanceName: process.env.EVOLUTION_INSTANCE_NAME,
  baseURL: process.env.EVOLUTION_BASE_URL || 'http://localhost:8080'
})

​
Basic Usage

​
Sending Text Messages

const welcomeFlow = addKeyword(['hi', 'hello'])
  .addAnswer('Hello! Welcome to our service')
  .addAnswer('How can we assist you?')

​
Sending Media

const mediaFlow = addKeyword('media')
  // Send image from local file
  .addAnswer('Here is an image:', {
    media: './assets/image.jpg'
  })
  // Send image from URL
  .addAnswer('Image from URL:', {
    media: 'https://example.com/image.jpg'
  })
  // Send video
  .addAnswer('Check this video:', {
    media: './assets/video.mp4'
  })
  // Send audio
  .addAnswer('Listen to this:', {
    media: './assets/audio.mp3'
  })
  // Send document
  .addAnswer('Here is a PDF:', {
    media: './assets/document.pdf'
  })

​
Direct API Usage

​
Send Image

const imageFlow = addKeyword('image')
  .addAction(async (ctx, { provider }) => {
    await provider.sendImage(
      ctx.from,
      './path/to/image.jpg',
      'Check out this image!'
    )
  })

​
Send Video

const videoFlow = addKeyword('video')
  .addAction(async (ctx, { provider }) => {
    await provider.sendVideo(
      ctx.from,
      './path/to/video.mp4',
      'Watch this video'
    )
  })

​
Send Audio

const audioFlow = addKeyword('audio')
  .addAction(async (ctx, { provider }) => {
    await provider.sendAudio(
      ctx.from,
      './path/to/audio.mp3'
    )
  })
Audio files must be in OPUS codec format for voice notes. The provider automatically sets the mimetype to audio/ogg; codecs=opus.

​
Send Document

const documentFlow = addKeyword('document')
  .addAction(async (ctx, { provider }) => {
    await provider.sendFile(
      ctx.from,
      './path/to/document.pdf',
      'Here is the requested document'
    )
  })

​
Receiving Media

import { join } from 'path'

const receiveMediaFlow = addKeyword('MEDIA')
  .addAction(async (ctx, { provider, flowDynamic }) => {
    // Save the received file
    const filePath = await provider.saveFile(ctx, {
      path: join(process.cwd(), 'downloads')
    })
    
    await flowDynamic(`File saved at: ${filePath}`)
  })

​
Advanced Features

​
Sending Text with Options

const textFlow = addKeyword('info')
  .addAction(async (ctx, { provider }) => {
    await provider.sendText(
      ctx.from,
      'This is a text message with no delay'
    )
  })

​
Custom API Requests

You can send custom requests to Evolution API: 
const customFlow = addKeyword('custom')
  .addAction(async (ctx, { provider }) => {
    const response = await provider.sendMessageToApi(
      {
        number: ctx.from,
        text: 'Custom message',
        delay: 1000
      },
      '/message/sendText/'
    )
    console.log('Response:', response)
  })

​
Webhook Configuration

​
Webhook Endpoints

The provider sets up these endpoints: 
POST /       - Home endpoint
POST /webhook - Receive messages from Evolution API

​
Evolution API Webhook Setup

  1. Configure webhook in your Evolution API instance
  2. Set webhook URL: https://your-domain.com/webhook
  3. Enable message events

​
Connection State

The provider automatically checks connection state on startup: 
provider.on('ready', () => {
  console.log('Evolution API connected and ready!')
})

provider.on('notice', ({ title, instructions }) => {
  console.log(title)
  console.log(instructions)
})

​
File Size Limits

The provider enforces a 10MB file size limit: 
// Files larger than 10MB will throw an error
const MAX_FILE_SIZE = 10 * 1024 * 1024 // 10MB

​
Media Type Detection

The provider automatically detects media types: 
const autoMediaFlow = addKeyword('send')
  .addAction(async (ctx, { provider }) => {
    // Automatically detects if it's image, video, audio, or document
    await provider.sendMedia(
      ctx.from,
      'https://example.com/file.jpg', // URL or local path
      'Check this out!'
    )
  })

​
Error Handling

provider.on('notice', ({ title, instructions }) => {
  if (title.includes('ERROR')) {
    console.error('Connection error:', instructions)
  }
})

try {
  await provider.sendMessage(number, message)
} catch (error) {
  console.error('Failed to send message:', error.message)
}

​
Best Practices

  • Keep media files under 10MB
  • Use appropriate file formats
  • Clean up temporary files after sending
  • Monitor the ready event
  • Handle connection failures gracefully
  • Implement retry logic for critical messages
  • Messages are automatically queued
  • Default: 1 concurrent message, 100ms interval
  • Prevents rate limiting issues
  • Keep API key secure (use environment variables)
  • Use HTTPS for production
  • Implement proper authentication for webhooks

​
Troubleshooting

  • Verify Evolution API is running
  • Check baseURL is correct
  • Ensure API key is valid
  • Verify instance exists and is connected
  • Check file size (must be under 10MB)
  • Verify file format is supported
  • Ensure file path is correct
  • Check file permissions
  • Verify webhook URL is publicly accessible
  • Check Evolution API webhook configuration
  • Review network/firewall settings
  • Enable Evolution API logging for debugging

​
Example: Complete Bot

import { createBot, createProvider, createFlow, addKeyword } from '@builderbot/bot'
import { EvolutionProvider } from '@builderbot/provider-evolution-api'
import { MemoryDB } from '@builderbot/bot'
import { join } from 'path'

const welcomeFlow = addKeyword(['hi', 'hello'])
  .addAnswer('👋 Hello! Welcome to our service')
  .addAnswer('How can we help you today?')

const mediaFlow = addKeyword('files')
  .addAnswer('I\'ll send you some files...')
  .addAnswer('Image:', { media: join(process.cwd(), 'assets', 'image.png') })
  .addAnswer('Document:', { media: join(process.cwd(), 'assets', 'doc.pdf') })

const main = async () => {
  const adapterFlow = createFlow([welcomeFlow, mediaFlow])
  
  const adapterProvider = createProvider(EvolutionProvider, {
    apiKey: process.env.EVOLUTION_API_KEY,
    instanceName: process.env.EVOLUTION_INSTANCE_NAME,
    baseURL: process.env.EVOLUTION_BASE_URL || 'http://localhost:8080'
  })
  
  const adapterDB = new MemoryDB()

  const { handleCtx, httpServer } = await createBot({
    flow: adapterFlow,
    provider: adapterProvider,
    database: adapterDB,
  })

  httpServer(3000)
}

main()

​
API Response Types

The Evolution API provider returns typed responses: 
interface ApiResponse {
  key?: {
    remoteJid: string
    fromMe: boolean
    id: string
  }
  message?: any
  messageTimestamp?: string
  status?: string
}

​
Further Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us