Enviar mensajes

Todo se envía con un solo endpoint: POST /api/v1/messages. Necesitas una clave con el scope messages:send y una instancia conectada.

Enviar un texto

curl -X POST "https://zappio.cloud/api/v1/messages" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{
    "instance": "ins_...",
    "to": "5215500000000",
    "type": "text",
    "text": "Tu pedido 1042 va en camino"
  }'

Campo	Qué es
instance	El id de la instancia desde la que se envía (ins_...).
to	El destinatario: un número en formato internacional o un id de grupo (grp_...).
type	text, image, document, audio o video.
text	El mensaje, de hasta 4096 caracteres (para type: text).

to como número: con código de país primero. Los espacios, guiones, paréntesis y un + inicial se ignoran; deben quedar entre 8 y 15 dígitos. Si es un grupo, usa su id (ver Grupos).

Qué responde la API

El envío es asíncrono. La API responde 202 Accepted en cuanto el mensaje queda en cola, sin esperar a WhatsApp:

{
  "data": {
    "id": "msg_01EXAMPLE00000000000000001",
    "instance_id": "ins_01EXAMPLE00000000000000001",
    "direction": "outbound",
    "type": "text",
    "status": "queued",
    "to": "5215500000000",
    "from": null,
    "group_id": null,
    "text": "Tu pedido 1042 va en camino",
    "created_at": "2026-01-31T14:05:09+00:00",
    "queued_at": "2026-01-31T14:05:09+00:00",
    "sent_at": null,
    "delivered_at": null,
    "read_at": null
  }
}

Guarda el id del mensaje: sirve para consultarlo y para relacionarlo con los eventos que llegan por webhook.

Ciclo de vida de un mensaje

queued → processing → sent → delivered → read, o failed.

Estado	Significa
queued	En cola.
processing	ZAPPIO lo está enviando.
sent	WhatsApp lo aceptó.
delivered	Llegó al teléfono del destinatario.
read	El destinatario lo leyó.
failed	No se pudo enviar. error.code explica el motivo.

Los estados sent, delivered y read dependen de WhatsApp: pueden llegar tarde o saltarse alguno. Los mensajes que recibes de tus clientes tienen direction: "inbound" y status: "received".

Un mensaje failed trae error.code: MESSAGE_SEND_EXPIRED, INSTANCE_NOT_CONNECTED, INVALID_RECIPIENT, RECIPIENT_NOT_ON_WHATSAPP, MEDIA_UNAVAILABLE, UNSUPPORTED_MESSAGE_TYPE, GATEWAY_UNAVAILABLE o MESSAGE_SEND_FAILED.

Seguir un mensaje

Por webhook (recomendado): recibes message.sent, message.delivered, message.read y message.failed sin consultar. Ver Webhooks.

Por consulta: GET /api/v1/messages/{message} (scope messages:read) devuelve el mensaje con su estado actual.

curl "https://zappio.cloud/api/v1/messages/msg_..." -H "Authorization: Bearer $ZAPPIO_API_KEY"

GET /api/v1/messages lista tus mensajes (enviados y recibidos), los más recientes primero, con paginación por cursor (ver Convenciones). Acepta filtros por instance, direction, type y status.

Errores frecuentes al enviar

Respuesta	Código	Qué hacer
409	INSTANCE_NOT_CONNECTED	Conecta la instancia (Instancias).
422	INVALID_RECIPIENT	to no es un número válido ni un id de grupo.
422	UNSUPPORTED_MESSAGE_TYPE	El tipo no existe o la instancia no puede enviarlo.
404	INSTANCE_NOT_FOUND	El id de instancia no existe en tu espacio de trabajo.
402	TRIAL_LIMIT_REACHED	Se usaron los mensajes de la prueba (planes).
429	SEND_BACKLOG	La instancia tiene demasiados mensajes en espera; reintenta tras Retry-After.

La lista completa está en Errores. Para reintentar un envío sin riesgo de duplicarlo, usa Idempotencia.