Exemplos de integração

Casos de uso completos que você pode rodar de verdade com uma API Key. Todas as chamadas usam o header Authorization: Bearer — veja Autenticação e o Guia de API Key para obter e configurar a chave. Base: https://api.nuvia.ai, prefixo /v1. Cada caso indica os escopos de API Key necessários — conceda apenas esses na criação da chave.

Caso 1 — Enviar sua primeira mensagem

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

Descubra seus canais (inboxes)

Liste as caixas de entrada conectadas à sua 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"]

Obtenha uma conversa

O envio de mensagem é feito dentro de uma conversa. Liste conversas para pegar um conversationId (ou crie uma com POST /v1/conversations).

cURL

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

Envie uma mensagem de texto

POST /v1/messages/send com o conversationId e o 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_DA_CONVERSA",
    "message": { "content": "Olá! Enviado via 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_DA_CONVERSA",
    message: { content: "Olá! Enviado via 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_DA_CONVERSA",
        "message": {"content": "Olá! Enviado via API.", "contentType": "TEXT"},
    },
)

Use contentType: "TEXT" para mensagens de texto.

Leia o histórico da conversa

GET /v1/messages/conversation/:id retorna as mensagens; anexos ficam em GET /v1/messages/conversation/:id/attachments.

cURL

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

Caso 2 — Receber eventos via webhooks

Registre uma URL sua para a Nuvia notificar em tempo real (mensagens, conversas, contatos). Este caso mostra o fluxo ponta a ponta; o formato do payload, a lista completa de eventos e as garantias de entrega estão no guia de Webhooks. Escopos: para registrar e consultar, webhooks:create e webhooks:read; para gerenciar, webhooks:update e webhooks:delete (+ messages:create se você responder automaticamente).

Registre um webhook

POST /v1/webhooks. São 10 eventos válidos: MESSAGE_SENT, MESSAGE_RECEIVED, MESSAGE_DELIVERED, MESSAGE_READ, CONVERSATION_CREATED, CONVERSATION_UPDATED, CONTACT_CREATED, CONTACT_UPDATED, FOLLOWUP_SENT e FIELD_UPDATED — o que cada um entrega está na tabela de eventos.Sua empresa tem um webhook: se já houver um configurado, esta chamada devolve 409. Atualize o existente em vez de criar outro.

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

Campos opcionais: custom_headers (para você validar a origem) e status (ACTIVE/INACTIVE).

Receba os callbacks

Quando um evento ocorre, a Nuvia faz um POST para a sua url, com o header X-Webhook-Event e um corpo de três campos:

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

data traz o recurso do evento — a mensagem, a conversa ou o contato, no mesmo formato dos GET correspondentes. FIELD_UPDATED é a exceção e tem estrutura própria.

Responda 2xx em até 10 segundos e processe em background. Não há retry: se a sua resposta falhar ou estourar o tempo, o evento é perdido. Detalhes em Garantias de entrega.

Reaja ao evento

A partir do callback, você pode agir via API — por exemplo, responder com POST /v1/messages/send (Caso 1) ou baixar anexos com GET /v1/messages/conversation/:id/attachments.

Gerencie a configuração

GET /v1/webhooks devolve um objeto com a configuração da empresa (ou null) — não é uma lista. Use o id desse objeto para atualizar com PUT /v1/webhooks/:id ou remover com DELETE /v1/webhooks/:id. Para pausar sem perder a configuração, prefira PUT com status: "INACTIVE".

Caso 3 — Campanhas e disparo em massa

Escopos: campaigns:create, campaigns:read, campaigns:update, campaigns:delete (+ messages:create para o atalho de template em massa).

Crie a campanha

POST /v1/campaigns. Campos obrigatórios: name, channel_type, trigger_type e audience_config; opcionais incluem description, trigger_config, behavior_config e sender_config. As estruturas internas desses objetos de configuração estão na Referência da API — siga o schema de lá.A audiência é definida na própria criação, dentro de audience_config (por contact_ids, lists ou filters). Não há um passo de matrícula (enrollment) separado a fazer via API — a campanha já nasce com a audiência que você informar aqui.

Confira antes de disparar

Use os previews (não criam nada): POST /v1/campaigns/audience-preview conta os contatos da audiência e POST /v1/campaigns/preview-message resolve as variáveis da mensagem.

Ative e acompanhe

Ative com POST /v1/campaigns/:id/activate (pause com /pause). Acompanhe com GET /v1/campaigns/:id/analytics e GET /v1/campaigns/:id/step-analytics, e exporte os contatos com GET /v1/campaigns/:id/enrollments/export.

cURL

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

Atalho: para enviar um template de WhatsApp para vários contatos sem montar uma campanha, use POST /v1/messages/send-bulk-template (escopo messages:create). O passo a passo, com os parâmetros de template e os limites da Meta, está no guia Template em massa no WhatsApp.

Caso 4 — Sincronizar contatos

Mantenha seu CRM externo e a Nuvia em sincronia. Escopos: contacts:read, contacts:create, contacts:update, contacts:delete.

Cheque duplicidade por telefone

Antes de criar, resolva os telefones para ver quais já existem: 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"]},
)

Crie os contatos que faltam

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

curl -X POST https://api.nuvia.ai/v1/contacts \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Maria",
    "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: "Maria",
    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": "Maria",
        "lastname": "Silva",
        "phone": "+5511999999999",
        "email": "maria@empresa.com",
    },
)

Atualize e liste

Atualize um contato com PUT /v1/contacts/:id (ou só o nome com PUT /v1/contacts/:id/name) e liste/pagine com GET /v1/contacts. Para remover o vínculo de um contato com um CRM externo, use DELETE /v1/contacts/:id/crm-link — isso apenas desfaz a vinculação; o contato continua existindo na Nuvia (não é exclusão de contato).

Outras superfícies públicas

Consumíveis por API Key e cobertas na Referência: Agentes, Tabelas e listas, Conversas e Base de conhecimento. Veja o mapa em Seções da API.

Primeiros passos

Guias

Exemplos de integração

Caso 1 — Enviar sua primeira mensagem

Caso 2 — Receber eventos via webhooks

Caso 3 — Campanhas e disparo em massa

Caso 4 — Sincronizar contatos

Outras superfícies públicas

Próximos passos

Guia de API Key

Referência da API

​Caso 1 — Enviar sua primeira mensagem

​Caso 2 — Receber eventos via webhooks

​Caso 3 — Campanhas e disparo em massa

​Caso 4 — Sincronizar contatos

​Outras superfícies públicas

​Próximos passos

Guia de API Key

Referência da API

Caso 1 — Enviar sua primeira mensagem

Caso 2 — Receber eventos via webhooks

Caso 3 — Campanhas e disparo em massa

Caso 4 — Sincronizar contatos

Outras superfícies públicas

Próximos passos