Introduction

Success Response

{
  "status": "success",
  "message_id": "wamid.ABGS...",
  "timestamp": "2025-04-27T12:00:00Z",
  "recipient": "+14155552671"
}

Error Response

{
  "status": "error",
  "code": 400,
  "message": "Invalid phone number format",
  "details": "Phone number must include country code"
}

cURL Example

curl -X POST \
  https://api.whatsapp.com/v2/send-message \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155552671",
    "message": "Hello! This is an *important message*.",
    "preview_url": true
  }'

JavaScript Example

const sendMessage = async () => {
  const response = await fetch('https://api.whatsapp.com/v2/send-message', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: '+14155552671',
      message: 'Hello! This is an *important message*.',
      preview_url: true
    })
  });
  
  const data = await response.json();
  console.log(data);
};

Supported Formats

cURL Example

curl -X POST \
  https://api.whatsapp.com/v2/send-media \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155552671",
    "media_type": "image",
    "media_url": "https://example.com/image.jpg",
    "caption": "This is our *new product*"
  }'

Possible Statuses

Success Response

{
  "status": "delivered",
  "message_id": "wamid.ABGS...",
  "timestamp": "2025-04-27T12:05:00Z",
  "recipient": "+14155552671"
}

cURL Example

curl -X GET \
  "https://api.whatsapp.com/v2/message-status?message_id=wamid.ABGS..." \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Available Events

Webhook Example

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "15555555555",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "contacts": [{
          "profile": {
            "name": "John Doe"
          },
          "wa_id": "15555551234"
        }],
        "messages": [{
          "from": "15555551234",
          "id": "wamid.ID",
          "timestamp": "1520383572",
          "text": {
            "body": "Hello!"
          },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

Security Best Practices

• Use HTTPS with valid certificates
• Implement signature verification to authenticate requests
• Use secure verification tokens
• Limit accepted request rate
• Log and monitor all incoming requests

Signature Verification

WhatsApp includes a X-Hub-Signature-256 header with SHA256 signature of the payload using your App Secret.

// Verification example in Node.js
const crypto = require('crypto');

function verifySignature(req, res, next) {
  const signature = req.headers['x-hub-signature-256'];
  const hmac = crypto.createHmac('sha256', process.env.APP_SECRET);
  const digest = `sha256=${hmac.update(JSON.stringify(req.body)).digest('hex')}`;
  
  if (signature !== digest) {
    return res.status(401).send('Invalid signature');
  }
  
  next();
}

Approval Process

All templates must be approved by WhatsApp before they can be used. The process typically takes 24-72 hours.

1. Create the template in the WhatsApp Business Panel
2. Wait for review and approval
3. Receive email notification
4. Use the approved template name in your API calls

Text Template Example

{
  "name": "order_confirmation",
  "language": "en",
  "components": [
    {
      "type": "body",
      "text": "Hello {{1}}, your order #{{2}} has been confirmed. It will be shipped on {{3}}."
    },
    {
      "type": "button",
      "sub_type": "quick_reply",
      "index": 0,
      "parameters": [
        {
          "type": "payload",
          "payload": "track_order_12345"
        }
      ]
    }
  ]
}

Usage Example

POST /v2/messages
{
  "to": "15555551234",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "text": "John"},
          {"type": "text", "text": "12345"},
          {"type": "text", "text": "04/28/2025"}
        ]
      }
    ]
  }
}

Troubleshooting Process

1. Check the error code in the response
2. Consult the official documentation
3. Review your server logs
4. Test with minimal data to isolate the problem
5. If it persists, contact support with complete details

Error Logging

Implement a logging system that captures:

• Error timestamp
• Error code and message
• Request that generated the error
• Operation context

API Limits

Version 2.0 - January 2025

• New endpoint for survey messages
• Support for survey responses via webhook
• Template system improvements

Version 1.9 - October 2024

• Integration with WhatsApp Pay for payments
• Support for multiple currencies
• Authentication security improvements

Coming Soon (2025 Roadmap)

• Q3 2025: Support for AI-powered chatbots
• Q3 2025: Sentiment analysis on incoming messages
• Q4 2025: Integration with WhatsApp Communities
• Q4 2025: Support for advanced broadcast channels