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"},
    },
)

O campo message.contentType aceita TEXT, IMAGE, AUDIO, DOCUMENT ou VIDEO.

Envie mídia (opcional)

Para mídia há endpoints dedicados. POST /v1/messages/send-image usa o mesmo formato, com contentType: "IMAGE" e attachment (o ID de um anexo já enviado):

curl -X POST https://api.nuvia.ai/v1/messages/send-image \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "ID_DA_CONVERSA",
    "message": { "content": "Legenda da imagem", "contentType": "IMAGE", "attachment": "ID_DO_ANEXO" }
  }'

await fetch("https://api.nuvia.ai/v1/messages/send-image", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversationId: "ID_DA_CONVERSA",
    message: { content: "Legenda da imagem", contentType: "IMAGE", attachment: "ID_DO_ANEXO" },
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/messages/send-image",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "conversationId": "ID_DA_CONVERSA",
        "message": {"content": "Legenda da imagem", "contentType": "IMAGE", "attachment": "ID_DO_ANEXO"},
    },
)

De forma análoga, POST /v1/messages/send-audio, /send-document e /send-video enviam os demais tipos — veja os campos de cada um na Referência da API.

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). 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. Os eventos válidos são MESSAGE_SENT, MESSAGE_RECEIVED, CONVERSATION_CREATED, CONVERSATION_UPDATED, FOLLOWUP_SENT, FIELD_UPDATED, CONTACT_CREATED e CONTACT_UPDATED.

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. Seu servidor deve responder rápido com 2xx para confirmar o recebimento.

O formato exato do payload de saída ainda não está publicado nesta documentação. Trate o corpo recebido de forma defensiva (valide os campos que usar) e, se precisar da estrutura garantida, confirme com o time da Nuvia. Use custom_headers para autenticar que a chamada veio da Nuvia.

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 os webhooks

Consulte a configuração com GET /v1/webhooks, atualize com PUT /v1/webhooks/:id e remova com DELETE /v1/webhooks/:id.

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; multipart/form-data). Veja os campos na Referência da API.

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