Documentación de la API

Todo lo necesario para enviar mensajes de WhatsApp desde tus sistemas.

Primeros pasos

  1. Crea tu cuenta y vincula tu WhatsApp desde Mis números.
  2. En Claves API, crea una clave. Guárdala: solo se muestra una vez.
  3. Abre este enlace en el navegador, con tu clave. Te llegará un mensaje a ti mismo:
/api/send?text=Hola&apikey=TU_CLAVE

Enviar un mensaje

Hay dos formas equivalentes. Usa la que te resulte más cómoda.

Enlace sencillo (GET o POST de formulario)

/api/send?phone=612345678&text=Tu%20pedido%20sale%20hoy&apikey=TU_CLAVE

Acepta los parámetros en la dirección o como formulario (application/x-www-form-urlencoded). También responde en /send.php.

API REST (JSON)

POST /api/v1/messages
Authorization: Bearer TU_CLAVE
Content-Type: application/json

{ "to": "612345678", "text": "Tu pedido sale hoy" }

Parámetros

ParámetroObligatorioDescripción
apikeySíTu clave. En la API REST va en la cabecera Authorization: Bearer.
phone o toNoDestinatario. Sin él, el mensaje te llega a tu propio número: ideal para avisos internos. También se acepta recipient.
groupNoID de un grupo de WhatsApp en lugar de un número. Mira Grupos.
fromNoNúmero emisor si tienes varios: su ID, su nombre o el número. Sin él se usa el principal.
textSí, salvo con archivoTexto del mensaje, hasta 4.000 caracteres. Admite emojis y el formato de WhatsApp: *negrita*, _cursiva_.
fileNoEnlace público a una imagen, PDF, vídeo o audio. El texto se envía como pie.
formatNoCon json, el enlace sencillo responde en JSON en lugar de texto.
langNoIdioma de los mensajes de error: es, en, pt o fr.

Grupos

Disponible en el plan Pro y superiores, y durante la prueba gratuita. Tu número debe ser miembro del grupo. En el panel, Mis números → Ver grupos muestra cada grupo con su ID. También puedes consultarlos por API:

GET /api/v1/groups
Authorization: Bearer TU_CLAVE

{"ok":true,"groups":[{"id":"120363012345678901","name":"Comerciales","size":6}]}
/api/send?group=120363012345678901&text=Reunión%20a%20las%2010&apikey=TU_CLAVE

En JSON también vale "to": "[email protected]". Los grupos están disponibles con números vinculados por QR.

Varios números

Si tu cuenta tiene varios números, elige el emisor con from. Acepta el ID que aparece en el panel, el nombre que le hayas dado (por ejemplo Taller) o el propio número de teléfono.

/api/send?from=Taller&phone=612345678&text=Tu%20equipo%20está%20listo&apikey=TU_CLAVE

Cada número tiene su propia cola: los envíos de un número no esperan a los de otro.

Imágenes y documentos

Añade file con un enlace que se pueda descargar sin iniciar sesión. Máximo 16 MB.

/api/send?phone=612345678&text=Albarán%20adjunto&file=https://drive.google.com/file/d/ID/view&apikey=TU_CLAVE

Los enlaces de Google Drive del tipo «Cualquier persona con el enlace» se convierten automáticamente en descarga directa.

Respuestas de la API

Los mensajes no se envían en el momento de la petición: entran en una cola y salen en orden, con pausas de unos segundos para proteger tu número. La respuesta confirma que el mensaje está en cola.

Enlace sencillo:  200  Mensaje en cola. id=123
API REST:         202  {"ok":true,"id":123,"status":"queued","to":"34612345678","from":5}
CódigoQué significaQué hacer
400Falta el texto, el número no es válido o el emisor no existeRevisa los parámetros
401Clave incorrecta o borradaCrea una clave nueva en tu panel
402La prueba gratuita ha terminadoElige un plan en tu panel
403Cuenta desactivada, o clave del bot usada para otro destinoContacta con soporte
429Demasiadas peticiones por minuto o límite diario alcanzadoEspera, o amplía tu plan

Estado de un mensaje

GET /api/v1/messages/123
Authorization: Bearer TU_CLAVE

{"ok":true,"message":{"id":123,"status":"sent","attempts":1,"error":null, ...}}

Estados: queued (en cola), sending, sent (entregado a WhatsApp) y failed (no enviado, con el motivo en error). Si un número se desconecta, sus mensajes esperan y se reintentan solos.

Estado de tus números: GET /api/v1/status

Formato de los números

Funciona con números de cualquier país. Puedes escribirlos en formato internacional (+44 7911 123456, 0044…) o en formato local de tu país (07911 123456). Sin prefijo, se usa el país de tu cuenta, configurable en Ajustes.

El sistema conoce las reglas de numeración de cada país: quita el 0 o el prefijo nacional cuando corresponde y añade el código del país. Por ejemplo, 06 12 34 56 78 en Francia pasa a ser +33 6 12 34 56 78 y (11) 98765-4321 en Brasil pasa a ser +55 11 98765 4321.

Límites

Envía solo mensajes que tus destinatarios esperan. Los envíos masivos a personas que no te conocen pueden hacer que WhatsApp restrinja tu número.

Recibir mensajes

En Ajustes puedes indicar una dirección https:// de tu sistema. Cada mensaje que reciba cualquiera de tus números se te reenviará así:

POST https://tu-sistema.com/webhook
Content-Type: application/json
X-Wagate-Signature: firma HMAC-SHA256 del cuerpo

{"event":"message.received","number_id":5,"from":"+34612345678","message":"SI","name":"Luis","group":null,"at":1762440000000}

Ejemplos

Google Apps Script

function enviarWhatsApp(telefono, texto) {
  const r = UrlFetchApp.fetch('/api/send', {
    method: 'post',
    payload: { apikey: 'TU_CLAVE', phone: telefono, text: texto },
    muteHttpExceptions: true,
  });
  return r.getResponseCode() === 200;
}

AppSheet

Automation, Bot, tarea «Call a webhook»: URL /api/v1/messages, verbo POST, tipo JSON, cabecera Authorization: Bearer TU_CLAVE y cuerpo:

{ "to": "<<[TELEFONO]>>", "text": "Hola <<[CLIENTE]>>, tu pedido está listo." }

PHP

file_get_contents('/api/send?' . http_build_query([
  'apikey' => 'TU_CLAVE', 'phone' => '612345678', 'text' => 'Hola desde PHP',
]));

Python

import requests
requests.post('/api/v1/messages',
  headers={'Authorization': 'Bearer TU_CLAVE'},
  json={'to': '612345678', 'text': 'Hola desde Python'})