Integración (API REST)

Antes de empezar #

Necesitas una instancia conectada y una API key. Todas las respuestas llegan como { "data": ... } y los errores como { "error": { "code", "message", "details", "traceId" } }.

1. 1
   Paso 1: Revisa que la instancia diga «Conectada» en Instancias
2. 2
   Paso 2: Crea una API key con el permiso messages.sendY messages.read si vas a consultar estados.
3. 3
   Paso 3: Envía la llave en el header X-API-KeyTambién se acepta Authorization: Bearer <key>.
4. 4
   Paso 4: Si tienes varias instancias, elige cuál usar en «Instancia para los ejemplos»

Relacionado: Instancias · API keys

Enviar un mensaje por API #

Haz un POST a /instances/<ID>/messages con el número destino (to), el texto y, opcionalmente, una referencia de tu sistema. La respuesta 202 trae el mensaje con estado queued: entró a la cola y saldrá en orden. Ejemplo con curl: curl -X POST "https://chat-digital.com/api/v1/instances/1/messages" -H "X-API-Key: TU_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: pedido-1234-confirmacion" -d '{"to":"5215512345678","text":"Tu pedido #1234 fue confirmado.","reference":"pedido-1234"}'

1. 1
   Paso 1: Copia el ejemplo de «2. Enviar un mensaje» en la pantalla Integración
2. 2
   Paso 2: Reemplaza TU_API_KEY por tu llave y el número por uno de prueba
3. 3
   Paso 3: Ejecútalo y guarda el id que regresa en data.id

Evitar duplicados con Idempotency-Key #

Si tu sistema reintenta un envío (por un timeout o un reinicio), el header Idempotency-Key evita que el cliente reciba el mensaje dos veces: con la misma llave, la API devuelve el mensaje original (200) en lugar de enviar otro. Usa un valor derivado del evento de negocio, por ejemplo pedido-1234-confirmacion, no un valor aleatorio en cada intento.

Instancia desconectada: queueIfOffline #

Por omisión, si la instancia no está conectada la API responde 409 INSTANCE_NOT_READY y el mensaje no se guarda. Si envías "queueIfOffline": true, el mensaje espera en cola hasta 24 horas y sale cuando la instancia se conecte; si no se conecta a tiempo, queda Fallido con «Expiró en cola».

Relacionado: Instancias

Consultar el estado #

Consulta GET /messages/<id> o busca por tu referencia con GET /messages?reference=pedido-1234. Los estados son queued → sending → sent → delivered → read (played en notas de voz) o failed con el motivo en error. Mejor aún: configura un webhook con el evento message.status y recibe cada cambio sin consultar.

Relacionado: Mensajes · Webhooks

Errores comunes #

400 VALIDATION_ERROR: datos inválidos; error.details dice qué campo. 401: API key inválida, revocada o expirada. 403: a la llave le falta el permiso o está limitada a otra instancia (TENANT_SUSPENDED si la cuenta está suspendida). 409 INSTANCE_NOT_READY: la instancia no está conectada; usa queueIfOffline. 429 QUOTA_EXCEEDED: se alcanzó el límite diario del plan (se reinicia a las 00:00 UTC). 429 RATE_LIMITED: más de 300 peticiones por minuto con la misma llave.