Use and adapt WhatsApp-Meta-Business-API-Handler

Use the documented interfaces and source layout for WhatsApp-Meta-Business-API-Handler. The sections below retain the README’s examples and configuration details.

Configuration

Configuration Options

Full Configuration Example

1const whatsapp = createWhatsAppHandler({
2  token: 'YOUR_TOKEN',
3  phoneNumberId: 'YOUR_PHONE_ID',
4  businessAccountId: 'YOUR_BUSINESS_ID',
5  version: 'v21.0',
6  appSecret: 'YOUR_APP_SECRET',
7  webhookVerifyToken: 'YOUR_VERIFY_TOKEN',
8  apiTimeout: 30000,
9  maxRetries: 3,
10  autoMarkRead: true,
11  autoProcessMessages: true,
12  queueEnabled: true,
13  maxQueueSize: 1000,
14  storage: {
15    type: 'memory',
16    autoCleanup: true,
17    maxMessagesPerConversation: 1000
18  },
19  webhook: {
20    verifyToken: 'YOUR_VERIFY_TOKEN',
21    appSecret: 'YOUR_APP_SECRET',
22    autoProcess: true,
23    autoMarkRead: true,
24    verifySignature: true,
25    maxBodySize: 10485760, // 10MB
26    timeout: 30000
27  }
28});

API Reference

Core Methods

sendMessage(to, message, options?)

Send a text message.

Parameters:

• to (string): Recipient phone number
• message (string): Message text
• options (object, optional):
  • previewUrl (boolean): Enable URL preview
  • replyTo (string): Message ID to reply to
  • priority (number): Message priority
  • queueIfBusy (boolean): Queue if busy

Returns: Promise<MessageResponse>

sendVoice(to, audioIdOrUrl, options?)

Send a voice message.

Parameters:

• to (string): Recipient phone number
• audioIdOrUrl (string): Media ID or URL
• options (object, optional):
  • replyTo (string): Message ID to reply to
  • priority (number): Message priority

Returns: Promise<MessageResponse>

markAsRead(messageId)

Mark a message as read.

Parameters:

• messageId (string): WhatsApp message ID

Returns: Promise<{ success: boolean }>

processWebhook(request)

Process a webhook request (universal handler).

Parameters:

• request (UniversalRequest): Request object

Returns: Promise<WebhookResult>

setWebhookHandlers(handlers)

Set webhook event handlers.

Parameters:

• handlers (WebhookHandlers): Handler functions

Returns: void

getConversationHistory(conversationId, limit?, offset?)

Get conversation message history.

Parameters:

• conversationId (string): Phone number
• limit (number, optional): Max messages (default: 50)
• offset (number, optional): Pagination offset (default: 0)

Returns: Promise<StoredMessage[]>

searchMessages(query, conversationId?)

Search messages by text.

Parameters:

• query (string): Search term
• conversationId (string, optional): Limit to conversation

Returns: Promise<StoredMessage[]>

getConversationState(conversationId)

Get conversation state.

Parameters:

• conversationId (string): Phone number

Returns: ConversationState | undefined

updateConversationContext(conversationId, context)

Update conversation context data.

Parameters:

• conversationId (string): Phone number
• context (object): Context data to merge

Returns: ConversationState

getStatistics()

Get message statistics.

Returns: Object with sent, received, failed, delivered, read counts

getQueueStats()

Get message queue statistics.

Returns: Object with size, maxSize, usagePercentage

startWebhookServer(port?, path?, callback?)

Start standalone HTTP webhook server.

Parameters:

• port (number, optional): Port (default: 3000)
• path (string, optional): Webhook path (default: '/webhook')
• callback (function, optional): Success callback

Returns: http.Server

stopWebhookServer()

Stop webhook server.

Returns: Promise<void>

Troubleshooting

Common Issues

1. Webhook Verification Fails

Problem: GET webhook returns 403

Solution:

1// Ensure verify token matches
2const whatsapp = createWhatsAppHandler({
3  webhookVerifyToken: 'same_token_in_meta_dashboard'
4});

2. Signature Verification Fails

Problem: POST webhook returns 401

Solution:

1// Add app secret and enable verification
2const whatsapp = createWhatsAppHandler({
3  appSecret: 'your_app_secret',
4  webhook: {
5    verifySignature: true,
6    appSecret: 'your_app_secret'
7  }
8});

3. Messages Not Sending

Problem: Messages fail silently

Solution:

1// Listen for errors
2whatsapp.on('messageFailed', (data) => {
3  console.error('Failed:', data.error);
4});
5 
6// Check API credentials
7console.log('Token:', process.env.WHATSAPP_TOKEN);
8console.log('Phone ID:', process.env.WHATSAPP_PHONE_NUMBER_ID);

4. Webhook Not Receiving Events

Problem: No events received

Checklist:

• ✅ Webhook URL is publicly accessible
• ✅ SSL certificate is valid
• ✅ Webhook is subscribed in Meta dashboard
• ✅ Verify token matches
• ✅ Server is running and reachable

Test webhook:

1# Test GET (verification)
2curl "http://your-domain.com/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test"
3 
4# Test POST (message)
5curl -X POST http://your-domain.com/webhook \
6  -H "Content-Type: application/json" \
7  -d '{"object":"whatsapp_business_account","entry":[]}'

5. Rate Limiting

Problem: 429 Too Many Requests

Solution:

1// Enable queue to handle rate limits
2const whatsapp = createWhatsAppHandler({
3  queueEnabled: true,
4  maxQueueSize: 1000,
5  maxRetries: 3
6});
7 
8// Send with queue
9await whatsapp.sendMessage(to, message, { queueIfBusy: true });

Debug Mode

1// Enable verbose logging
2whatsapp.on('messageSent', console.log);
3whatsapp.on('messageFailed', console.error);
4whatsapp.on('messageRead', console.log);
5 
6// Log all webhook events
7whatsapp.setWebhookHandlers({
8  onMessage: (msg, meta) => console.log('Message:', msg, meta),
9  onMessageStatus: (status) => console.log('Status:', status),
10  onError: (error) => console.error('Error:', error),
11  onUnknown: (event) => console.log('Unknown:', event)
12});

Source and help

• GitHub repository
• Original README
• Issues and existing reports

The catalog identifies the license as MIT. Read the repository license before redistributing source or assets.