> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nuvia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Exemplos de integração

> Cenários ponta a ponta com a API da Nuvia: mensagens, webhooks, campanhas e contatos

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](/autenticacao) e o [Guia de API Key](/guia-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`.

<Steps>
  <Step title="Descubra seus canais (inboxes)">
    Liste as caixas de entrada conectadas à sua empresa.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.nuvia.ai/v1/inboxes \
        -H "Authorization: Bearer $NUVIA_API_KEY"
      ```

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

      ```python Python theme={null}
      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"]
      ```
    </CodeGroup>
  </Step>

  <Step title="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`).

    ```bash cURL theme={null}
    curl "https://api.nuvia.ai/v1/conversations" \
      -H "Authorization: Bearer $NUVIA_API_KEY"
    ```
  </Step>

  <Step title="Envie uma mensagem de texto">
    `POST /v1/messages/send` com o `conversationId` e o objeto `message`.

    <CodeGroup>
      ```bash cURL theme={null}
      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" }
        }'
      ```

      ```javascript JavaScript theme={null}
      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" },
        }),
      });
      ```

      ```python Python theme={null}
      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"},
          },
      )
      ```
    </CodeGroup>

    O campo `message.contentType` aceita `TEXT`, `IMAGE`, `AUDIO`, `DOCUMENT` ou `VIDEO`.
  </Step>

  <Step title="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):

    <CodeGroup>
      ```bash cURL theme={null}
      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" }
        }'
      ```

      ```javascript JavaScript theme={null}
      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" },
        }),
      });
      ```

      ```python Python theme={null}
      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"},
          },
      )
      ```
    </CodeGroup>

    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](/api-reference/messages).
  </Step>

  <Step title="Leia o histórico da conversa">
    `GET /v1/messages/conversation/:id` retorna as mensagens; anexos ficam em
    `GET /v1/messages/conversation/:id/attachments`.

    ```bash cURL theme={null}
    curl "https://api.nuvia.ai/v1/messages/conversation/ID_DA_CONVERSA" \
      -H "Authorization: Bearer $NUVIA_API_KEY"
    ```
  </Step>
</Steps>

## 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).

<Steps>
  <Step title="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`.

    <CodeGroup>
      ```bash cURL theme={null}
      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"
        }'
      ```

      ```javascript JavaScript theme={null}
      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",
        }),
      });
      ```

      ```python Python theme={null}
      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",
          },
      )
      ```
    </CodeGroup>

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

  <Step title="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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Gerencie os webhooks">
    Consulte a configuração com `GET /v1/webhooks`, atualize com `PUT /v1/webhooks/:id` e remova com
    `DELETE /v1/webhooks/:id`.
  </Step>
</Steps>

## 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).

<Steps>
  <Step title="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](/api-reference/campaigns) — 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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.

    ```bash cURL theme={null}
    curl -X POST https://api.nuvia.ai/v1/campaigns/ID_DA_CAMPANHA/activate \
      -H "Authorization: Bearer $NUVIA_API_KEY"
    ```
  </Step>
</Steps>

<Note>
  **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](/api-reference/messages).
</Note>

## Caso 4 — Sincronizar contatos

Mantenha seu CRM externo e a Nuvia em sincronia.

**Escopos:** `contacts:read`, `contacts:create`, `contacts:update`, `contacts:delete`.

<Steps>
  <Step title="Cheque duplicidade por telefone">
    Antes de criar, resolva os telefones para ver quais já existem: `POST /v1/contacts/find-by-phones`.

    <CodeGroup>
      ```bash cURL theme={null}
      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"] }'
      ```

      ```javascript JavaScript theme={null}
      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"] }),
      });
      ```

      ```python Python theme={null}
      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"]},
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Crie os contatos que faltam">
    `POST /v1/contacts`. Campos: `firstname`, `lastname`, `phone`, `email`, `company` e `properties`.

    <CodeGroup>
      ```bash cURL theme={null}
      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"
        }'
      ```

      ```javascript JavaScript theme={null}
      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",
        }),
      });
      ```

      ```python Python theme={null}
      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",
          },
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="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).
  </Step>
</Steps>

## 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](/secoes-da-api).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia de API Key" icon="key" href="/guia-api-key">
    Escopos, criação e revogação de chaves.
  </Card>

  <Card title="Referência da API" icon="code" href="/api-reference">
    Todos os endpoints, parâmetros e respostas.
  </Card>
</CardGroup>