# Nuvia API

## Docs

- [Introdução](https://developers.nuvia.ai/index.md): A API da Nuvia para automação de vendas e atendimento via WhatsApp
- [Início rápido](https://developers.nuvia.ai/quickstart.md): Do zero à sua primeira requisição bem-sucedida na API da Nuvia
- [Guia de API Key](https://developers.nuvia.ai/guia-api-key.md): Como gerar, listar e revogar API Keys da Nuvia, e quais escopos existem
- [Autenticação](https://developers.nuvia.ai/autenticacao.md): Como autenticar suas requisições na API da Nuvia com uma API Key
- [Seções da API](https://developers.nuvia.ai/secoes-da-api.md): Mapa das áreas funcionais da API da Nuvia e os escopos de API Key de cada uma
- [Rate limits](https://developers.nuvia.ai/guias/rate-limits.md): Como a API da Nuvia trata limites de requisição hoje
- [Exemplos de integração](https://developers.nuvia.ai/guias/exemplos-integracao.md): Cenários ponta a ponta com a API da Nuvia: mensagens, webhooks, campanhas e contatos
- [Webhooks](https://developers.nuvia.ai/guias/webhooks.md): Receba eventos da Nuvia no seu servidor: formato do payload, eventos disponíveis e garantias de entrega
- [Template em massa no WhatsApp](https://developers.nuvia.ai/guias/whatsapp-template-massa.md): Dispare um template aprovado do WhatsApp para vários contatos numa única requisição
- [Exemplos de código](https://developers.nuvia.ai/guias/code-samples.md): Snippets reutilizáveis da API da Nuvia em cURL, JavaScript, Python, PHP e Go
- [Coleção Postman](https://developers.nuvia.ai/guias/postman.md): Baixe a coleção oficial da API da Nuvia e importe no Postman para testar os endpoints
- [Buscar a configuração de webhook da empresa](https://developers.nuvia.ai/api-reference/webhooks/buscar-a-configuração-de-webhook-da-empresa.md): Devolve **um objeto** de configuração ou `null` — não é uma lista. Cada empresa tem no máximo um webhook.
- [Criar a configuração de webhook](https://developers.nuvia.ai/api-reference/webhooks/criar-a-configuração-de-webhook.md): Cada empresa tem **no máximo um** webhook. Se já existir um, esta chamada devolve 409 — atualize o existente com `PUT /v1/webhooks/{id}` ou apague com `DELETE /v1/webhooks/{id}` antes de criar outro.
- [Atualizar a configuração de webhook](https://developers.nuvia.ai/api-reference/webhooks/atualizar-a-configuração-de-webhook.md): Use o `id` devolvido por `GET /v1/webhooks`. Webhook de outra empresa devolve 403.
- [Remover a configuração de webhook](https://developers.nuvia.ai/api-reference/webhooks/remover-a-configuração-de-webhook.md): Depois de remover, a empresa volta a poder criar um webhook novo via `POST /v1/webhooks`.
- [Listar mensagens de uma conversa](https://developers.nuvia.ai/api-reference/messages/listar-mensagens-de-uma-conversa.md): Retorna uma lista paginada de mensagens de uma conversa específica
- [Listar anexos de uma conversa](https://developers.nuvia.ai/api-reference/messages/listar-anexos-de-uma-conversa.md): Retorna uma lista paginada de anexos (IMAGE/VIDEO/DOCUMENT) de uma conversa, com URL assinada e contexto do remetente para resolução client-side
- [Enviar mensagem de texto](https://developers.nuvia.ai/api-reference/messages/enviar-mensagem-de-texto.md): Envia uma mensagem de texto simples para uma conversa. Suporta múltiplos tipos de conteúdo (TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT).
- [Enviar template em massa](https://developers.nuvia.ai/api-reference/messages/enviar-template-em-massa.md): Dispara um template aprovado do WhatsApp para vários contatos em uma única requisição (`multipart/form-data`).
- [Listar conversas](https://developers.nuvia.ai/api-reference/conversations/listar-conversas.md): Retorna uma lista paginada de conversas com filtros opcionais (inbox, agente, time, usuários, status, período de datas, etc.).
- [Criar conversa](https://developers.nuvia.ai/api-reference/conversations/criar-conversa.md): Cria uma nova conversa entre um contato e um inbox
- [Buscar conversa por ID](https://developers.nuvia.ai/api-reference/conversations/buscar-conversa-por-id.md): Retorna os dados completos de uma conversa específica
- [Atualizar conversa](https://developers.nuvia.ai/api-reference/conversations/atualizar-conversa.md): Atualiza os dados de uma conversa existente
- [Atribuir usuário à conversa](https://developers.nuvia.ai/api-reference/conversations/atribuir-usuário-à-conversa.md): Atribui um usuário (atendente) a uma conversa específica
- [Atribuir dono à conversa](https://developers.nuvia.ai/api-reference/conversations/atribuir-dono-à-conversa.md): Define o dono (responsável) da conversa vinculando um usuário. NÃO altera quem está respondendo (who_answering) nem coloca a conversa na fila de atendimento humano.
- [Retomar controle da IA](https://developers.nuvia.ai/api-reference/conversations/retomar-controle-da-ia.md): Devolve o controle da conversa para a IA. Opcionalmente gera uma mensagem contextual para o contato.
- [Marcar conversa como lida](https://developers.nuvia.ai/api-reference/conversations/marcar-conversa-como-lida.md): Limpa a marcação "requer atenção" da conversa. A conversa sai do chip "Requer atenção" e do badge, mas o macro estado, o dono, o status e a etapa NÃO mudam. Idempotente: sem atenção pendente, nada é escrito.
- [Atribuir agente à conversa](https://developers.nuvia.ai/api-reference/conversations/atribuir-agente-à-conversa.md): Atribui um agente de IA a uma conversa específica
- [Atribuir time à conversa](https://developers.nuvia.ai/api-reference/conversations/atribuir-time-à-conversa.md): Atribui um time a uma conversa específica
- [Atribuir prioridade à conversa](https://developers.nuvia.ai/api-reference/conversations/atribuir-prioridade-à-conversa.md): Define ou atualiza a prioridade de uma conversa (URGENT, HIGH, NORMAL, LOW)
- [Atualizar status da conversa](https://developers.nuvia.ai/api-reference/conversations/atualizar-status-da-conversa.md): Atualiza o status de uma conversa (OPEN, RESOLVED)
- [Atualizar passo da conversa](https://developers.nuvia.ai/api-reference/conversations/atualizar-passo-da-conversa.md): Atualiza o passo atual do fluxo do agente em uma conversa
- [Listar contatos](https://developers.nuvia.ai/api-reference/contacts/listar-contatos.md): Retorna uma lista paginada de contatos com filtros opcionais (nome, telefone, e-mail, busca textual)
- [Criar contato](https://developers.nuvia.ai/api-reference/contacts/criar-contato.md): Cria um novo contato no sistema. Campos customizados podem ser adicionados via custom_attributes.
- [Listar contatos para CRM](https://developers.nuvia.ai/api-reference/contacts/listar-contatos-para-crm.md): Retorna uma lista paginada de contatos com sua última conversa, filtros por etapa, inbox, status, etc.
- [Buscar contatos por telefones](https://developers.nuvia.ai/api-reference/contacts/buscar-contatos-por-telefones.md): Busca contatos existentes por uma lista de números de telefone. Útil para reconciliação no import de CSV.
- [Listar conversas de um contato](https://developers.nuvia.ai/api-reference/contacts/listar-conversas-de-um-contato.md): Retorna todas as conversas associadas a um contato, com dados populados de inbox, usuário, agente e etapa do funil.
- [Listar campanhas de um contato](https://developers.nuvia.ai/api-reference/contacts/listar-campanhas-de-um-contato.md): Retorna as campanhas em que o contato está inscrito, com nome, status, canal e data de início.
- [Listar listas de um contato](https://developers.nuvia.ai/api-reference/contacts/listar-listas-de-um-contato.md): Retorna as listas (tabelas de contatos) em que o contato está presente, com nome, total de itens e data de inclusão.
- [Listar o histórico de atividade de um contato](https://developers.nuvia.ai/api-reference/contacts/listar-o-histórico-de-atividade-de-um-contato.md): Retorna a timeline agregada do contato (notas, entrada em listas e criação), ordenada da atividade mais recente para a mais antiga.
- [Listar contatos de uma empresa](https://developers.nuvia.ai/api-reference/contacts/listar-contatos-de-uma-empresa.md): Retorna os contatos vinculados ao business, paginado e ordenável por nome ou cargo.
- [Listar contatos vinculados à empresa do contato](https://developers.nuvia.ai/api-reference/contacts/listar-contatos-vinculados-à-empresa-do-contato.md): Retorna os demais contatos da mesma empresa (business) do contato, paginado e ordenável por nome ou cargo.
- [Buscar contato por ID](https://developers.nuvia.ai/api-reference/contacts/buscar-contato-por-id.md): Retorna os dados completos de um contato específico
- [Atualizar contato](https://developers.nuvia.ai/api-reference/contacts/atualizar-contato.md): Atualiza os dados de um contato existente (nome, e-mail, atributos customizados, etc.)
- [Excluir contato](https://developers.nuvia.ai/api-reference/contacts/excluir-contato.md): Remove um contato da base. Só é permitido quando o contato não possui vínculos ativos (conversas, mensagens, campanhas, logs de enriquecimento ou falhas de envio). Nesse caso retorna 409 com o detalhe do que bloqueia. Vínculos de listas e de empresa (employees) são desvinculados automaticamente.
- [Atualizar nome do contato](https://developers.nuvia.ai/api-reference/contacts/atualizar-nome-do-contato.md): Atualiza apenas o nome de um contato específico
- [Desvincular contato de CRM externo](https://developers.nuvia.ai/api-reference/contacts/desvincular-contato-de-crm-externo.md): Remove a referência ao CRM externo (crm_type, crm_external_id, crm_last_synced_at) do contato. Atualmente usado pela ação "Desvincular HubSpot" na listagem de contatos.
- [Listar conhecimentos e mídias](https://developers.nuvia.ai/api-reference/knowledge/listar-conhecimentos-e-mídias.md): Lista todos os conhecimentos e mídias da empresa com paginação e filtros
- [Criar conhecimento ou mídia](https://developers.nuvia.ai/api-reference/knowledge/criar-conhecimento-ou-mídia.md): Envie o arquivo em `multipart/form-data`. Com `type=KNOWLEDGE` (PDF/DOCX) o arquivo é processado para busca semântica e o item nasce `PROCESSING` até virar `READY`. Com `type=MEDIA` (imagem, vídeo, áudio ou documento para envio em conversas) o arquivo é só armazenado e já nasce `READY`.
- [Criar conhecimento em markdown](https://developers.nuvia.ai/api-reference/knowledge/criar-conhecimento-em-markdown.md): Cria um item do tipo AUTCL: conteúdo markdown editável pela própria API, sem upload de arquivo. O texto vira chunks + embeddings em background — o item nasce `PROCESSING` e vai para `READY`. A cada edição os embeddings são regerados.
- [Buscar conhecimento ou mídia por ID](https://developers.nuvia.ai/api-reference/knowledge/buscar-conhecimento-ou-mídia-por-id.md): Retorna os detalhes de um conhecimento ou mídia específico
- [Atualizar conhecimento ou mídia](https://developers.nuvia.ai/api-reference/knowledge/atualizar-conhecimento-ou-mídia.md): Atualiza nome e/ou descrição de um conhecimento ou mídia
- [Listar inboxes](https://developers.nuvia.ai/api-reference/inboxes/listar-inboxes.md): Retorna uma lista paginada de inboxes (canais de atendimento) com filtros opcionais
- [Criar inbox](https://developers.nuvia.ai/api-reference/inboxes/criar-inbox.md): Cria um novo inbox (canal de atendimento) para receber e enviar mensagens. Suporta múltiplos canais: WhatsApp Business API, Evolution API, etc.
- [Buscar inbox por ID](https://developers.nuvia.ai/api-reference/inboxes/buscar-inbox-por-id.md): Retorna os dados completos de um inbox específico
- [Atualizar inbox](https://developers.nuvia.ai/api-reference/inboxes/atualizar-inbox.md): Atualiza as configurações de um inbox existente (nome, webhook, agente padrão, configurações de API, etc.)
- [Deletar inbox](https://developers.nuvia.ai/api-reference/inboxes/deletar-inbox.md): Remove um inbox do sistema (marca como DELETED, não remove fisicamente do banco)
- [Criar tabela manual](https://developers.nuvia.ai/api-reference/tables/criar-tabela-manual.md)
- [Listar tabelas](https://developers.nuvia.ai/api-reference/tables/listar-tabelas.md)
- [Importar tabela](https://developers.nuvia.ai/api-reference/tables/importar-tabela.md)
- [Buscar tabela por ID](https://developers.nuvia.ai/api-reference/tables/buscar-tabela-por-id.md)
- [Remover tabela](https://developers.nuvia.ai/api-reference/tables/remover-tabela.md)
- [Atualizar labels das colunas](https://developers.nuvia.ai/api-reference/tables/atualizar-labels-das-colunas.md)
- [Exportar lista em CSV](https://developers.nuvia.ai/api-reference/tables/exportar-lista-em-csv.md): Exporta as linhas em CSV. Listas respeitam view/filtros/ordenação; datasets exportam as colunas gerenciadas (round-trip do sync por upload).
- [Listar linhas da tabela com paginação](https://developers.nuvia.ai/api-reference/tables/listar-linhas-da-tabela-com-paginação.md)
- [Adicionar linhas à tabela](https://developers.nuvia.ai/api-reference/tables/adicionar-linhas-à-tabela.md)
- [Remover uma linha da tabela](https://developers.nuvia.ai/api-reference/tables/remover-uma-linha-da-tabela.md)
- [Atualizar uma linha da tabela](https://developers.nuvia.ai/api-reference/tables/atualizar-uma-linha-da-tabela.md)
- [Remover múltiplas linhas da tabela em batch](https://developers.nuvia.ai/api-reference/tables/remover-múltiplas-linhas-da-tabela-em-batch.md)
- [Remover todas as linhas da lista](https://developers.nuvia.ai/api-reference/tables/remover-todas-as-linhas-da-lista.md): Remove todas as linhas que atendem aos filtros/view. Pode excluir IDs específicos via excludeRowIds.
- [Criar lista](https://developers.nuvia.ai/api-reference/tables/criar-lista.md): Cria uma lista (`table_kind=list`) para organizar contatos ou empresas. Diferente de um dataset, a lista não é fonte de dados: é um contexto sobre registros que já existem.
- [Inserir linhas em lote](https://developers.nuvia.ai/api-reference/tables/inserir-linhas-em-lote.md): Só para listas. Cada linha precisa de exatamente uma referência — `contact_id` ou `business_id` — compatível com o `object_type` da lista. Duplicatas são ignoradas.
- [Atualizar o campo data de uma linha](https://developers.nuvia.ai/api-reference/tables/atualizar-o-campo-data-de-uma-linha.md): Só para listas. Escreve estado contextual da linha (validação, enriquecimento) sem alterar as referências a contato ou empresa.
- [Importar CSV para uma lista existente](https://developers.nuvia.ai/api-reference/tables/importar-csv-para-uma-lista-existente.md): Importa dados de um CSV para uma lista existente. Cria contatos novos, atualiza existentes conforme fieldResolutions, e vincula à lista. Duplicatas são ignoradas.
- [Listar views de uma lista](https://developers.nuvia.ai/api-reference/tables/listar-views-de-uma-lista.md): Retorna todas as views de uma lista, incluindo a view default.
- [Criar nova view para uma lista](https://developers.nuvia.ai/api-reference/tables/criar-nova-view-para-uma-lista.md): Cria uma nova view personalizada para a lista. Se column_keys não for informado, copia todas as colunas da lista.
- [Excluir view de uma lista](https://developers.nuvia.ai/api-reference/tables/excluir-view-de-uma-lista.md)
- [Atualizar view de uma lista](https://developers.nuvia.ai/api-reference/tables/atualizar-view-de-uma-lista.md): Atualiza nome e/ou ordem das colunas de uma view.
- [Atualizar um dataset por planilha](https://developers.nuvia.ai/api-reference/tables/atualizar-um-dataset-por-planilha.md): Aplica o delta pela coluna-chave, sem apagar o que não veio na planilha. Por padrão gera um preview aguardando confirmação (`POST /:id/sync-reports/{reportId}/confirm`); com `?apply=true` aplica direto. Acompanhe em `GET /:id/sync-reports`.
- [Listar relatórios de sync da tabela](https://developers.nuvia.ai/api-reference/tables/listar-relatórios-de-sync-da-tabela.md): Ordenados do mais recente para o mais antigo.
- [Confirmar um sync abortado por deleção em massa](https://developers.nuvia.ai/api-reference/tables/confirmar-um-sync-abortado-por-deleção-em-massa.md): Reprocessa o mesmo arquivo com a deleção autorizada. Responde 202 e processa em background.
- [Descartar um preview de sync](https://developers.nuvia.ai/api-reference/tables/descartar-um-preview-de-sync.md): Encerra um sync que aguardava confirmação. Nada é aplicado na tabela.
- [Recalcular a coluna _score](https://developers.nuvia.ai/api-reference/tables/recalcular-a-coluna-_score.md): Reaplica o `ranking_config` já configurado nas linhas atuais, sem novo upload.
- [Sugerir a coluna-chave do sync](https://developers.nuvia.ai/api-reference/tables/sugerir-a-coluna-chave-do-sync.md): Analisa a unicidade de cada coluna e devolve `suggested_key` — a primeira coluna com valores únicos, ou `null` se nenhuma servir.
- [Simular o ranking da lista](https://developers.nuvia.ai/api-reference/tables/simular-o-ranking-da-lista.md): Aplica os critérios em memória e devolve o top-N na ordem resultante. Nada é persistido.
- [Configurar o sync por upload](https://developers.nuvia.ai/api-reference/tables/configurar-o-sync-por-upload.md): Define a coluna-chave de negócio (`sync_key_column`) e os critérios de ranking (`ranking_config`) usados a cada sync.
- [Listar agentes](https://developers.nuvia.ai/api-reference/agents/listar-agentes.md): Retorna uma lista de agentes de atendimento.
- [Criar agente](https://developers.nuvia.ai/api-reference/agents/criar-agente.md): Cria um novo agente de atendimento.
- [Clonar agente](https://developers.nuvia.ai/api-reference/agents/clonar-agente.md): Cria uma cópia completa de um agente existente com base no ID fornecido. O novo agente terá todas as configurações idênticas ao original (prompts, configurações gerais, steps e follow-ups), exceto o ID e o nome (que receberá o sufixo "(Cópia)").
- [Buscar agente](https://developers.nuvia.ai/api-reference/agents/buscar-agente.md): Retorna os detalhes de um agente específico.
- [Atualizar agente](https://developers.nuvia.ai/api-reference/agents/atualizar-agente.md): Atualiza as informações de um agente existente.
- [Deletar agente](https://developers.nuvia.ai/api-reference/agents/deletar-agente.md): Remove um agente do sistema.
- [Campanhas ativas que usam o agente](https://developers.nuvia.ai/api-reference/agents/campanhas-ativas-que-usam-o-agente.md): Retorna as campanhas ACTIVE da empresa que ativam este agente (send_config.agent_to_activate). Usado para explicar por que a desativação do agente foi bloqueada.
- [Listar campanhas](https://developers.nuvia.ai/api-reference/campaigns/listar-campanhas.md)
- [Criar nova campanha](https://developers.nuvia.ai/api-reference/campaigns/criar-nova-campanha.md)
- [Simular a audiência da campanha](https://developers.nuvia.ai/api-reference/campaigns/simular-a-audiência-da-campanha.md): Conta os contatos que seriam inscritos, com validação por canal. Nenhuma inscrição é criada.
- [Simular a mensagem da campanha](https://developers.nuvia.ai/api-reference/campaigns/simular-a-mensagem-da-campanha.md): Resolve as variáveis do template a partir de uma linha de lista (`list_id` + `row_id`) ou de um contato (`contact_id`) e devolve a mensagem formatada. Nada é enviado.
- [Contar campanhas por status](https://developers.nuvia.ai/api-reference/campaigns/contar-campanhas-por-status.md)
- [Buscar campanha por ID](https://developers.nuvia.ai/api-reference/campaigns/buscar-campanha-por-id.md)
- [Arquivar campanha](https://developers.nuvia.ai/api-reference/campaigns/arquivar-campanha.md)
- [Atualizar campanha](https://developers.nuvia.ai/api-reference/campaigns/atualizar-campanha.md)
- [Ativar campanha](https://developers.nuvia.ai/api-reference/campaigns/ativar-campanha.md)
- [Disparar step manualmente](https://developers.nuvia.ai/api-reference/campaigns/disparar-step-manualmente.md)
- [Pausar campanha](https://developers.nuvia.ai/api-reference/campaigns/pausar-campanha.md)
- [Analytics da campanha](https://developers.nuvia.ai/api-reference/campaigns/analytics-da-campanha.md): Métricas agregadas por contato único.
- [Analytics da campanha agrupados por step](https://developers.nuvia.ai/api-reference/campaigns/analytics-da-campanha-agrupados-por-step.md)
- [Exportar contatos da campanha em CSV](https://developers.nuvia.ai/api-reference/campaigns/exportar-contatos-da-campanha-em-csv.md)
- [Listar enrollments da campanha](https://developers.nuvia.ai/api-reference/campaigns/listar-enrollments-da-campanha.md)
- [Listar execuções da campanha](https://developers.nuvia.ai/api-reference/campaigns/listar-execuções-da-campanha.md)
- [Listar execuções de um enrollment específico](https://developers.nuvia.ai/api-reference/campaigns/listar-execuções-de-um-enrollment-específico.md)
- [Criar inscrições em massa a partir de contact_ids](https://developers.nuvia.ai/api-reference/campaign-enrollments/criar-inscrições-em-massa-a-partir-de-contact_ids.md): Inscreve os contatos informados na campanha. Contatos já inscritos são ignorados; a resposta traz `created` e `skipped`.
- [Criar inscrições em massa a partir de listas](https://developers.nuvia.ai/api-reference/campaign-enrollments/criar-inscrições-em-massa-a-partir-de-listas.md): Processa em background e retorna imediatamente com `jobId` e `status: processing`. O progresso é publicado no WebSocket, no evento `campaign:enrollment:progress`.
- [Criar inscrições em massa a partir do funil](https://developers.nuvia.ai/api-reference/campaign-enrollments/criar-inscrições-em-massa-a-partir-do-funil.md): Inscreve os contatos do funil do agente, opcionalmente restritos a uma etapa (`agent_step_id`) e a filtros por campo (`match_criteria`).
- [Listar enrollments da campanha](https://developers.nuvia.ai/api-reference/campaign-enrollments/listar-enrollments-da-campanha.md)
- [Inscrever um contato na campanha](https://developers.nuvia.ai/api-reference/campaign-enrollments/inscrever-um-contato-na-campanha.md): Cria o contato se ele ainda não existir e o inscreve na campanha. Identifique por `contact.phone` (E.164) e/ou `contact.linkedin_identifier` — ao menos um; campanha de WhatsApp exige phone, de LinkedIn exige linkedin. Só campanhas ACTIVE (409 caso contrário). Conversa ativa ou canal incompatível dev…
- [MCP da Nuvia](https://developers.nuvia.ai/mcp-nuvia.md): Conecte assistentes de IA (Claude, ChatGPT, Cursor) aos dados da sua empresa na Nuvia via MCP

## OpenAPI Specs

- [user-json](https://api.nuvia.ai/api/docs/user-json)
- [openapi](https://developers.nuvia.ai/openapi.json)