WhatsApp Business API

Overview

The WhatsApp Business API is Meta’s official solution for enterprise-scale WhatsApp integration. Unlike Baileys, it requires official credentials and provides higher rate limits, better reliability, and advanced business features.

You need a Meta Business Account and approved WhatsApp Business API access to use this provider.

Prerequisites

Create Meta Business Account

Request WhatsApp API Access

Apply for WhatsApp Business API access through Meta Business Manager

Get API Credentials

Obtain your:

Phone Number ID
WhatsApp Business Account ID
Access Token

Configure Webhook

Set up webhook verification token in Meta’s developer console

Configuration

Configure Evolution API to use WhatsApp Business API:

.env

# WhatsApp Business API Configuration
WA_BUSINESS_TOKEN_WEBHOOK=evolution
WA_BUSINESS_URL=https://graph.facebook.com
WA_BUSINESS_VERSION=v20.0
WA_BUSINESS_LANGUAGE=en_US

Configuration Options

Variable	Description	Default
`WA_BUSINESS_TOKEN_WEBHOOK`	Webhook verification token	`evolution`
`WA_BUSINESS_URL`	Meta Graph API base URL	`https://graph.facebook.com`
`WA_BUSINESS_VERSION`	Graph API version	`v20.0`
`WA_BUSINESS_LANGUAGE`	Default template language	`en_US`

The webhook token must match the verification token you set in Meta’s developer console.

Creating an Instance

Create a Business API instance with your credentials:

POST /instance/create

{
  "instanceName": "business-instance",
  "token": "your-whatsapp-access-token",
  "number": "15550123456",
  "businessId": "your-business-account-id"
}

Instance Properties

token: Your WhatsApp Business API access token
number: Phone Number ID (not the actual phone number)
businessId: WhatsApp Business Account ID

Connection Flow

Unlike Baileys, the Business API doesn’t require QR code authentication:

Instant Connection

Business API instances connect immediately when created:

public stateConnection: wa.StateConnection = { state: 'open' };

The connection state is always 'open' since authentication is handled via API tokens.

Webhook Setup

Configure webhook URL to receive messages:

POST /webhook/set

{
  "instanceName": "business-instance",
  "webhook": {
    "url": "https://your-server.com/webhook",
    "enabled": true,
    "webhookByEvents": false
  }
}

Verify Webhook

Meta sends verification requests to your webhook URL:

// Evolution API handles verification automatically
if (query['hub.verify_token'] === WA_BUSINESS_TOKEN_WEBHOOK) {
  return query['hub.challenge'];
}

Sending Messages

The Business API supports all standard message types with the same Evolution API interface:

Text Message
Media Message
Template Message

POST /message/sendText/:instanceName

{
  "number": "5511999999999",
  "text": "Hello from Business API!"
}

Internally converts to Meta’s format:

const content = {
  messaging_product: 'whatsapp',
  recipient_type: 'individual',
  type: 'text',
  to: number.replace(/\D/g, ''),
  text: {
    body: message['conversation'],
    preview_url: Boolean(options?.linkPreview)
  }
};

POST /message/sendMedia/:instanceName

{
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://example.com/image.jpg",
  "caption": "Check this out!"
}

Media is uploaded to Meta’s servers:

const id = await this.getIdMedia(prepareMedia);

const content = {
  messaging_product: 'whatsapp',
  type: mediaType,
  to: number,
  [mediaType]: {
    id: id,
    caption: caption
  }
};

Use pre-approved message templates:

POST /message/sendTemplate/:instanceName

{
  "number": "5511999999999",
  "name": "welcome_message",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        }
      ]
    }
  ]
}

Templates must be approved by Meta before use. Create and submit templates in Meta Business Manager.

Receiving Messages

Meta sends webhook notifications to your configured endpoint:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550123456",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.XXX",
                "timestamp": "1234567890",
                "type": "text",
                "text": {
                  "body": "Hello!"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Evolution API normalizes this to standard message format:

const messageRaw = {
  key: {
    id: message.id,
    remoteJid: phoneNumber,
    fromMe: message.from === metadata.phone_number_id
  },
  pushName: contacts[0].profile.name,
  message: this.messageTextJson(received),
  messageType: this.renderMessageType(message.type),
  messageTimestamp: parseInt(message.timestamp),
  instanceId: this.instanceId
};

Message Status Updates

Track message delivery and read status:

{
  "statuses": [
    {
      "id": "wamid.XXX",
      "status": "delivered",
      "timestamp": "1234567890",
      "recipient_id": "5511999999999"
    }
  ]
}

Status Types

Status	Description
`sent`	Message sent to Meta servers
`delivered`	Message delivered to recipient’s phone
`read`	Message read by recipient
`failed`	Message delivery failed

Evolution API emits messages.update events:

const message = {
  messageId: findMessage.id,
  keyId: key.id,
  remoteJid: key.remoteJid,
  fromMe: key.fromMe,
  status: item.status.toUpperCase(),
  instanceId: this.instanceId
};

this.sendDataWebhook(Events.MESSAGES_UPDATE, message);

Business Profile

Update your business profile information:

POST /business/profile/:instanceName

{
  "about": "Your business description",
  "address": "123 Main St, City, Country",
  "description": "Detailed business description",
  "email": "[email protected]",
  "vertical": "RETAIL",
  "websites": ["https://business.com"]
}

Implementation:

public async setWhatsappBusinessProfile(data: NumberBusiness): Promise<any> {
  const content = {
    messaging_product: 'whatsapp',
    about: data.about,
    address: data.address,
    description: data.description,
    vertical: data.vertical,
    email: data.email,
    websites: data.websites,
    profile_picture_handle: data.profilehandle
  };
  return await this.post(content, 'whatsapp_business_profile');
}

API Version Management

Meta regularly updates the Graph API. Evolution API tracks the configured version:

const urlServer = `${this.configService.get<WaBusiness>('WA_BUSINESS').URL}/${
  this.configService.get<WaBusiness>('WA_BUSINESS').VERSION
}/${this.number}/messages`;

Update WA_BUSINESS_VERSION when Meta releases new API versions to access latest features.

Version History

v20.0: Current recommended version
v19.0: Previous stable version
v18.0: Legacy support

Check Meta’s API Changelog for updates.

Rate Limits

Business API has tiered rate limits based on your account:

Tier	Messages per Day	Unique Recipients
Tier 1	1,000	1,000
Tier 2	10,000	10,000
Tier 3	100,000	100,000
Tier 4	Unlimited	Unlimited

Your tier increases automatically based on message quality and volume. Start at Tier 1 and scale up.

Differences from Baileys

Feature	Business API	Baileys
Authentication	API tokens	QR code
Connection	Always connected	Can disconnect
Session storage	Not required	Required
Rate limits	High (tiered)	Web client limits
Templates	Supported	Not supported
Cost	Paid	Free
Reliability	Enterprise-grade	Community-maintained
Support	Official Meta	Community
Features	Full business features	Basic messaging

Pricing

WhatsApp Business API uses conversation-based pricing:

User-initiated: Conversations started by customer (cheaper)
Business-initiated: Conversations started with templates (higher cost)
Free tier: 1,000 free conversations per month

Pricing varies by country. See Meta’s pricing page for details.

Best Practices

Use Templates Wisely

Pre-approve message templates for business-initiated conversations. Keep templates generic enough for reuse.

Monitor Quality

Meta monitors message quality. Low ratings can result in rate limit reductions.

Handle Webhooks Efficiently

Respond to webhook requests quickly (under 5 seconds) to avoid retries.

Implement Fallbacks

Handle API errors gracefully and implement retry logic for failed messages.

Troubleshooting

Webhook Not Receiving Messages

Verify webhook token matches Meta’s configuration:

.env

WA_BUSINESS_TOKEN_WEBHOOK=your-verification-token

Authentication Errors

Check your access token is valid and has correct permissions:

curl -X GET "https://graph.facebook.com/v20.0/me?access_token=YOUR_TOKEN"

Template Rejection

Ensure templates follow Meta’s guidelines:

No promotional content in utility templates
Proper variable formatting
Compliant with messaging policies

Next Steps

Template Messages

Create and send template messages

Webhooks

Configure webhook events

Baileys Comparison

Compare with free Baileys provider

Connection Management

Manage Business API connections

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

Overview

Prerequisites

Configuration

Configuration Options

Creating an Instance

Instance Properties

Connection Flow

Sending Messages

Receiving Messages

Message Status Updates

Status Types

Business Profile

API Version Management

Version History

Rate Limits

Differences from Baileys

Pricing

Best Practices

Troubleshooting

Webhook Not Receiving Messages

Authentication Errors

Template Rejection

Next Steps

Template Messages

Webhooks

Baileys Comparison

Connection Management

Build docs developers (and LLMs) love

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

​Overview

​Prerequisites

​Configuration

​Configuration Options

​Creating an Instance

​Instance Properties

​Connection Flow

​Sending Messages

​Receiving Messages

​Message Status Updates

​Status Types

​Business Profile

​API Version Management

​Version History

​Rate Limits

​Differences from Baileys

​Pricing

​Best Practices

​Troubleshooting

​Webhook Not Receiving Messages

​Authentication Errors

​Template Rejection

​Next Steps

Template Messages

Webhooks

Baileys Comparison

Connection Management

Build docs developers (and LLMs) love

Overview

Prerequisites

Configuration

Configuration Options

Creating an Instance

Instance Properties

Connection Flow

Sending Messages

Receiving Messages

Message Status Updates

Status Types

Business Profile

API Version Management

Version History

Rate Limits

Differences from Baileys

Pricing

Best Practices

Troubleshooting

Webhook Not Receiving Messages

Authentication Errors

Template Rejection

Next Steps