WhatsApp Business API

Integrate with official Meta WhatsApp Business API for enterprise messaging

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

1. Create Meta Business Account

   Sign up for a Meta Business Account at business.facebook.com

2. Request WhatsApp API Access

   Apply for WhatsApp Business API access through Meta Business Manager

3. Get API Credentials

   Obtain your:

   • Phone Number ID
   • WhatsApp Business Account ID
   • Access Token
4. 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:

1. 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.

2. 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
     }
   }
   
3. 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

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)
  }
};

Media Message

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
  }
};

Template Message

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": "[e-mail]",
  "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

1. Use Templates Wisely

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

2. Monitor Quality

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

3. Handle Webhooks Efficiently

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

4. 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