API Documentation

Overview

MessageAgentKit provides a REST API and MCP (Model Context Protocol) server for integrating WhatsApp messaging capabilities into your applications. The API allows you to send text messages, template messages, schedule messages for approval, and retrieve message history.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

REST API Authentication

Authorization: Bearer YOUR_API_TOKEN

MCP Server Authentication

When calling MCP tools, include your API token as the api_token parameter in the tool arguments.

{
  "tool": "send_text_message",
  "arguments": {
    "api_token": "YOUR_API_TOKEN",
    "to": "5511999999999",
    "text": "Hello!"
  }
}

API Endpoints

{
  "to": "5511999999999",
  "text": "Hello from MessageAgentKit!"
}

{
  "messaging_product": "whatsapp",
  "contacts": [...],
  "messages": [
    {
      "id": "wamid.xxx"
    }
  ]
}

{
  "to": "5511999999999",
  "template_name": "hello_world",
  "language": "en_US",
  "components": []
}

{
  "to": "5511999999999",
  "text": "Scheduled message",
  "scheduled_for": "2025-01-20T10:00:00Z"
}

{
  "to": "5511999999999",
  "template_name": "hello_world",
  "language": "en_US",
  "components": [],
  "scheduled_for": "2025-01-20T10:00:00Z"
}

{
  "messages": [
    {
      "sent_at": "2025-01-15 10:30:00",
      "message_type": "text",
      "recipient": "5511999999999",
      "message_content": "Hello!",
      "status": "sent",
      "whatsapp_message_id": "wamid.xxx"
    }
  ]
}

{
  "message_ids": ["uuid1", "uuid2", "uuid3"]
}

API Analytics Endpoint

Get comprehensive analytics data for building charts and dashboards. Perfect for Lovable integration.

GET https://your-domain.com/api/analytics/usage?range=7d
Authorization: Bearer YOUR_API_TOKEN

{
  "totalMessages": 34,
  "daily": [
    {
      "date": "2025-01-15",
      "count": 10,
      "sent": 9,
      "failed": 1
    },
    {
      "date": "2025-01-16",
      "count": 24,
      "sent": 24,
      "failed": 0
    }
  ],
  "hourlyHeatmap": [
    {
      "hour": 9,
      "dayOfWeek": 1,
      "count": 5
    },
    {
      "hour": 14,
      "dayOfWeek": 1,
      "count": 8
    }
  ],
  "successRate": 0.97
}

MCP Tools

The MCP Server exposes tools that can be called by AI agents (Claude, GPT, etc.) to interact with WhatsApp. All tools require an api_token parameter.

Best Practices

Phone Number Format

Always use E.164 format for phone numbers. This means:

• Include country code (without +)
• No spaces, dashes, or special characters
• Example: 5511999999999 for Brazil (+55 11 99999-9999)

Error Handling

Always implement proper error handling:

try {
  const response = await fetch('https://your-domain.com/api/messages/text', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ to: '5511999999999', text: 'Hello' })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'Request failed');
  }

  const data = await response.json();
  console.log('Message sent:', data.messages[0].id);
} catch (error) {
  console.error('Error sending message:', error);
  // Handle error appropriately
}

Rate Limiting

WhatsApp Business API has rate limits. Be mindful of:

• Message sending rate (varies by account tier)
• Template message approval process
• 24-hour messaging window for conversations

Message Scheduling

Use scheduled messages for:

• Campaigns that need approval before sending
• Bulk messaging with review workflow
• Compliance and audit requirements

Security

• Never commit API tokens to version control
• Use environment variables for sensitive data
• Rotate API tokens periodically
• Validate user input before sending messages
• Implement rate limiting on your side

Error Handling

All endpoints return standard HTTP status codes:

Error Response Format

{
  "error": "Error message description"
}

Common Errors

Code Examples

JavaScript/Node.js

const sendWhatsAppMessage = async (to, text) => {
  const response = await fetch('https://your-domain.com/api/messages/text', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WHATSAPP_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ to, text })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return await response.json();
};

// Usage
try {
  const result = await sendWhatsAppMessage('5511999999999', 'Hello!');
  console.log('Message ID:', result.messages[0].id);
} catch (error) {
  console.error('Failed to send message:', error.message);
}

Python

import requests
import os

def send_whatsapp_message(to, text):
    url = 'https://your-domain.com/api/messages/text'
    headers = {
        'Authorization': f'Bearer {os.getenv("WHATSAPP_API_TOKEN")}',
        'Content-Type': 'application/json'
    }
    data = {'to': to, 'text': text}
    
    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    return response.json()

# Usage
try:
    result = send_whatsapp_message('5511999999999', 'Hello!')
    print(f"Message ID: {result['messages'][0]['id']}")
except requests.exceptions.RequestException as e:
    print(f"Failed to send message: {e}")

cURL

curl -X POST https://your-domain.com/api/messages/text \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Hello from MessageAgentKit!"
  }'

MCP Tool Call Example

{
  "tool": "send_text_message",
  "arguments": {
    "api_token": "YOUR_API_TOKEN",
    "to": "5511999999999",
    "text": "Hello from MCP!"
  }
}