Ejemplos de integración

Casos de uso completos que puede ejecutar de verdad con una API key. Todas las llamadas usan el header Authorization: Bearer. Consulte Autenticación y la Guía de API key para obtener y configurar la clave. Base: https://api.nuvia.ai, prefijo /v1. Cada caso indica los scopes de API key necesarios. Otorgue solo esos al crear la clave.

Caso 1: Enviar su primer mensaje

Scopes: inboxes:read, conversations:read, messages:read, messages:create.

Descubra sus canales (inboxes)

Liste las inboxes conectadas a su empresa.

curl https://api.nuvia.ai/v1/inboxes \
  -H "Authorization: Bearer $NUVIA_API_KEY"

const res = await fetch("https://api.nuvia.ai/v1/inboxes", {
  headers: { Authorization: `Bearer ${process.env.NUVIA_API_KEY}` },
});
const { data } = await res.json();

import os, requests
res = requests.get(
    "https://api.nuvia.ai/v1/inboxes",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
)
data = res.json()["data"]

Obtenga una conversación

El envío de un mensaje se hace dentro de una conversación. Liste conversaciones para obtener un conversationId (o cree una con POST /v1/conversations).

cURL

curl "https://api.nuvia.ai/v1/conversations" \
  -H "Authorization: Bearer $NUVIA_API_KEY"

Envíe un mensaje de texto

POST /v1/messages/send con el conversationId y el objeto message.

curl -X POST https://api.nuvia.ai/v1/messages/send \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "ID_DE_LA_CONVERSACION",
    "message": { "content": "¡Hola! Enviado vía API.", "contentType": "TEXT" }
  }'

await fetch("https://api.nuvia.ai/v1/messages/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversationId: "ID_DE_LA_CONVERSACION",
    message: { content: "¡Hola! Enviado vía API.", contentType: "TEXT" },
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/messages/send",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "conversationId": "ID_DE_LA_CONVERSACION",
        "message": {"content": "¡Hola! Enviado vía API.", "contentType": "TEXT"},
    },
)

Use contentType: "TEXT" para mensajes de texto.

Lea el historial de la conversación

GET /v1/messages/conversation/:id devuelve los mensajes; los adjuntos están en GET /v1/messages/conversation/:id/attachments.

cURL

curl "https://api.nuvia.ai/v1/messages/conversation/ID_DE_LA_CONVERSACION" \
  -H "Authorization: Bearer $NUVIA_API_KEY"

Caso 2: Recibir eventos vía webhooks

Registre una URL propia para que Nuvia le notifique en tiempo real (mensajes, conversaciones, contactos). Este caso muestra el flujo de principio a fin; el formato del payload, la lista completa de eventos y las garantías de entrega están en la guía de Webhooks. Scopes: para registrar y consultar, webhooks:create y webhooks:read; para gestionar, webhooks:update y webhooks:delete (+ messages:create si responde automáticamente).

Registre un webhook

POST /v1/webhooks. Son 10 eventos válidos: MESSAGE_SENT, MESSAGE_RECEIVED, MESSAGE_DELIVERED, MESSAGE_READ, CONVERSATION_CREATED, CONVERSATION_UPDATED, CONTACT_CREATED, CONTACT_UPDATED, FOLLOWUP_SENT y FIELD_UPDATED. Consulte lo que cada uno entrega en la tabla de eventos.Su empresa tiene un webhook: si ya hay uno configurado, esta llamada devuelve 409. Actualice el existente en lugar de crear otro.

curl -X POST https://api.nuvia.ai/v1/webhooks \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/nuvia/webhook",
    "events": ["MESSAGE_RECEIVED", "CONVERSATION_CREATED"],
    "status": "ACTIVE"
  }'

await fetch("https://api.nuvia.ai/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://tu-servidor.com/nuvia/webhook",
    events: ["MESSAGE_RECEIVED", "CONVERSATION_CREATED"],
    status: "ACTIVE",
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "url": "https://tu-servidor.com/nuvia/webhook",
        "events": ["MESSAGE_RECEIVED", "CONVERSATION_CREATED"],
        "status": "ACTIVE",
    },
)

Campos opcionales: custom_headers (para que usted valide el origen) y status (ACTIVE/INACTIVE).

Reciba los callbacks

Cuando ocurre un evento, Nuvia hace un POST a su url, con el header X-Webhook-Event y un cuerpo de tres campos:

{
  "event": "MESSAGE_RECEIVED",
  "timestamp": "2026-08-13T14:03:00.000Z",
  "data": {}
}

data trae el recurso del evento: el mensaje, la conversación o el contacto, en el mismo formato de los GET correspondientes. FIELD_UPDATED es la excepción y tiene estructura propia.

Responda 2xx en hasta 10 segundos y procese en background. No hay retry: si su respuesta falla o excede el tiempo, el evento se pierde. Detalles en Garantías de entrega.

Reaccione al evento

A partir del callback, puede actuar vía API: responda con POST /v1/messages/send (Caso 1) o descargue adjuntos con GET /v1/messages/conversation/:id/attachments.

Gestione la configuración

GET /v1/webhooks devuelve un objeto con la configuración de la empresa (o null). No es una lista. Use el id de ese objeto para actualizar con PUT /v1/webhooks/:id o eliminar con DELETE /v1/webhooks/:id. Para pausar sin perder la configuración, prefiera PUT con status: "INACTIVE".

Caso 3: Campañas y envío masivo

Scopes: campaigns:create, campaigns:read, campaigns:update, campaigns:delete (+ messages:create para el atajo de plantilla en masa).

Cree la campaña

POST /v1/campaigns. Campos obligatorios: name, channel_type, trigger_type y audience_config; los opcionales incluyen description, trigger_config, behavior_config y sender_config. Las estructuras internas de estos objetos de configuración están en la Referencia de la API. Siga el esquema de allí.La audiencia se define en la propia creación, dentro de audience_config (por contact_ids, lists o filters). No hay un paso de inscripción (enrollment) separado que hacer vía API. La campaña ya nace con la audiencia que se indique aquí.

Verifique antes de enviar

Use las vistas previas (no crean nada): POST /v1/campaigns/audience-preview cuenta los contactos de la audiencia y POST /v1/campaigns/preview-message resuelve las variables del mensaje.

Active y monitoree

Active con POST /v1/campaigns/:id/activate (pause con /pause). Monitoree con GET /v1/campaigns/:id/analytics y GET /v1/campaigns/:id/step-analytics, y exporte los contactos con GET /v1/campaigns/:id/enrollments/export.

cURL

curl -X POST https://api.nuvia.ai/v1/campaigns/ID_DE_LA_CAMPANA/activate \
  -H "Authorization: Bearer $NUVIA_API_KEY"

Atajo: para enviar una plantilla de WhatsApp a varios contactos sin armar una campaña, use POST /v1/messages/send-bulk-template (scope messages:create). El paso a paso, con los parámetros de plantilla y los límites de Meta, está en la guía Envío masivo de plantillas en WhatsApp.

Caso 4: Sincronizar contactos

Mantenga su CRM externo y Nuvia sincronizados. Scopes: contacts:read, contacts:create, contacts:update, contacts:delete.

Verifique duplicados por teléfono

Antes de crear, resuelva los teléfonos para ver cuáles ya existen: POST /v1/contacts/find-by-phones.

curl -X POST https://api.nuvia.ai/v1/contacts/find-by-phones \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phones": ["+5511999999999", "+5511888888888"] }'

const res = await fetch("https://api.nuvia.ai/v1/contacts/find-by-phones", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phones: ["+5511999999999", "+5511888888888"] }),
});

import os, requests
res = requests.post(
    "https://api.nuvia.ai/v1/contacts/find-by-phones",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={"phones": ["+5511999999999", "+5511888888888"]},
)

Cree los contactos que faltan

POST /v1/contacts. Campos: firstname, lastname, phone, email, company y properties.

curl -X POST https://api.nuvia.ai/v1/contacts \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "María",
    "lastname": "Silva",
    "phone": "+5511999999999",
    "email": "maria@empresa.com"
  }'

await fetch("https://api.nuvia.ai/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstname: "María",
    lastname: "Silva",
    phone: "+5511999999999",
    email: "maria@empresa.com",
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "firstname": "María",
        "lastname": "Silva",
        "phone": "+5511999999999",
        "email": "maria@empresa.com",
    },
)

Actualice y liste

Actualice un contacto con PUT /v1/contacts/:id (o solo el nombre con PUT /v1/contacts/:id/name) y liste/pagine con GET /v1/contacts. Para quitar el vínculo de un contacto con un CRM externo, use DELETE /v1/contacts/:id/crm-link: esto solo deshace la vinculación; el contacto sigue existiendo en Nuvia (no es una eliminación de contacto).

Otras superficies públicas

Consumibles por API key y cubiertas en la Referencia: Agentes, Tablas y listas, Conversaciones y Base de conocimiento. Vea el mapa en Secciones de la API.

Primeros pasos

Guías

Ejemplos de integración

Caso 1: Enviar su primer mensaje

Caso 2: Recibir eventos vía webhooks

Caso 3: Campañas y envío masivo

Caso 4: Sincronizar contactos

Otras superficies públicas

Próximos pasos

Guía de API key

Referencia de la API

​Caso 1: Enviar su primer mensaje

​Caso 2: Recibir eventos vía webhooks

​Caso 3: Campañas y envío masivo

​Caso 4: Sincronizar contactos

​Otras superficies públicas

​Próximos pasos

Guía de API key

Referencia de la API

Caso 1: Enviar su primer mensaje

Caso 2: Recibir eventos vía webhooks

Caso 3: Campañas y envío masivo

Caso 4: Sincronizar contactos

Otras superficies públicas

Próximos pasos