referencia v1 en producción

Referencia de la API de InstantReply

Construye sobre la REST API de producción para conversaciones de WhatsApp, Instagram y Messenger. Aquí tienes auth, paginación, mensajes, journeys, templates, webhooks firmados, debugging de entregas y endpoints para desarrolladores.

Empezar guía rápida Catálogo de endpoints Hub de desarrolladores

Qué puede construir un desarrollador

Usa InstantReply como la capa de mensajería de tu producto o herramientas internas. Tu backend puede leer conversaciones, enviar respuestas, actualizar contactos, enrutar leads, disparar journeys de WhatsApp, validar templates y reaccionar a mensajes de clientes en tiempo real.

Una superficie versionada

Las rutas REST públicas viven bajo /v1. Las rutas compatibles bajo /api/v1 llegan a la misma API.

Sirve para operación real

Es la misma superficie de producción que usan el dashboard, las automatizaciones, las respuestas IA y los journey sends.

Sin polling

Registra un endpoint webhook y recibe POSTs firmados cuando el cliente responde o cambia una entrega.

Autenticación, paginación y errores

Autentica con una API key con scopes en Authorization: Bearer $IR_API_KEY. Mantén separadas las keys live y test. Puedes rotar keys desde developer settings sin cambiar el secreto de firma del webhook.

authbash

curl https://api.instantreply.co/v1/conversations \
  -H "Authorization: Bearer $IR_API_KEY"

send-messagebash

curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \
  -H "Authorization: Bearer $IR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Thanks for reaching out - how can we help?"}'

Paginación por cursor

Cada endpoint de lista acepta ?cursor= y devuelve el siguiente cursor cuando hay más registros. Trata el cursor como opaco y reenvíalo exactamente como lo recibiste.

Errores predecibles

Los fallos devuelven un envelope JSON con code, message, doc_url y request_id. Guarda X-Request-Id si necesitas que soporte rastree una llamada.

Grupos de endpoints en producción

Estas son las rutas que más usan los desarrolladores. El inventario completo está en el catálogo REST, pero esta página explica para qué sirve cada grupo y cómo encaja en una integración.

Abrir catálogo REST completo

Conversaciones y mensajes

Lee conversaciones, envía respuestas y sincroniza historiales de mensajes.

GET/v1/conversations
Lista conversaciones con filtros por estado, canal, responsable y paginación por cursor.
GET/v1/conversations/:id
Lee una conversación con cliente, canal, etapa, etiquetas y actividad reciente.
PATCH/v1/conversations/:id
Actualiza asignación, estado, etiquetas o reglas de ruta de una conversación.
GET/v1/conversations/:id/messages
Lee el historial de mensajes de una conversación.
POST/v1/conversations/:id/messages
Envía una respuesta por el canal correcto: WhatsApp, Instagram o Messenger.
GET/v1/messages
Lista mensajes de todas las conversaciones para auditoría, sincronización o analítica.
POST/v1/messages
Crea un mensaje saliente cuando tu integración ya conoce el contexto del canal.
GET/v1/messages/:id
Obtiene detalles de contenido y entrega de un mensaje.

Contactos, canales y analítica

Mantén el registro del cliente sincronizado y consulta métricas operativas.

GET/v1/contacts
Lista contactos con etapa, score, owner e identidad de canal.
GET/v1/contacts/:id
Lee un perfil de contacto y su contexto de conversación.
PATCH/v1/contacts/:id
Actualiza campos creados por lead capture o tu CRM.
GET/v1/channels
Lista canales conectados de WhatsApp, Instagram y Messenger.
GET/v1/analytics/summary
Consulta métricas de volumen, respuesta y conversión.
GET/v1/usage
Lee uso de plan para mensajes, IA, webhooks y llamadas API.

Keys y webhooks

Administra API keys y suscribe tu servidor a eventos firmados en tiempo real.

GET/v1/keys
Lista API keys activas y scopes.
POST/v1/keys
Crea una key con scopes para backend, agente o ambiente test.
POST/v1/keys/:id/rotate
Rota una key sin downtime.
DELETE/v1/keys/:id
Revoca una key de inmediato.
GET/v1/webhooks
Lista endpoints webhook.
POST/v1/webhooks
Registra un endpoint webhook firmado.
DELETE/v1/webhooks/:id
Desactiva un endpoint webhook.
GET/v1/webhooks/:id/deliveries
Inspecciona intentos recientes y fallos.

Journeys, triggers y campañas

Dispara journeys de WhatsApp, revisa entregas y sincroniza eventos del negocio.

GET/v1/journeys
Lista journey templates disponibles en tu cuenta.
POST/v1/trigger
Enrola un contacto en un journey o template workflow.
GET/v1/trigger/status/:id
Explica el resultado actual de entrega de un trigger.
POST/v1/trigger/validate
Valida un payload antes de enviarlo.
POST/v1/trigger/batch
Dispara un lote de contactos con resultado por fila.
POST/v1/events
Envía un evento externo de negocio a InstantReply.
POST/v1/campaigns/:id/send
Inicia el envío de una campaña aprobada.

Templates y herramientas developer

Valida, envía y depura templates de WhatsApp sin adivinar política de Meta.

GET/v1/templates
Lista templates y estado desde InstantReply y Meta.
POST/v1/templates
Crea un borrador de template.
POST/v1/templates/:id/validate
Revisa categoria y recibe coaching para UTILITY.
POST/v1/templates/:id/submit
Envía el template a revisión de Meta.
GET/v1/developer/capabilities
Lee scopes, features habilitadas y limites.
GET/v1/developer/onboarding
Consulta checklist de integración.
GET/v1/developer/limits
Consulta rate limits y cuotas.
GET/v1/developer/troubleshooting/errors/:code
Busca un error conocido del proveedor.

Webhooks y seguridad

Registra POST /v1/webhooks una vez y InstantReply enviará eventos en tiempo real a tu servidor. La entrega es at-least-once, así que procesa X-InstantReply-Delivery de forma idempotente.

Verificación de firma

Cada webhook tiene un secreto whsec_. Verifica X-InstantReply-Signature con HMAC-SHA256 sobre timestamp.rawBody antes de confiar en el payload. Los intentos recientes están en GET /v1/webhooks/:id/deliveries.

verify-signaturets

app.post("/webhooks/instantreply", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-InstantReply-Timestamp")
  const signature = req.header("X-InstantReply-Signature")
  const rawBody = req.body.toString("utf8")

  verifyHmacSha256({
    secret: process.env.IR_WEBHOOK_SECRET,
    payload: timestamp + "." + rawBody,
    signature,
  })

  res.sendStatus(204)
})

Eventos actuales
Evento	Cuando se dispara
`message.received`	Un cliente envía un mensaje por WhatsApp, Instagram o Messenger.
`message.sent`	Sale un mensaje desde IA, dashboard, API, automatización o journey.
`conversation.created`	Se abre una conversacion nueva por inbound, coexistence o journey.
`conversation.closed`	Una conversacion queda resuelta manualmente o por automatizacion.
`conversation.assigned`	Cambia el owner por asignación manual o reglas de ruta.
`contact.updated`	Lead extraction o CRM sync actualiza un contacto.
`template.status_update`	Meta reporta revisión o cambio de calidad de un template.
`message.delivery_failed`	El proveedor rechaza o falla una entrega después de reintentos.

Ciclo de vida de templates y debugging

Los endpoints de templates ayudan a publicar templates de WhatsApp con compliance. Valida categoría, envía a Meta, inspecciona resultados del proveedor y explica errores conocidos.

POST /v1/templates/:id/validate revisa categoría y da coaching para UTILITY.
POST /v1/templates/:id/submit envía el template a revisión de Meta.
GET /v1/trigger/status/:id explica resultados de entrega para triggers.
GET /v1/developer/onboarding y /limits muestran setup, features, cuotas y rate limits.

OpenAPI generado en producción

Swagger/OpenAPI generado está disponible en ambientes no productivos para validación interna. Producción no expone /openapi.json de forma intencional. Usa esta referencia, el catálogo REST y la guía rápida como superficie pública.

Checklist para salir a producción

Tu integración está lista cuando esto se cumple.

Usa https://api.instantreply.co/v1 en producción.

Guarda por separado API keys live y test.

Verifica X-InstantReply-Signature antes de aceptar un webhook.

Maneja duplicados con X-InstantReply-Delivery.

Reintenta POST solo con estrategia de idempotencia.

Respeta ventanas de mensajeria del canal y opt-outs.

Referencia de la API de InstantReply

curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \ -H "Authorization: Bearer $IR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text":"Thanks for reaching out - how can we help?"}'

Conversaciones y mensajes

Lee conversaciones, envía respuestas y sincroniza historiales de mensajes.

GET/v1/conversations
Lista conversaciones con filtros por estado, canal, responsable y paginación por cursor.
GET/v1/conversations/:id
Lee una conversación con cliente, canal, etapa, etiquetas y actividad reciente.
PATCH/v1/conversations/:id
Actualiza asignación, estado, etiquetas o reglas de ruta de una conversación.
GET/v1/conversations/:id/messages
Lee el historial de mensajes de una conversación.
POST/v1/conversations/:id/messages
Envía una respuesta por el canal correcto: WhatsApp, Instagram o Messenger.
GET/v1/messages
Lista mensajes de todas las conversaciones para auditoría, sincronización o analítica.
POST/v1/messages
Crea un mensaje saliente cuando tu integración ya conoce el contexto del canal.
GET/v1/messages/:id
Obtiene detalles de contenido y entrega de un mensaje.

app.post("/webhooks/instantreply", express.raw({ type: "application/json" }), (req, res) => { const timestamp = req.header("X-InstantReply-Timestamp") const signature = req.header("X-InstantReply-Signature") const rawBody = req.body.toString("utf8") verifyHmacSha256({ secret: process.env.IR_WEBHOOK_SECRET, payload: timestamp + "." + rawBody, signature, }) res.sendStatus(204) })

Evento

Cuando se dispara

message.received

Un cliente envía un mensaje por WhatsApp, Instagram o Messenger.

message.sent

Sale un mensaje desde IA, dashboard, API, automatización o journey.

conversation.created

Se abre una conversacion nueva por inbound, coexistence o journey.

conversation.closed

Una conversacion queda resuelta manualmente o por automatizacion.

conversation.assigned

Cambia el owner por asignación manual o reglas de ruta.

contact.updated

Lead extraction o CRM sync actualiza un contacto.

template.status_update

Meta reporta revisión o cambio de calidad de un template.

message.delivery_failed

El proveedor rechaza o falla una entrega después de reintentos.