Envía tu primer mensaje con ZAPPIO

En esta guía vas de cuenta nueva a tu primer mensaje de WhatsApp enviado por API. Dura unos pasos y no necesitas instalar nada más que curl.

Cada paso dice dónde ocurre:

• En el panel se hace desde la aplicación web de ZAPPIO, con clics.
• Por API se hace con una petición HTTP; los comandos están listos para copiar.

Tu API key es una contraseña

Los ejemplos usan zp_... como valor de ejemplo. Nunca pegues una API key real en un repositorio, un chat o código que corre en el navegador.

1. Crea tu cuenta En el panel

Regístrate en ZAPPIO con tu nombre, correo de trabajo y contraseña. No pide tarjeta: empiezas con la prueba gratuita (50 mensajes salientes en total, sin límite de días).

Después verifica tu correo con el enlace que te enviamos. Hasta que lo hagas, el panel muestra un aviso con la opción de reenviarlo, y no podrás crear claves API ni webhooks.

2. Crea tu espacio de trabajo En el panel

La primera vez, el panel te pide un nombre para tu espacio de trabajo: ahí viven tus instancias, tus claves API y tus webhooks. Puedes cambiarlo después.

3. Agrega una instancia En el panel

Una instancia es un número de WhatsApp conectado a ZAPPIO.

1. Abre Instancias y elige Agregar instancia.
2. Ponle un nombre (por ejemplo, Ventas) y elige Crear.

4. Conecta tu número En el panel

1. Abre la instancia y elige Conectar WhatsApp. En unos segundos aparece un código QR.
2. En tu teléfono abre WhatsApp, entra a Dispositivos vinculados, toca Vincular un dispositivo y apunta la cámara al QR.
3. Espera a que el estado de la instancia cambie a Conectado.

El QR se renueva solo mientras esperas. Si algo falla, consulta la guía de Instancias y conexión.

También por API

Crear la instancia y pedir el QR también se puede hacer por API (POST /instances, POST /instances/{instance}/connect, GET /instances/{instance}/qr). Está explicado en Instancias y conexión.

5. Crea tu API key En el panel

1. Abre Claves API y elige Crear clave API.
2. Ponle un nombre (por ejemplo, Producción) y marca los permisos: para este Quickstart basta messages:send e instances:read.
3. Elige Crear clave y Copiar. La clave se muestra una sola vez: si la pierdes, revócala y crea otra.

En tu terminal, guarda la clave y la URL de la API en variables de entorno:

export ZAPPIO_API_URL="https://zappio.cloud"
export ZAPPIO_API_KEY="zp_..."   # pega aquí tu clave

URL de la API

ZAPPIO_API_URL es la dirección base de la API de tu cuenta, sin /api/v1 al final. Todos los ejemplos de esta documentación la usan.

6. Comprueba tu API key Por API

curl "$ZAPPIO_API_URL/api/v1/api-key" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

Si la clave es válida, responde con su nombre, sus permisos y tu espacio de trabajo:

{
  "data": {
    "id": "key_01EXAMPLE00000000000000001",
    "name": "Producción",
    "scopes": ["instances:read", "messages:send"],
    "workspace": { "id": "ten_01EXAMPLE00000000000000001", "name": "Acme" }
  }
}

Un 401 INVALID_API_KEY significa que la clave no existe o fue revocada; un 401 UNAUTHENTICATED, que falta el header Authorization.

7. Busca el id de tu instancia Por API

curl "$ZAPPIO_API_URL/api/v1/instances" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

Busca tu instancia conectada y copia su id (empieza con ins_). Debe tener "status": "connected":

{
  "data": [
    {
      "id": "ins_01EXAMPLE00000000000000001",
      "name": "Ventas",
      "status": "connected",
      "phone_number": "5215500000003",
      "paired": true
    }
  ]
}

(La respuesta real trae más campos; aquí solo se muestran los que necesitas ahora.)

export ZAPPIO_INSTANCE="ins_..."   # pega aquí el id de tu instancia

8. Envía tu primer mensaje Por API

Reemplaza to por el número de WhatsApp que recibirá el mensaje, con código de país (para probar, usa el tuyo):

curl -X POST "$ZAPPIO_API_URL/api/v1/messages" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: primer-mensaje-1" \
  -d '{
    "instance": "'"$ZAPPIO_INSTANCE"'",
    "to": "5215500000000",
    "type": "text",
    "text": "Hola desde ZAPPIO"
  }'

ZAPPIO responde 202 Accepted: el mensaje ya está en cola y sale en segundo plano.

{
  "data": {
    "id": "msg_01EXAMPLE00000000000000001",
    "instance_id": "ins_01EXAMPLE00000000000000001",
    "direction": "outbound",
    "type": "text",
    "status": "queued",
    "to": "5215500000000",
    "text": "Hola desde ZAPPIO",
    "queued_at": "2026-01-31T14:05:09+00:00"
  }
}

Unos segundos después, el mensaje llega al teléfono. El header Idempotency-Key es opcional pero recomendable: si repites exactamente la misma petición con la misma clave, no se genera un nuevo envío (ver Idempotencia).

9. Sigue el estado del mensaje Por API

El envío es asíncrono. Consulta el mensaje con el id que recibiste:

curl "$ZAPPIO_API_URL/api/v1/messages/msg_..." \
  -H "Authorization: Bearer $ZAPPIO_API_KEY"

El campo status avanza así:

Estado	Significa
queued	ZAPPIO recibió el mensaje y lo tiene en cola.
processing	Se 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 dice por qué.

sent, delivered y read dependen de WhatsApp y pueden llegar con retraso o saltarse. Para no consultar una y otra vez, recibe los cambios por webhook.

Si algo no sale

Respuesta	Qué pasó	Qué hacer
401 INVALID_API_KEY	La clave no existe o fue revocada.	Crea otra en Claves API.
403 INSUFFICIENT_SCOPE	A la clave le falta el permiso.	Crea una con messages:send.
409 INSTANCE_NOT_CONNECTED	La instancia no está conectada.	Conéctala desde el panel (paso 4).
422 INVALID_RECIPIENT	to no es un número válido ni un grupo.	Usa el formato internacional, con código de país.
402 TRIAL_LIMIT_REACHED	Usaste los 50 mensajes de la prueba.	Revisa Prueba y planes.

Todos los errores están en la guía de Errores.

Siguiente paso: recibe eventos por webhook

Ya envías mensajes. Para saber cuándo se entregan o se leen, y para recibir lo que tus clientes responden, configura un webhook: Webhooks.