Introducción

WhatsApi es una API REST para enviar mensajes automáticos por WhatsApp desde tus aplicaciones: códigos OTP, notificaciones, alertas y avisos transaccionales.

Hay dos formas de enviar mensajes:

• Tu propio número (BYO — Bring Your Own) — vinculas tu WhatsApp con un código QR o código de emparejamiento y envías con tu identidad. Disponible en todos los planes, incluido el gratis.
• Números de plataforma como respaldo (opcional) — en planes de pago, si tu número se desconecta, números administrados por la plataforma (disponibles 24/7) envían por ti. Se activa por defecto y puedes desactivarlo en tu panel cuando quieras.

Vincular tu número de WhatsApp

Desde tu panel → Mi número, elige Código QR (desde una PC/tablet) o Código de emparejamiento (desde el mismo teléfono). En WhatsApp para Android:

1. Abre WhatsApp y toca el menú ⋮ (arriba a la derecha).
2. Entra a Dispositivos vinculados.
3. Toca Vincular un dispositivo.
4. Escanea el QR, o elige "Vincular con número de teléfono" e ingresa el código de 8 dígitos que te muestra el panel.

En iPhone (iOS)

Según la guía oficial de WhatsApp, en iPhone el proceso es:

1. En WhatsApp, toca Ajustes (o tu foto de perfil) → Dispositivos vinculados → Vincular dispositivo.
2. Desbloquea tu iPhone si tienes iOS 14 o una versión posterior: usa Touch ID o Face ID; si no tienes autenticación biométrica activada, se te pedirá el PIN que usas para desbloquear el teléfono.
3. Apunta la cámara del teléfono hacia la pantalla del dispositivo que quieras vincular y escanea el código QR.

Autenticación

Todas las llamadas a la API requieren tu API Key en el header Authorization.

Authorization: Bearer wa_tu_api_key_aqui

Encuentra tu key en el panel → API Key. Puedes rotarla ahí mismo si se compromete.

Enviar mensajes

Envía un mensaje de texto (hasta 4096 caracteres). Soporta emojis, saltos de línea y formato de WhatsApp (*negrita*, _cursiva_, ~tachado~, ```monospace```).

Cuerpo (JSON)

to *

Número destino con código de país, solo dígitos — ej. 50257110284

text *

Texto del mensaje (máx. 4096 caracteres)

Respuestas

• 200 → {"queued":false,"sent":true,"sessionId":"…","msgId":"…"} — enviado de inmediato.
• 202 → {"queued":true,"id":"…","held":true/false} — no había número disponible; quedó en cola (ver Cola y respaldo).
• 4xx/5xx → {"error":"CODIGO"} — ver códigos de error.

Ejemplos

curl -X POST https://cloud.voltgo.net/whatsapp/api/send \
  -H "Authorization: Bearer wa_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "50257110284",
        "text": "Tu código de verificación es: *483920*" }'

<?php
$r = file_get_contents('https://cloud.voltgo.net/whatsapp/api/send', false,
  stream_context_create(['http' => [
    'method' => 'POST',
    'header' => "Authorization: Bearer wa_tu_api_key\r\nContent-Type: application/json\r\n",
    'content' => json_encode([
      'to'   => '50257110284',
      'text' => 'Tu código de verificación es: *483920*',
    ]),
  ]]));
$res = json_decode($r, true);
if (!empty($res['sent'])) echo "Enviado!";
if (!empty($res['queued'])) echo "En cola — se enviará al reconectar.";

const res = await fetch('https://cloud.voltgo.net/whatsapp/api/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_tu_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '50257110284',
    text: 'Tu código de verificación es: *483920*',
  }),
});
const data = await res.json();
if (data.sent) console.log('Enviado!');
if (data.queued) console.log('En cola — se enviará al reconectar.');

import requests

res = requests.post(
    'https://cloud.voltgo.net/whatsapp/api/send',
    headers={'Authorization': 'Bearer wa_tu_api_key'},
    json={'to': '50257110284',
          'text': 'Tu código de verificación es: *483920*'},
    timeout=15,
)
data = res.json()
if data.get('sent'):   print('Enviado!')
if data.get('queued'): print('En cola — se enviará al reconectar.')

Otros endpoints

Verifica que tu API Key funciona → {"ok":true,"clientId":"…"}

Perfil de tu cliente: límites del plan, sesiones vinculadas, vencimiento y uso (hoy / mes / encolados).

Contadores de uso → {"today":N,"month":N,"queued":N}

Verifica si un número está en WhatsApp antes de enviar → {"to":"…","exists":true}. Requiere una sesión conectada; si no hay ninguna responde 503 NO_SESSION.

Cola y respaldo

Si no hay ningún número disponible para enviar (tu WhatsApp se desconectó), el mensaje no se pierde: entra a la cola y la API responde 202 {"queued":true}.

Plan gratis (trial)

• Solo envías desde tu propio número. No hay respaldo de plataforma.
• Si tu número se desconecta, te avisamos por WhatsApp desde otro número con un link para revincularlo.
• Los mensajes en cola quedan en espera: al reconectar tu número, tu panel te preguntará si quieres reenviarlos todos o revisarlos uno por uno desde el historial.

Planes de pago

• Tu número es el remitente principal. El respaldo con números de plataforma viene activado por defecto — si tu número cae, seguimos enviando por ti 24/7.
• Puedes desactivarlo en Panel → Ajustes. Al hacerlo, si tu número se desconecta los mensajes quedan en cola (igual que en el plan gratis) y tú decides cuándo reenviarlos.

Reenvío de la cola

• Los reenvíos respetan los límites de tu plan (por minuto, por día y por mes).
• Si al reenviar todo solo una parte cabe dentro de tus límites, se envía lo que se puede y el resto queda registrado en el historial con la razón del fallo (PLAN_LIMIT_DAILY, PLAN_LIMIT_MONTHLY).
• Nada se pierde: lo que no salió puede reenviarse después, uno por uno, desde tu historial de mensajes.

Códigos de error

Todos los errores responden {"error":"CODIGO", ...detalles} con su código HTTP.

Fallos registrados en el historial

Límites y buenas prácticas

• Por minuto — evita ráfagas; al superarlo recibes 429 RATE_LIMITED con retryAfter.
• Por día y por mes — definidos por tu plan; al agotarse recibes 429 PLAN_LIMIT_EXCEEDED. Los reenvíos de cola también los respetan.
• Contenido — textos útiles (OTP, avisos, confirmaciones). El spam masivo puede causar el baneo de tu número por WhatsApp, algo fuera de nuestro control.
• Reintentos — los errores permanentes (NO_WHATSAPP, límites) no deben reintentarse; los temporales se reintentan solos hasta 5 veces y luego puedes reenviarlos manualmente.