API REST de WhatsApp

Enviar mensajes de WhatsApp desde tu sistema, con la API oficial

Para enviar mensajes por API de WhatsApp, tu sistema llama a la API REST de Waspy. Waspy los manda por la Cloud API oficial de Meta y la conversación queda en el inbox del equipo.

Respuesta corta: cómo enviar mensajes por API de WhatsApp

Para enviar mensajes por API de WhatsApp desde tu sistema, con Waspy, creás una clave y hacés un POST a https://api.waspytech.com/api/v2/messages. La clave va en el encabezado Authorization, como Bearer, y empieza con wspy_. El número tiene que estar en la API oficial de Meta. Waspy es Tech Provider de Meta verificado: el alta es el registro embebido y el número sigue siendo del negocio.

Si lo buscás como whatsapp api ejemplo, enviar whatsapp desde mi sistema, integrar api de whatsapp, whatsapp api webhooks o api rest whatsapp, en Waspy es esa misma llamada. Los webhooks avisan a tu URL cuando pasa algo. El conector MCP es otro camino, para ChatGPT, Claude u otro cliente que habla MCP, no para un HTTP suelto. La referencia está en docs.waspytech.com y la pantalla, en API REST.

La clave se crea en Configuración → Claves de API y se muestra una sola vez. La API REST está en Scale y Enterprise, según la fila API de la tabla pública de planes. Starter y Growth no crean claves: ahí el equipo escribe desde el panel. El alta de la clave está en crear una API key.

Cómo funciona: clave, canal y el POST

Todas las llamadas llevan Authorization: Bearer y la clave. La base es https://api.waspytech.com/api/v2. Sin permisos marcados, la clave puede hacer lo que la API permite. Si marcás permisos, mandar un mensaje exige messages:write. Si falta el encabezado o la clave no existe, la API responde 401. Si la clave no tiene el permiso, responde 403.

El phoneNumberId del POST es el id (un UUID) que devuelve GET /api/v2/channels. No es el phoneNumberId de Meta que viene en el mismo objeto, ni el teléfono del negocio. Ese GET pide el permiso channels:read. El to va en E.164, con el más y el país. Si después de normalizarlo no es un número de WhatsApp válido, la respuesta es 400 con código INVALID_PHONE.

Si ese UUID no es un canal de la cuenta, el POST responde 400 INVALID_CHANNEL. Si el canal existe pero no está active, responde 403 CHANNEL_NOT_CONNECTED. Los tipos que acepta el body son text, image, video, audio, document, template, interactive y reaction. Un texto lleva text.body. Una imagen, un video, un audio o un documento llevan link o id en su objeto. No hay un POST de subida en esta API.

La respuesta que crea el mensaje es 201. El estado arranca en queued y el origin es external_api. Si no había contacto o conversación para ese número, se crean. El equipo ve ese chat en el inbox. Para seguir el estado podés leer GET /api/v2/messages/:id (pasa de queued a sent, delivered, read o failed) o esperar el webhook message.status_changed. Un clientRef de hasta 256 caracteres vuelve igual en cada evento de estado.

El encabezado Idempotency-Key (hasta 256 caracteres) evita un duplicado si reintentás el mismo POST. Durante 24 horas, la misma clave devuelve la respuesta guardada con el encabezado Idempotency-Replayed: true. Si otro pedido con esa clave todavía está en curso, la respuesta es 409 IDEMPOTENCY_CONFLICT.

Hay un tope de 120 pedidos por minuto por cuenta, compartido por las claves de esa cuenta. Si te pasás, la respuesta es 429 con código RATE_LIMITED y el encabezado Retry-After. Ese tope es de la API de Waspy. El de Meta, cuántas personas distintas podés contactar con una plantilla, es otra regla y está más abajo.

Ejemplo: un texto con la ventana abierta

Este es un whatsapp api ejemplo de un texto. Reemplazá la clave y el UUID del canal. El teléfono de abajo es un placeholder.

curl -sS -X POST https://api.waspytech.com/api/v2/messages -H "Authorization: Bearer wspy_TU_CLAVE" -H "Content-Type: application/json" -H "Idempotency-Key: pedido-1847" -d '{"phoneNumberId":"UUID-DEL-CANAL","to":"+5491100000000","type":"text","text":{"body":"Tu pedido ya está en preparación."}}'

Eso manda un mensaje de sesión. La ventana de 24 horas tiene que estar abierta: alguien escribió en las últimas 24 horas. Si está cerrada, el mismo POST de texto responde 403 con código SERVICE_WINDOW_EXPIRED. Ahí el type pasa a template y el body lleva template.name más template.language.code (por ejemplo es_AR). components es opcional y sirve para las variables. El nombre tiene que ser el de una plantilla ya aprobada. Crear la plantilla por este POST no está en la API: se crea en el panel, o con la herramienta create_template del conector, y eso la manda a revisión de Meta sin enviársela a nadie.

Para varios destinatarios está POST /api/v2/messages/batch: hasta 100 mensajes, respuesta 202, y cada ítem se acepta, se saltea o se rechaza solo. Con respectOptOut en true (es el default), quien está en la lista de baja vuelve como skipped y opted_out, y no se envía. El POST de un solo destinatario no consulta esa lista: el código lo trata como un envío a una persona que elegiste a propósito.

Webhooks: enterarte sin preguntar

Los whatsapp api webhooks de Waspy son un POST a una URL tuya. Los eventos, con esos nombres, son cuatro: message.received (entró un mensaje), message.status_changed (cambió el estado de uno que mandaste), conversation.created y contact.created. No hay un evento de plantilla aprobada: para eso se vuelve a consultar GET /api/v2/templates.

Se dan de alta en Configuración, junto a las claves, o con POST /api/v2/webhooks y el permiso webhooks:write. El body lleva url y events. El secreto de la firma vuelve una sola vez. Cada aviso trae el encabezado X-Waspy-Signature con la forma t= (hora unix), v1= (firma). La firma es HMAC-SHA256 de esa hora, un punto y el cuerpo. Si no cierra, no proceses el pedido. El detalle de reintentos está en Webhooks y en la referencia.

El webhook avisa en el momento. Leer GET /messages/:id es para cuando querés consultar. Las dos cosas sirven para el mismo envío: el POST crea el mensaje y el evento message.status_changed cuenta sent, delivered, read o failed.

Conector MCP, si el cliente no es un HTTP

Waspy tiene un conector en https://api.waspytech.com/mcp. ChatGPT, Claude, Cursor, Codex, Grok y n8n usan esa URL. No hace falta pegar la clave si la persona entra por la pantalla de permiso. Para un cliente que no abre esa pantalla, la API key va en el encabezado de autorización.

send_message manda un texto: pide conversationId y text, y el permiso messages:write. Es un mensaje de sesión, así que la ventana de 24 horas tiene que estar abierta. send_template manda una plantilla ya aprobada: conversationId, templateName y, si hace falta, language y bodyParameters. Las dos le escriben a un cliente. En la pantalla de permiso se puede dejar solo lectura y notas, y el cliente pide una confirmación aparte antes de enviar.

El conector no empuja eventos. Si tu sistema tiene que enterarse solo, el camino es el webhook. Una nota interna o un cambio de etapa no le escriben a la persona. create_template manda la plantilla a revisión de Meta y no se la envía a nadie. La guía de la pantalla está en Conector MCP.

Reglas de Meta que aplican igual

La ventana de 24 horas se abre cuando la persona escribe y dura 24 horas desde su último mensaje. Adentro se puede mandar texto, un archivo o una reacción. Afuera, un texto libre no sale: hace falta una plantilla de WhatsApp aprobada (marketing, utilidad o autenticación). En la API, esa regla es el 403 SERVICE_WINDOW_EXPIRED del POST que no es plantilla.

Una plantilla que inicia el negocio necesita opt-in de WhatsApp: el número solo no alcanza. El POST de un destinatario no filtra la lista de baja de Waspy. El lote sí, si dejás respectOptOut en true. La regla de Meta sigue siendo tuya: no uses una plantilla de marketing con alguien que no aceptó recibirla.

Cuántos usuarios distintos podés contactar con una plantilla lo marca el límite del portfolio de Meta, no este POST ni el tope de 120 pedidos por minuto. Los escalones y qué cuenta están en límites de mensajería de WhatsApp. Responder dentro de la ventana no consume ese escalón.

Waspy o la Cloud API directo con Meta

Las dos usan la Cloud API oficial. Meta cobra los mensajes entregados, directo a la cuenta del negocio. Waspy no agrega markup. La diferencia es qué tenés que construir y dónde queda el chat. El detalle de ir directo (app en Meta for Developers, token, endpoint de webhooks) está en WhatsApp Cloud API.

Con Waspy el número se conecta con el registro embebido, desde el panel. El POST de tu sistema crea la conversación en el mismo inbox donde atiende el equipo. Waspy recibe los eventos de Meta. Tu sistema, si quiere avisos, se suscribe a los cuatro eventos de arriba: no hosteás el webhook de Meta. También están el inbox compartido, los equipos, las campañas con plantillas y el chatbot de pasos, que contesta cuando escriben y no reemplaza a este POST.

Directo con Meta no hay cargo de plataforma. Tu sistema llama a la Graph API, guarda el token y hostea un HTTPS público para los webhooks de Meta. No hay inbox ni equipo salvo que los desarrolles. Conviene si nadie va a atender en una pantalla y ya tenés quién mantenga esa integración. Si el equipo también tiene que ver el chat, la API de Waspy deja el mensaje en la bandeja. El cruce con el CRM está en CRM de WhatsApp con API oficial. Qué es la API oficial, aparte de este POST, está en API de WhatsApp.

En qué planes está y cuánto sale

La plataforma es Starter (US$70/mes), Growth (US$100/mes) y Scale (US$150/mes); Enterprise es a medida. La prueba es de 10 días, sin tarjeta. La fila API de la tabla pública marca la API REST en Scale y Enterprise. Starter y Growth no la incluyen.

Aparte, Meta cobra cada mensaje entregado, sin un recargo de Waspy. Las tarifas de Argentina y qué entra en el cupo de respuestas están en precios de la WhatsApp Business API. El plan de la plataforma arranca en US$70/mes. Mirá el desglose en planes.

Qué usa tu sistema y qué ve el equipo

POST /api/v2/messages

Texto, media, plantilla, interactivo o reacción. La clave es Bearer wspy_ y el permiso es messages:write.

Webhooks firmados

Cuatro eventos a tu URL, con X-Waspy-Signature. El estado del envío vuelve en message.status_changed.

Conector MCP

https://api.waspytech.com/mcp. send_message y send_template, con confirmación. No empuja eventos.

El chat queda en el inbox

El mensaje nace con origin external_api. El equipo lo ve en la misma conversación, sin otro número.

Waspy vs Cloud API directo con Meta

Las dos hablan con la Cloud API oficial y Meta factura los mensajes directo. Cambia qué construís vos y dónde queda el chat.

WaspyCloud API directo con Meta
Mandar desde tu sistemaPOST /api/v2/messagesGraph API de Meta
AutenticaciónBearer wspy_, creada en el panelToken de la app de Meta
Inbox del equipoEl POST entra a la bandejaLo construís
Webhooks hacia tu sistemaCuatro eventos, firma HMACHosteás el webhook de Meta
Alta del númeroRegistro embebido, desde el panelApp en Meta for Developers
Tarifas de MetaDirecto a tu cuenta, sin markupDirecto a tu cuenta
Costo de plataformaDesde US$70/mes; la API REST en Scale y EnterpriseSin cargo de plataforma

La fila API de la tabla pública de planes marca la API REST en Scale y Enterprise. Starter y Growth no crean claves.

Waspy: 10 días gratis sin tarjeta y planes Starter (US$70/mes), Growth (US$100/mes) y Scale (US$150/mes), más Enterprise a medida. La API REST está en Scale y Enterprise. Meta cobra los mensajes directo, sin markup de Waspy. Mirá precios de la WhatsApp Business API.

Ver planes y precios

Preguntas frecuentes

Mandá el primer mensaje desde tu sistema

10 días gratis, sin tarjeta. Conectás el número con el registro embebido de Meta. En Scale o Enterprise creás la clave y el POST entra al inbox del equipo.