Introducción

Respuesta Exitosa

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

Respuesta de Error

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

Ejemplo cURL

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": "¡Hola! Este es un *mensaje importante*.",
    "preview_url": true
  }'

Ejemplo JavaScript

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: '¡Hola! Este es un *mensaje importante*.',
      preview_url: true
    })
  });
  
  const data = await response.json();
  console.log(data);
};

Formatos Soportados

Ejemplo cURL

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": "Este es nuestro *nuevo producto*"
  }'

Posibles Estados

Respuesta Exitosa

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

Ejemplo cURL

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

Eventos Disponibles

Ejemplo de Webhook

{
  "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"
    }]
  }]
}

Mejores Prácticas de Seguridad

• Usa HTTPS con certificados válidos
• Implementa verificación de firma para autenticar solicitudes
• Usa tokens de verificación seguros
• Limita la tasa de solicitudes aceptadas
• Registra y monitorea todas las solicitudes entrantes

Verificación de Firma

WhatsApp incluye un encabezado X-Hub-Signature-256 con firma SHA256 del payload usando tu App Secret.

// Ejemplo de verificación en 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();
}

Proceso de Aprobación

Todas las plantillas deben ser aprobadas por WhatsApp antes de poder usarse. El proceso tarda típicamente 24-72 horas.

1. Crea la plantilla en el Panel de WhatsApp Business
2. Espera la revisión y aprobación
3. Recibe notificación por email
4. Usa el nombre de plantilla aprobado en tus llamadas API

Ejemplo de Plantilla de Texto

{
  "name": "order_confirmation",
  "language": "es",
  "components": [
    {
      "type": "body",
      "text": "Hola {{1}}, tu pedido #{{2}} ha sido confirmado. Será enviado el {{3}}."
    },
    {
      "type": "button",
      "sub_type": "quick_reply",
      "index": 0,
      "parameters": [
        {
          "type": "payload",
          "payload": "track_order_12345"
        }
      ]
    }
  ]
}

Ejemplo de Uso

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

Proceso de Solución

1. Verifica el código de error en la respuesta
2. Consulta la documentación oficial
3. Revisa los logs de tu servidor
4. Prueba con datos mínimos para aislar el problema
5. Si persiste, contacta al soporte con detalles completos

Registro de Errores

Implementa un sistema de registro que capture:

• Timestamp del error
• Código y mensaje de error
• Solicitud que generó el error
• Contexto de la operación

Límites de la API

Versión 2.0 - Enero 2025

• Nuevo endpoint para mensajes de encuestas
• Soporte para respuestas a encuestas via webhook
• Mejoras en el sistema de plantillas

Versión 1.9 - Octubre 2024

• Integración con WhatsApp Pay para pagos
• Soporte para múltiples monedas
• Mejoras de seguridad en autenticación

Próximamente (Roadmap 2025)

• Q3 2025: Soporte para chatbots con IA integrada
• Q3 2025: Análisis de sentimientos en mensajes entrantes
• Q4 2025: Integración con WhatsApp Communities
• Q4 2025: Soporte para canales de broadcast avanzados