# NexTags Desenvolvedores > Documentação para desenvolvedores da NexTags: API REST, webhooks, exemplos de código e integração com IA (llms.txt e MCP). Endereço: https://docs.nextags.com.br/ Tipo: Página _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._ --- # Começar > Autenticação, primeira requisição, limites e os identificadores que a API usa. Endereço: https://docs.nextags.com.br/comecar/ Tipo: Seção ## Páginas - [Visão geral da API](https://docs.nextags.com.br/comecar/visao-geral.md): O que a API REST da NexTags faz em cada recurso, a URL base e o formato das respostas, dos IDs, das datas e do dinheiro. E o que fica fora dela. - [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao.md): Guarde a chave de API numa variável de ambiente, mande no cabeçalho X-ACCESS-TOKEN, reconheça o erro 401 e troque a chave sem parar as integrações. - [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao.md): Consulte os dados da conta com GET /accounts/me em cURL, JavaScript, Python ou PHP, entenda a resposta e saiba o que fazer com o erro 401. - [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores.md): Onde achar o ID de contato, fluxo, etiqueta, campo, pipeline, etapa, oportunidade, administrador, agente, produto, pedido e disparo, pela API e pela tela. - [Limites, erros e boas práticas](https://docs.nextags.com.br/comecar/limites-e-erros.md): Os códigos de resposta da API, o formato do erro, quantas chamadas planejar por minuto, a paginação e como repetir chamadas sem duplicar contatos e envios. - [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis.md): Campo personalizado (um valor por contato), campo do bot (um valor da conta) e campos do sistema: o formato de cada valor e como ler e gravar cada um pela API. - [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes.md): O formato JSON de mensagens e ações da NexTags (texto, botões, respostas rápidas, mídia, cartões, galeria e as 8 ações), com os limites e onde ele vale. _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._ --- # Visão geral da API > O que a API REST da NexTags faz em cada recurso, a URL base e o formato das respostas, dos IDs, das datas e do dinheiro. E o que fica fora dela. Endereço: https://docs.nextags.com.br/comecar/visao-geral/ Tipo: Conceito Atualizado em: 26/10/2026 A API da NexTags deixa o seu sistema trabalhar com a conta sem abrir o painel: criar e achar contatos, enviar fluxos e mensagens, pôr etiquetas, preencher campos, mover oportunidades, cuidar do carrinho e dos pedidos e acompanhar os Broadcasts. É uma API REST: cada recurso tem um endereço, e as respostas vêm em JSON. Toda chamada leva a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` e sai do seu servidor. Comece por [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/) e [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/). ## Como funciona ### O que a API faz | Recurso | O que dá para fazer | Referência | |---|---|---| | Conta | Consultar os dados da conta e listar os administradores, as equipes e as integrações ligadas. | [Conta](https://docs.nextags.com.br/referencia/conta/) | | Contatos | Criar um contato, consultar pelo ID e buscar pelo telefone, pelo e-mail ou por um campo personalizado. | [Contatos](https://docs.nextags.com.br/referencia/contatos/) | | Mensagens | Enviar ao contato um fluxo, um texto, um arquivo ou um conteúdo com várias mensagens e ações. | [Mensagens](https://docs.nextags.com.br/referencia/mensagens/) | | Etiquetas | Listar, criar, buscar pelo nome e apagar etiquetas; pôr e tirar etiquetas do contato. | [Etiquetas](https://docs.nextags.com.br/referencia/etiquetas/) | | Campos personalizados | Listar, criar e buscar campos pelo nome; ler, preencher e limpar o valor de cada contato. | [Campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados/) | | Campos do bot | Ler, preencher e limpar um campo do bot, o valor único da conta. | [Campos do bot](https://docs.nextags.com.br/referencia/campos-do-bot/) | | Fluxos e modelos | Listar os fluxos; instalar na conta um modelo da ferramenta **Templates** e gerar um link de uso único dele. | [Fluxos e modelos](https://docs.nextags.com.br/referencia/fluxos/) | | Pipelines | Listar pipelines, etapas e campos; criar, consultar, atualizar, transferir e apagar oportunidades; comentar. | [Pipelines e oportunidades](https://docs.nextags.com.br/referencia/pipelines/) | | Agentes de IA | Listar e consultar os agentes do AI Hub; atualizar o prompt, o modelo e o limite de tokens; listar funções, servidores MCP e arquivos; salvar mensagens no histórico da IA do contato. | [Agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/) | | E-commerce | Consultar e atualizar produtos (preço, estoque e se está ativo); enviar produtos; mexer no carrinho; consultar e alterar pedidos e marcar como pagos. | [E-commerce](https://docs.nextags.com.br/referencia/ecommerce/) | | Disparos | Listar, consultar, reenviar e cancelar Broadcasts. | [Disparos](https://docs.nextags.com.br/referencia/disparos/) | | Agenda | Listar e consultar os calendários do **Gestor de Agendamentos**. | [Agenda](https://docs.nextags.com.br/referencia/agenda/) | | Ferramentas | Formatar números, trocar e recortar textos, codificar URLs, gerar QR Code e hash e calcular distâncias, para usar nas requisições externas dos fluxos. | [Ferramentas](https://docs.nextags.com.br/referencia/ferramentas/) | ### O endereço e os métodos A URL base é `https://app.nextagsai.com.br/api`. Junte a ela o caminho do endpoint: ```http GET https://app.nextagsai.com.br/api/accounts/me X-ACCESS-TOKEN: ``` - `GET` lê, `POST` cria e altera (inclusive para atualizar oportunidades, produtos e pedidos) e `DELETE` apaga ou limpa. A API não usa `PUT` nem `PATCH`. - As respostas vêm em JSON. No erro de chave, o corpo é JSON, mas o cabeçalho `Content-Type` vem `text/html`: leia o corpo como JSON sem olhar o cabeçalho. Veja [Limites, erros e boas práticas](https://docs.nextags.com.br/comecar/limites-e-erros/). ### Corpo em JSON ou em formulário O corpo vai em JSON (`Content-Type: application/json`), menos nestas chamadas, que recebem formulário (`application/x-www-form-urlencoded`): | Chamada | Campo | |---|---| | [Criar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/), `POST /accounts/tags` | `name` | | [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/), `POST /contacts/{contact_id}/custom_fields/{custom_field_id}` | `value` | | [Preencher campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot/), `POST /accounts/bot_fields/{bot_field_id}` | `value` | | [Adicionar produto ao carrinho](https://docs.nextags.com.br/referencia/ecommerce/adicionar-produto-ao-carrinho/), `POST /contacts/{contact_id}/cart/{product_id}` | `quantity` | | [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/), `POST /contacts/{contact_id}/pay/{order_id}` | `amount_received` | | As [ferramentas](https://docs.nextags.com.br/referencia/ferramentas/), `POST /tools/...`, menos `/tools/echo` | os campos de cada ferramenta | Quatro chamadas não levam corpo: [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/), [Reenviar disparo](https://docs.nextags.com.br/referencia/disparos/reenviar-disparo/), [Cancelar disparo](https://docs.nextags.com.br/referencia/disparos/cancelar-disparo/) e [Gerar link de uso único do modelo](https://docs.nextags.com.br/referencia/fluxos/gerar-link-de-uso-unico-do-modelo/). ### Listas Umas listas vêm direto, como `[...]`; outras vêm dentro de `data`, como `{"data": [...]}`: | Formato | Chamadas | |---|---| | `[...]` | Etiquetas, campos personalizados, fluxos, administradores e equipes da conta; etiquetas e campos de um contato. | | `{"data": [...]}` | Busca de contatos, pipelines, etapas, oportunidades, comentários, agentes de IA, funções, servidores MCP, arquivos dos agentes, calendários e disparos. | ### IDs - Os IDs são números inteiros: contato, fluxo, etiqueta, campo, pipeline, etapa, oportunidade, agente, produto, disparo, calendário. Guarde em inteiro de 64 bits ou como texto. - O ID do pedido (`order_id`) é texto. - Na busca de contatos, o `field_id` aceita o ID de um campo e também `phone` e `email`. Onde achar cada um: [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ### Datas e horas | Onde | Formato | Exemplo | |---|---|---| | Datas dos objetos, como `created_at`, `updated_at` e `subscribed_date` | Texto em UTC, `AAAA-MM-DD HH:MM:SS` | `2026-10-26 12:00:00` (9h em Brasília) | | `last_sent`, `last_delivered`, `last_seen` e `last_interaction` do contato | Unix timestamp em milissegundos | `1793016000000` | | Valor de um campo personalizado do tipo Data ou Data e hora | Unix timestamp em segundos | `1794279600` (10/11/2026, 0h em Brasília) | Converta para o fuso da sua conta antes de mostrar a data a alguém. ### Dinheiro | Valor | Unidade | Exemplo | |---|---|---| | `total`, `subtotal` e `coupon_discount` do carrinho e do pedido | Centavos | `17980` = R$ 179,80 | | `amount_received` de [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/) | Centavos | `17980` = R$ 179,80 | | `price` de cada item do carrinho (`line_items`) | Reais, não centavos | `89.9` = R$ 89,90 | | `price` e `sale_price` do produto | Reais, não centavos | `89.9` = R$ 89,90 | | `value` da oportunidade | O contrato não diz | Confira no seu teste como o valor aparece no cartão. | ### O que a API não faz | Você quer | Como fazer | |---|---| | Listar todos os contatos | Não há lista de contatos. Busque pelo telefone, pelo e-mail ou por um campo ([guia](https://docs.nextags.com.br/guias/buscar-contato-por-campo/)) ou exporte na tela ([Exportar contatos](https://help.nextags.com.br/tutoriais/contatos/exportar-contatos/)). | | Mudar o nome, o telefone ou o e-mail de um contato | Não há chamada de atualizar contato. Use a ação `set_field_value` com `first_name`, `last_name`, `full_name`, `phone` ou `email` em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). | | Apagar um contato | Na tela, nas [ações em massa de Contatos](https://help.nextags.com.br/tutoriais/contatos/acoes-em-massa/), ou num fluxo, com a ação **Excluir Contato** ([Todas as ações do fluxo](https://help.nextags.com.br/tutoriais/fluxos/acoes-do-fluxo/)). | | Ler as conversas e as mensagens da Caixa de Entrada | Não há. Para levar dados da conversa ao seu sistema, use a [requisição externa no fluxo](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/) ou os [webhooks de saída](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/). | | Criar um Broadcast | Na tela: [Criar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/criar-disparo/). A API lista, consulta, reenvia e cancela ([guia](https://docs.nextags.com.br/guias/disparos-pela-api/)). | | Enviar um Modelo de Mensagem do WhatsApp | Monte um fluxo que comece com o modelo ([Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/)) e envie o fluxo ([guia](https://docs.nextags.com.br/guias/enviar-fluxo/)). | | Inscrever um contato numa sequência | Num fluxo, com a ação **Inscrever-se em uma sequência** ([Inscrever e cancelar inscrição em sequência](https://help.nextags.com.br/tutoriais/fluxos/iniciar-sequencia/)). Pela API, envie esse fluxo. | | Criar fluxos, pipelines, etapas, agentes de IA ou produtos | Na tela. | | Listar pedidos ou criar agendamentos | Na tela. A API consulta um pedido pelo ID e lista os calendários. | ### Arquivos para baixar O contrato da API está na [Referência](https://docs.nextags.com.br/referencia/#arquivos-para-baixar), em dois formatos: o [OpenAPI em JSON](https://docs.nextags.com.br/openapi.json), para gerar clientes e dar contexto a uma IA, e a [coleção do Postman](https://docs.nextags.com.br/nextags.postman_collection.json), para testar as chamadas. ## Quando usar - O seu sistema precisa agir na NexTags quando algo acontece nele, como uma venda, um cadastro ou um pagamento: chame a API. - A NexTags precisa avisar o seu sistema, ou um fluxo precisa de dados dele: use os [webhooks](https://docs.nextags.com.br/webhooks/visao-geral/). - Você quer ligar ferramentas sem programar: use a API pelo [Make, n8n e Zapier](https://docs.nextags.com.br/guias/make-n8n-zapier/). - Uma IA vai escrever a integração: entregue a ela [a documentação pronta para IA](https://docs.nextags.com.br/ia/documentacao-para-ia/). ## Boas práticas > **Chame a API do seu servidor:** > A chave dá acesso à conta inteira. Nunca a coloque no código do navegador nem no app do celular: qualquer pessoa veria a chave. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). > **Procure antes de criar:** > Antes de criar um contato, uma etiqueta ou uma oportunidade, procure se já existe. Assim uma nova tentativa não duplica dados. Veja [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/). > **Guarde os IDs:** > Depois de achar o ID de uma etiqueta, de um campo ou de um fluxo, guarde no seu sistema. Os IDs não mudam quando o nome muda, e você economiza chamadas. --- # Autenticação com a chave de API > Guarde a chave de API numa variável de ambiente, mande no cabeçalho X-ACCESS-TOKEN, reconheça o erro 401 e troque a chave sem parar as integrações. Endereço: https://docs.nextags.com.br/comecar/autenticacao/ Tipo: Guia Atualizado em: 26/10/2026 A API da NexTags reconhece a conta pela chave de API: cada chamada leva a chave no cabeçalho `X-ACCESS-TOKEN`. Neste guia, você guarda a chave fora do código, faz uma chamada autenticada, aprende a reconhecer o erro de chave e a trocar a chave quando precisar. **Antes de começar** - A chave de API da conta, gerada em **Configurações** › **Integrações** › **Chave de API do NexTags** › **Gerar**. O passo a passo com prints está em [Gerar a chave de API](https://help.nextags.com.br/tutoriais/configuracoes/chave-de-api/). - Acesso de **Super Administrador**: só ele abre as **Configurações**. Veja [Administradores e permissões](https://help.nextags.com.br/tutoriais/configuracoes/administradores-e-permissoes/). - Um servidor ou computador para rodar os exemplos, com cURL, Node 18 ou mais novo, Python 3 com `requests` ou PHP com a extensão cURL. ## Passo a passo ### Passo 1: Guarde a chave numa variável de ambiente Guarde a chave numa variável de ambiente chamada `NEXTAGS_API_KEY`, na máquina que vai chamar a API. Assim a chave não fica escrita no código nem vai parar no Git. **Guardar a chave** ```bash export NEXTAGS_API_KEY="cole-aqui-a-chave" ``` ```powershell $env:NEXTAGS_API_KEY = "cole-aqui-a-chave" ``` Em produção, cadastre a variável no painel da hospedagem, do contêiner ou da função, ou no cofre de segredos que você usa. Todos os exemplos desta documentação leem a chave de `NEXTAGS_API_KEY`. > **A chave age como a conta inteira:** > A chave não tem permissões por área: com ela, dá para ler os contatos, enviar mensagens e mexer em etiquetas, pipelines, pedidos e agentes da conta. A conta tem uma chave só, a mesma no Zapier, no Make, no Pabbly, no n8n e no seu sistema. Por isso, a chamada sai sempre do servidor, nunca do navegador nem do app do celular: lá, qualquer pessoa veria a chave. ### Passo 2: Mande a chave no cabeçalho X-ACCESS-TOKEN Em toda chamada, mande o cabeçalho `X-ACCESS-TOKEN` com a chave. Para testar, use [Consultar a conta](https://docs.nextags.com.br/referencia/conta/consultar-a-conta/), que só lê os dados da conta: **Consultar a conta** ```bash curl "https://app.nextagsai.com.br/api/accounts/me" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/accounts/me", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Com a chave certa, a resposta é `200` com os dados da conta. Os campos estão em [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/). ### Passo 3: Reconheça o erro de chave Sem a chave, com a chave incompleta ou com uma chave que foi excluída, a API responde `401`, em qualquer endereço, com este corpo: ```json {"error": {"code": 401, "message": "No valid API key provided."}} ``` O cabeçalho `Content-Type` dessa resposta vem `text/html; charset=UTF-8`, mas o corpo é JSON. Leia o corpo como JSON sem confiar no cabeçalho. Trate o `401` como chave errada: repetir a chamada não resolve. **Tratar o 401** ```bash curl -i "https://app.nextagsai.com.br/api/accounts/me" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); // json() lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave const dados = await resposta.json(); if (resposta.status === 401) { throw new Error(`Chave de API recusada: ${dados.error.message}`); } console.log(dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/accounts/me", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) # json() lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave dados = resposta.json() if resposta.status_code == 401: raise RuntimeError("Chave de API recusada: " + dados["error"]["message"]) print(dados) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); // json_decode lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave $dados = json_decode(curl_exec($ch), true); if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 401) { throw new RuntimeException('Chave de API recusada: ' . $dados['error']['message']); } print_r($dados); ``` ### Passo 4: Troque a chave quando precisar Troque a chave se ela vazou ou se alguém que a conhecia saiu da equipe. Em **Configurações** › **Integrações** › **Chave de API do NexTags**, clique em **Excluir** e depois em **Gerar**. A chave antiga para de valer: atualize a variável de ambiente e todas as ferramentas que usavam a antiga. **Trocar a chave no servidor** ```bash export NEXTAGS_API_KEY="cole-aqui-a-chave-nova" ``` ```powershell $env:NEXTAGS_API_KEY = "cole-aqui-a-chave-nova" ``` > **O Excluir não pede confirmação:** > Entre o **Excluir** e o **Gerar**, a conta fica sem chave, e toda chamada recebe `401`. Deixe abertas as ferramentas que usam a chave (Zapier, Make, Pabbly, n8n, o seu sistema) e troque tudo de uma vez. ## Pronto: como conferir - [Consultar a conta](https://docs.nextags.com.br/referencia/conta/consultar-a-conta/) responde `200`, com o `name` da sua conta. - O cartão **Chave de API do NexTags** mostra o selo **Ativa**. ## Se não funcionou ### 401 com "No valid API key provided." A chave não veio, veio incompleta ou foi excluída. Confira o nome do cabeçalho (`X-ACCESS-TOKEN`) e copie a chave inteira, sem espaços no começo ou no fim. Se a chave foi trocada, use a nova. ### O cliente HTTP diz que a resposta não é JSON O erro de chave vem com `Content-Type: text/html`, mas o corpo é JSON. Leia o texto do corpo e converta para JSON você mesmo, sem depender do cabeçalho. ### A chamada funciona no meu computador e falha no servidor A variável `NEXTAGS_API_KEY` não chegou ao processo do servidor. Cadastre a variável no painel da hospedagem, do contêiner ou da função e reinicie a aplicação. ### Não vejo a aba Integrações Só **Super Administrador** abre as **Configurações**. Peça a um Super Administrador para gerar a chave e entregar por um canal seguro, como o cofre de senhas da equipe. ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Vou integrar o meu sistema à API da NexTags. Leia https://docs.nextags.com.br/comecar/autenticacao.md e https://docs.nextags.com.br/comecar/primeira-requisicao.md. Meu sistema usa [linguagem e framework, por exemplo: Node 20 com Express]. Escreva um módulo cliente da API que lê a chave da variável de ambiente NEXTAGS_API_KEY, manda o cabeçalho X-ACCESS-TOKEN em toda chamada, lê o corpo como JSON mesmo quando o Content-Type vem text/html e lança um erro claro quando a resposta for 401. Não peça a minha chave. ``` --- # Sua primeira requisição > Consulte os dados da conta com GET /accounts/me em cURL, JavaScript, Python ou PHP, entenda a resposta e saiba o que fazer com o erro 401. Endereço: https://docs.nextags.com.br/comecar/primeira-requisicao/ Tipo: Guia Atualizado em: 26/10/2026 A primeira chamada é a mais simples da API: [Consultar a conta](https://docs.nextags.com.br/referencia/conta/consultar-a-conta/), `GET /accounts/me`. Ela só lê os dados da conta e não muda nada, por isso serve para conferir a chave e o seu ambiente antes de qualquer integração. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - Uma destas opções: cURL; Node 18 ou mais novo (o `fetch` já vem pronto); Python 3 com `requests` (`pip install requests`); ou PHP com a extensão cURL. ## Passo a passo ### Passo 1: Faça a chamada O endereço é a URL base da API, `https://app.nextagsai.com.br/api`, mais o caminho `/accounts/me`. Rode o exemplo da sua linguagem no servidor ou no seu computador, nunca no navegador nem num app de celular, onde a chave ficaria à mostra. **Consultar a conta** ```bash curl "https://app.nextagsai.com.br/api/accounts/me" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/accounts/me", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Em JavaScript, salve o código como `primeira.mjs` e rode `node primeira.mjs`: o `await` fora de uma função só funciona em arquivo `.mjs`. Em Python e em PHP, rode o arquivo como de costume (`python primeira.py`, `php primeira.php`). ### Passo 2: Leia a resposta Com a chave certa, a resposta é `200`, com os dados da conta: ```json { "page_id": 123456, "name": "Doce Encanto", "active": true, "created": 1768478400, "total_users": 4210 } ``` | Campo | O que é | |---|---| | `page_id` | O ID da conta. | | `name` | O nome da conta. | | `active` | `false` quando os administradores não conseguem entrar no painel da conta. | | `created` | Quando a conta foi criada, em Unix timestamp. O contrato não diz se em segundos ou em milissegundos: confira no seu teste. | | `total_users` | O total de contatos da conta. | ### Passo 3: Se vier 401, confira a chave Se a resposta for `401`, a chave não veio, está incompleta ou foi excluída. O corpo é sempre este: ```json {"error": {"code": 401, "message": "No valid API key provided."}} ``` O cabeçalho `Content-Type` desse erro vem `text/html`, mas o corpo é JSON: os exemplos acima leem o corpo do mesmo jeito. Confira a variável `NEXTAGS_API_KEY` e veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Pronto: como conferir - A resposta é `200`, e o `name` é o nome da sua conta, o mesmo que aparece no painel da NexTags. - Agora é só escolher o próximo passo: [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/), [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo/) ou a [Referência da API](https://docs.nextags.com.br/referencia/). ## Se não funcionou ### 401 com "No valid API key provided." A chave está errada ou não chegou à chamada. Copie a chave inteira, sem espaços, e confira o nome do cabeçalho: `X-ACCESS-TOKEN`. Se a chave foi excluída e gerada de novo, use a nova. ### A chave chega vazia A variável `NEXTAGS_API_KEY` não existe no processo que roda o código: o JavaScript manda `undefined`, o Python para com `KeyError` e o PHP manda a chave vazia. Defina a variável no mesmo terminal ou serviço que roda o código. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### JavaScript: erro no await ou "fetch is not defined" O `await` fora de uma função pede um arquivo `.mjs` (ou `"type": "module"` no `package.json`). O `fetch` pronto pede o Node 18 ou mais novo: confira com `node --version`. ### Python: "No module named 'requests'" Instale a biblioteca com `pip install requests` e rode de novo. ### PHP: "Call to undefined function curl_init()" A extensão cURL do PHP está desligada. Instale ou ative a extensão (no Linux, o pacote costuma se chamar `php-curl`) e rode de novo. ### A chamada fica parada O servidor não alcança `app.nextagsai.com.br` pela porta 443. Confira a internet e o firewall. Ponha sempre um tempo limite nas chamadas, como o `timeout=30` do exemplo em Python. ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/comecar/primeira-requisicao.md. Escreva, em [linguagem], um script que chama GET /accounts/me na API da NexTags com a chave da variável de ambiente NEXTAGS_API_KEY e mostra o nome da conta e o total de contatos. Se a resposta for 401, mostre uma mensagem dizendo que a chave está errada. Não peça a minha chave. ``` --- # Contatos, fluxos e outros identificadores > Onde achar o ID de contato, fluxo, etiqueta, campo, pipeline, etapa, oportunidade, administrador, agente, produto, pedido e disparo, pela API e pela tela. Endereço: https://docs.nextags.com.br/comecar/identificadores/ Tipo: Conceito Atualizado em: 26/10/2026 Quase toda chamada da API pede um ID no caminho, como `/contacts/{contact_id}/send/{flow_id}`. Os IDs são números inteiros (o do pedido é texto) e não mudam quando o nome muda. Cada um pode ser achado por uma chamada da própria API e, em vários casos, também na tela da NexTags. ## Como funciona Em cada tabela, **API** é a chamada que lista ou busca o item e **Tela** é onde o ID aparece no painel da NexTags. Os números de exemplo são os mesmos de todos os guias. ### Contato: `contact_id` | Onde | Como achar | |---|---| | API | [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/): `GET /contacts/find_by_custom_field?field_id=phone&value=5511988776655` (ou `field_id=email`). O ID é o `id` de cada contato em `data`. Veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/). | | Tela | Na **Caixa de Entrada**, o painel do contato mostra o **ID de contato** para quem tem a permissão **Ver e-mail e telefone dos contatos**. Em **Contatos**, clicar num contato abre a conversa numa aba nova, com o endereço `inbox?acc=&id=`. | | Fluxo | O campo do sistema `{{user_id}}` traz o ID. A [requisição externa](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/) manda o ID no cabeçalho `X-USER-ID`. | Exemplo: `123456789`. ### Fluxo: `flow_id` | Onde | Como achar | |---|---| | API | [Listar fluxos](https://docs.nextags.com.br/referencia/fluxos/listar-fluxos/): `GET /accounts/flows` devolve o `id` e o `name` de cada fluxo. | | Tela | Em **Fluxos**, abra o fluxo: o endereço do editor traz `flow?id=`. No menu ⋮ do fluxo, **Obter Link** mostra os links do fluxo em cada canal, e todos terminam com o ID, como `https://wa.me/5511999990000?text=/1000001`. No editor, **Obter ID da Etapa** da etapa inicial copia o ID do fluxo. | Exemplo: `1000001`. ### Etiqueta: `tag_id` | Onde | Como achar | |---|---| | API | [Listar etiquetas](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas/) (`GET /accounts/tags`) ou [Buscar etiqueta pelo nome](https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome/) (`GET /accounts/tags/name/{tag_name}`). [Criar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/) devolve o `id` da nova. | | Tela | **Fluxos** › aba **Etiquetas** › menu ⋮ da etiqueta › **Obter ID**: o ID vai para a área de transferência. | Exemplo: `2001`. ### Campo personalizado: `custom_field_id` | Onde | Como achar | |---|---| | API | [Listar campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-personalizados/) (`GET /accounts/custom_fields`) ou [Buscar campo pelo nome](https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/) (`GET /accounts/custom_fields/name/{custom_field_name}`). [Criar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/) devolve o `id` do novo. | | Tela | **Fluxos** › aba **Campo Personalizados** › menu ⋮ do campo › **Obter ID**. | Exemplo: `3001`. ### Campo do bot: `bot_field_id` | Onde | Como achar | |---|---| | API | Não há uma chamada que liste só os campos do bot. Criar o campo com [Criar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/) e `"isBotField": true` devolve o `id`. | | Tela | **Fluxos** › aba **Campo Personalizados** › seção **Campo Personalizados do Bot** › menu ⋮ do campo › **Obter ID**. | Exemplo: `3101`. ### Pipeline: `pipeline_id` | Onde | Como achar | |---|---| | API | [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/): `GET /pipelines`. | | Tela | Em **Pipelines**, abra o pipeline: o endereço traz `board?acc=&id=`. | Exemplo: `4001`. ### Etapa do pipeline: `stage_id` | Onde | Como achar | |---|---| | API | [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/): `GET /pipelines/{pipeline_id}/stages`. A oportunidade traz a etapa em `stage.id`. | | Tela | O ID da etapa não aparece na tela. | Exemplo: `4101`. ### Oportunidade: `opportunity_id` | Onde | Como achar | |---|---| | API | [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/): `GET /pipelines/{pipeline_id}/opportunities`, com `contact_id` para filtrar por contato. [Criar oportunidade](https://docs.nextags.com.br/referencia/pipelines/criar-oportunidade/) devolve a oportunidade criada. | | Tela | No cartão aberto, o campo **Número**. No cartão fechado, o número aparece como `#4201` quando **ID da Oportunidade** está ligado nas **Definições** do pipeline, em **Elementos visíveis do cartão**. | Exemplo: `4201`. ### Comentário da oportunidade: `comment_id` | Onde | Como achar | |---|---| | API | [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/). [Comentar na oportunidade](https://docs.nextags.com.br/referencia/pipelines/comentar-na-oportunidade/) devolve o comentário com o `id`. | | Tela | O ID do comentário não aparece na tela. | Exemplo: `4301`. ### Administrador: `admin_id` e `assigned_admins` | Onde | Como achar | |---|---| | API | [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores/): `GET /accounts/admins` devolve o `id`, o nome e o e-mail de cada um. | | Tela | O ID do administrador não aparece na tela. | Exemplo: `10001`. O mesmo ID vale no `admin_id` da ação `assign_conversation` e na lista `assigned_admins` da oportunidade. ### Equipe | Onde | Como achar | |---|---| | API | [Listar equipes](https://docs.nextags.com.br/referencia/conta/listar-equipes/): `GET /accounts/teams` devolve o `id` e o `name` de cada equipe. | | Tela | O ID da equipe não aparece na tela. | ### Agente de IA: `agent_id` | Onde | Como achar | |---|---| | API | [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/): `GET /agents/`. | | Tela | No **AI Hub**, clique no agente: o endereço do editor traz `agent?acc=&id=`. | Exemplo: `5001`. ### Produto: `product_id` | Onde | Como achar | |---|---| | API | Não há lista de produtos. O ID aparece no `id` de cada item do carrinho (`line_items`), em [Consultar carrinho](https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/). | | Tela | **Ferramentas** › **Ecommerce** › aba **Produtos**: clique no produto, e o endereço traz `product?id=`. | Exemplo: `6001`. ### Pedido: `order_id` | Onde | Como achar | |---|---| | API | Não há lista de pedidos. O carrinho do contato traz o `order_id`, em [Consultar carrinho](https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/). | | Tela | Na **Caixa de Entrada**, o painel do contato lista os **Pedidos**; o link de cada um traz `order?acc=&id=`. | | Fluxo | O campo do sistema `{{order_id}}` traz o ID do pedido. Mande para o seu sistema numa [requisição externa](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/). | Exemplo: `PED-1001`. O ID do pedido é texto: mande do jeito que veio. ### Disparo (Broadcast): `broadcast_id` | Onde | Como achar | |---|---| | API | [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/): `GET /broadcasts`. | | Tela | O ID do Broadcast não aparece na lista de **Broadcasts**. | Exemplo: `7001`. ### Calendário: `calendar_id` | Onde | Como achar | |---|---| | API | [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios/): `GET /calendars`. | | Tela | **Ferramentas** › **Gestor de Agendamentos**: clique no calendário, e o endereço traz `calendar?id=`. O **Obter Link** do calendário também traz o ID, em `booking/?id=`. | Exemplo: `8001`. ### Modelo da ferramenta Templates: `template_id` e `template_key` | Onde | Como achar | |---|---| | API | Não há lista de modelos. | | Tela | **Ferramentas** › **Templates** › menu ⋮ do modelo › **Obter Link** copia `…store/template?id=&key=`. [Instalar modelo na conta](https://docs.nextags.com.br/referencia/fluxos/instalar-modelo-na-conta/) pede os dois. Veja [Templates: copiar conteúdo entre contas](https://help.nextags.com.br/tutoriais/ferramentas/templates/). | Exemplo: `9001`. ## Quando usar - Comece pela API quando o seu sistema precisa achar o item sozinho, como o contato que acabou de comprar. - Use a tela para pegar uma vez os IDs fixos da integração, como o do fluxo de boas-vindas, o da etiqueta de cliente e o do pipeline de vendas, e guarde no seu sistema. - Os nomes mudam e podem se repetir; os IDs não. Prefira guardar o ID. ## Boas práticas > **Guarde os IDs fixos na configuração:** > Fluxo, etiqueta, campo, pipeline e etapa quase nunca mudam. Guarde os IDs na configuração do seu sistema, ao lado da chave (fora do código), em vez de buscar pelo nome a cada chamada. > **Nomes vão na URL codificados:** > Ao buscar pelo nome (`/accounts/tags/name/{tag_name}`), codifique o nome para a URL: espaços e acentos viram `%20`, `%C3%A3` e assim por diante. Use `encodeURIComponent` no JavaScript, `urllib.parse.quote` no Python e `rawurlencode` no PHP. --- # Limites, erros e boas práticas > Os códigos de resposta da API, o formato do erro, quantas chamadas planejar por minuto, a paginação e como repetir chamadas sem duplicar contatos e envios. Endereço: https://docs.nextags.com.br/comecar/limites-e-erros/ Tipo: Referência Atualizado em: 26/10/2026 Esta página junta o que o contrato da API diz sobre respostas e erros, o que foi conferido na produção e as regras para tratar falhas sem criar dados repetidos. O que não está aqui não foi confirmado: trate como erro qualquer resposta fora do esperado e guarde o corpo inteiro no seu registro. ## Códigos de resposta | Código | O que quer dizer | |---|---| | `200` | Deu certo. A resposta traz os dados pedidos ou `{"success": true}`. | | `400` | Algum dado da chamada está errado ou faltando. | | `401` | A chave de API não veio ou não vale. Acontece em qualquer endereço. | | `402` | A operação não foi feita (só em duas chamadas de pedido, abaixo). | | `404` | O item não existe na conta. | O que cada endpoint diz no contrato, além do `200` e do `401`: | Endpoint | Código | Quando | |---|---|---| | [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/) | `400` | O ID do contato é inválido. | | [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/) | `404` | O contato não existe. | | [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/) | `400` | Parâmetros inválidos. | | [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/) | `400` | Parâmetros inválidos. | | [Atualizar agente de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/atualizar-agente-de-ia/) | `400` | O contrato cita o código sem descrever. | | [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios/) | `400` | Parâmetros inválidos. | | [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/) | `400` | Parâmetros inválidos. | | [Consultar disparo](https://docs.nextags.com.br/referencia/disparos/consultar-disparo/) | `404` | O disparo não existe. | | [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/) | `400` | O `status` não é 6, 7, 10 nem 13. | | [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/) | `402` | O `status` é o mesmo que o pedido já tem. | | [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/) | `404` | O pedido não existe. | | [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/) | `400` | O `amount_received` é menor que o total do pedido. | | [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/) | `402` | O pagamento não foi concluído. O contrato diz que o contato recebe uma mensagem no Messenger com o motivo. | | [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/) | `404` | O pedido não existe. | ## O formato do erro O erro de chave foi conferido na produção. A resposta é `401`, em qualquer endereço, com este corpo: ```json {"error": {"code": 401, "message": "No valid API key provided."}} ``` - `error.code` repete o código HTTP, e `error.message` explica em inglês. - O cabeçalho `Content-Type` dessa resposta vem `text/html; charset=UTF-8`, mas o corpo é JSON. Leia o corpo como JSON sem depender do cabeçalho. - O corpo dos outros erros (`400`, `402`, `404`) não foi conferido. Decida pelo código HTTP e guarde o corpo inteiro no seu registro para entender o caso. ## Limite de uso Planeje até 100 requisições por minuto por conta. A conta tem uma chave só, então esse total vale para todas as integrações juntas: o seu sistema, o Zapier, o Make, o n8n e o Pabbly. - Distribua os lotes no tempo. Uma fila com uma chamada por segundo fica em 60 por minuto e deixa folga. - O código que a API devolve quando o limite passa não foi conferido. Se vier um erro fora da tabela acima (como `429` ou um `5xx`), espere e tente de novo, com espera crescente: 1 segundo, depois 2, 4, 8, até umas cinco tentativas. - Nunca repita na hora, em laço: isso só gasta mais chamadas do limite. Uma nova tentativa com espera crescente: ```javascript async function chamarComNovasTentativas(fazerChamada, tentativas = 5) { for (let i = 0; i < tentativas; i++) { const resposta = await fazerChamada(); // 2xx, 4xx e o 401: a resposta é final, não adianta repetir if (resposta.status < 500 && resposta.status !== 429) return resposta; await new Promise((r) => setTimeout(r, 1000 * 2 ** i)); // 1 s, 2 s, 4 s, 8 s, 16 s } throw new Error('A API não respondeu depois de várias tentativas'); } ``` Use a nova tentativa automática só em consultas (`GET`) e em chamadas que você conferiu que não duplicam nada (veja abaixo). ## Paginação Três listas têm paginação, com `offset` (de onde começar) e `limit` (quantos trazer): | Endpoint | Parâmetros | Padrão | |---|---|---| | [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/) | `offset`, `limit` | `0` e `100` | | [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/) | `offset`, `limit` e `contact_id` (filtro) | `0` e `100` | | [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/) | `offset`, `limit` | `0` e `100` | Para ler tudo, peça páginas até vir uma com menos itens que o `limit`: ```javascript const base = 'https://app.nextagsai.com.br/api/pipelines/4001/opportunities'; const itens = []; for (let offset = 0; ; offset += 100) { const resposta = await fetch(`${base}?offset=${offset}&limit=100`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY }, }); const { data } = await resposta.json(); itens.push(...data); if (data.length < 100) break; // a última página veio incompleta } console.log(itens.length); ``` Estas listas não têm paginação e trazem no máximo 100 itens: | Endpoint | O que vem | |---|---| | [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/) | Até 100 contatos, os de mudança mais recente no campo primeiro. | | [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/) | Até 100 agentes. | | [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios/) | Até 100 calendários. | | [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/) | Até 100 disparos. | ## Tempo limite - Ponha um tempo limite em toda chamada no seu cliente HTTP. Os exemplos em Python usam `timeout=30` (30 segundos). - Se uma chamada que cria ou envia algo estourar o tempo, não repita direto: a NexTags pode ter recebido e feito a operação. Confira antes, como na tabela abaixo. ## Repetir sem duplicar | Tipo de chamada | Pode repetir? | Antes de repetir | |---|---|---| | Consultas (`GET`) | Sim. | Nada. | | Criar contato, etiqueta, campo, oportunidade ou comentário | Só depois de conferir. | Procure o item: [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/), [Buscar etiqueta pelo nome](https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome/), [Buscar campo pelo nome](https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/), [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/) com `contact_id`, [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/). | | Enviar fluxo, texto, arquivo, conteúdo ou produtos | Não: o contato recebe de novo. | Registre no seu sistema o que já foi enviado e confira na conversa da **Caixa de Entrada**. | | Reenviar disparo | Não: o Broadcast sai de novo. | [Consultar disparo](https://docs.nextags.com.br/referencia/disparos/consultar-disparo/). | | Pôr ou tirar etiqueta, preencher ou limpar campo, mudar a etapa ou o status | Só depois de conferir. | Consulte o contato, o campo, a oportunidade ou o pedido. No pedido, repetir o mesmo `status` dá `402`. | | Adicionar produto ao carrinho, marcar pedido como pago | Só depois de conferir. | [Consultar carrinho](https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/) ou [Consultar pedido](https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/). | A regra geral: procure antes de criar. O contrato não diz se a API recusa um contato, uma etiqueta ou uma oportunidade repetidos, então quem evita a duplicata é a sua integração. Veja o caminho completo em [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/). --- # Campos personalizados, campos do bot e variáveis > Campo personalizado (um valor por contato), campo do bot (um valor da conta) e campos do sistema: o formato de cada valor e como ler e gravar cada um pela API. Endereço: https://docs.nextags.com.br/comecar/campos-e-variaveis/ Tipo: Conceito Atualizado em: 26/10/2026 A NexTags guarda dados em três tipos de campo. O campo personalizado guarda um valor por contato, como a cidade ou o CPF. O campo do bot guarda um valor só para a conta toda, como o horário de atendimento. E os campos do sistema são os dados que a plataforma já tem de cada contato, como o nome e o telefone. Os três entram nas mensagens dos fluxos como variáveis entre chaves duplas, e a API lê e grava cada um de um jeito. ## Como funciona ### Os três tipos | | Campo personalizado | Campo do bot | Campo do sistema | |---|---|---|---| | Guarda | Um valor por contato | Um valor para a conta toda | Os dados prontos do contato e da conta | | Exemplo | `cidade` = São Paulo | `link_da_promocao` = um link | `first_name` = Ana | | Quem cria | Você, na tela ou pela API | Você, na tela ou pela API | A plataforma | | Na mensagem do fluxo | `{{cidade}}` | `{{link_da_promocao}}` | `{{first_name}}`, `{{phone}}`, `{{email}}` | | Na tela | **Fluxos** › aba **Campo Personalizados** | A mesma aba, seção **Campo Personalizados do Bot** | Na lista de variáveis do editor de fluxo, aberta com `{` | O passo a passo de tela está em [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/), [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/) e [Campos do sistema](https://help.nextags.com.br/tutoriais/fluxos/campos-do-sistema/), que tem a lista completa das variáveis do sistema. ### O formato do valor de cada tipo Cada campo personalizado tem um tipo (`type`). O valor vai num formato diferente em cada um: | `type` | Na tela | Como vai o valor | Exemplo | |---|---|---|---| | `0` | Texto | Texto | `São Paulo` | | `1` | Número | Número | `42` | | `2` | Data | Unix timestamp em segundos | `1794279600` (10/11/2026) | | `3` | Data e hora | Unix timestamp em segundos | `1794331800` (10/11/2026, 14h30 em Brasília) | | `4` | Verdadeiro/Falso | `1` para sim e `0` para não | `1` | | `5` | Texto longo | Texto | Um parágrafo | | `6` | Seleção única | Uma das opções do campo (o app guarda como texto) | Confira o formato no seu teste. | | `7` | Seleção múltipla | Várias opções do campo | Confira o formato no seu teste. | - Pela API, [Criar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/) aceita só os tipos `0` a `4`. Os tipos `5`, `6` e `7` são criados na tela. - O painel da NexTags mostra datas no fuso de quem está vendo. Para um campo de Data, mande a meia-noite no horário de Brasília, como `1794279600` para 10/11/2026: a meia-noite em UTC apareceria como o dia anterior para quem está no Brasil. - Um valor de Data ou Data e hora em milissegundos vira uma data errada. Divida por 1000 antes de mandar. ### Ler e gravar pela API | O que fazer | Campo personalizado | Campo do bot | Campo do sistema | |---|---|---|---| | Criar | [Criar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/), com `name`, `type` e `description` | A mesma chamada, com `"isBotField": true` e o `value` | Não se cria | | Achar o ID | [Listar campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-personalizados/) ou [Buscar campo pelo nome](https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/) | **Obter ID** na tela ([Identificadores](https://docs.nextags.com.br/comecar/identificadores/)) | Não tem ID: usa o nome | | Ler | [Listar campos do contato](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-do-contato/) ou [Consultar campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/consultar-campo-do-contato/) | [Consultar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/consultar-campo-do-bot/) | [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/), como `first_name` e `last_name` | | Gravar pelo ID | [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/), formulário com `value` | [Preencher campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot/), formulário com `value` | Não se aplica | | Gravar pelo nome | Ação `set_field_value` com o `field_name` | Não documentado | Ação `set_field_value` com `first_name`, `last_name`, `full_name`, `phone` ou `email` | | Limpar | [Limpar campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/limpar-campo-do-contato/) ou a ação `unset_field_value` | [Limpar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/limpar-campo-do-bot/) | Não se aplica | As ações `set_field_value` e `unset_field_value` vão em [Criar contato](https://docs.nextags.com.br/referencia/contatos/criar-contato/) e em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). O formato está em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). Criar um campo personalizado: ```json {"name": "cidade", "type": 0, "description": "Cidade do contato"} ``` A resposta traz o ID: ```json {"id": 3001, "name": "cidade"} ``` Criar um campo do bot, já com o valor: ```json { "name": "link_da_promocao", "type": 0, "isBotField": true, "value": "https://seusistema.exemplo.com.br/promocao" } ``` Gravar um campo pelo nome, numa ação: ```json {"action": "set_field_value", "field_name": "cidade", "value": "São Paulo"} ``` ### E os campos do pipeline As oportunidades têm campos próprios, criados nas **Definições** de cada pipeline. Eles não são campos personalizados do contato: liste com [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/) e preencha em `custom_fields` ao criar ou atualizar a oportunidade, com `{"id": …, "value": …}` ou `{"name": …, "value": …}`. Veja [Criar e mover oportunidades no pipeline](https://docs.nextags.com.br/guias/oportunidades-no-pipeline/). ## Quando usar - **Campo personalizado**: um dado que muda de contato para contato, como cidade, CPF, plano de interesse ou o código do cliente no seu sistema. - **Campo do bot**: um valor que vale para todos e muda de vez em quando, como um link de promoção, um horário ou um preço. Troque num lugar só, e todos os fluxos passam a usar o valor novo. - **Campo do sistema**: nome, telefone e e-mail do contato. Use direto nas mensagens. - **Etiqueta**: uma marca de sim ou não para segmentar, como "cliente-vip". Veja [Etiqueta ou campo: quando usar cada um](https://help.nextags.com.br/tutoriais/fluxos/etiqueta-ou-campo/). ## Boas práticas > **Nomes simples e fixos:** > A ação `set_field_value` acha o campo pelo nome exato. Use nomes curtos, sem acento, como `cidade` e `codigo_cliente`, e não renomeie um campo que uma integração usa. > **Datas em segundos, no fuso certo:** > Campo de Data ou Data e hora recebe Unix timestamp em segundos. Para Data, mande a meia-noite no horário de Brasília. Confira o valor no painel do contato, na **Caixa de Entrada**, depois do primeiro teste. > **Sim e não como 1 e 0:** > Campo Verdadeiro/Falso recebe `1` ou `0`. Textos como `sim`, `true` ou `yes` podem não virar o valor esperado. --- # Mensagens e ações em JSON > O formato JSON de mensagens e ações da NexTags (texto, botões, respostas rápidas, mídia, cartões, galeria e as 8 ações), com os limites e onde ele vale. Endereço: https://docs.nextags.com.br/comecar/mensagens-e-acoes/ Tipo: Referência Atualizado em: 26/10/2026 A NexTags usa um formato só para mensagens e ações em JSON. Você escreve a mensagem uma vez, no formato de mensagens do Messenger, e a NexTags converte para o canal do contato. Para o WhatsApp, dá também para mandar mensagens no formato da API do WhatsApp. As ações rodam no contato: põem etiquetas, preenchem campos, enviam fluxos e passam a conversa para a equipe. ## Onde o formato vale | Onde | O que vai | |---|---| | [Criar contato](https://docs.nextags.com.br/referencia/contatos/criar-contato/), `POST /contacts` | `actions` | | [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/), `POST /contacts/{contact_id}/send_content` | `messages` e `actions` | | A resposta do seu sistema a uma [requisição externa no fluxo](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/) | `messages` e `actions` | | A resposta de um [agente de IA em JSON](https://docs.nextags.com.br/ia/respostas-do-agente-em-json/) | `messages` e `actions` | O corpo tem duas listas, e as duas podem ir vazias: ```json { "messages": [], "actions": [] } ``` ## Mensagens Cada mensagem da lista `messages` é um objeto com `message` dentro, e elas saem na ordem da lista. As exceções são a pausa de "digitando" e a mensagem só do WhatsApp, mais abaixo. ### Texto ```json { "messages": [ {"message": {"text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega."}}, {"message": {"text": "Qualquer dúvida, é só responder aqui."}} ] } ``` ### Pausa de "digitando" Um número solto entre duas mensagens mostra o "digitando" por esse tanto de segundos. Este formato aparece nas respostas do agente de IA; nos outros lugares, confira no seu teste. ```json { "messages": [ {"message": {"text": "Oi, Ana!"}}, 3, {"message": {"text": "Seu pedido PED-1001 saiu para entrega."}} ] } ``` ### Texto com botões Até 3 botões, com título de até 20 caracteres. Cada botão tem um tipo: | `type` | O que faz | Campo | |---|---|---| | `web_url` | Abre um site | `url` | | `postback` | Envia um fluxo ou uma etapa | `payload` com o ID do fluxo ou da etapa, ou ações (abaixo) | | `phone_number` | Liga para um número | `payload` com o telefone e o código do país | ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "button", "text": "Seu boleto está pronto. Como prefere seguir?", "buttons": [ { "type": "web_url", "title": "Abrir o boleto", "url": "https://seusistema.exemplo.com.br/boleto/PED-1001" }, {"type": "postback", "title": "Falar com a equipe", "payload": "1000001"}, {"type": "phone_number", "title": "Ligar para a loja", "payload": "+551133445566"} ] } } } } ] } ``` ### Respostas rápidas Até 11 respostas rápidas, em qualquer tipo de mensagem. O `payload` funciona como o do botão. ```json { "messages": [ { "message": { "text": "Qual sabor você prefere?", "quick_replies": [ {"content_type": "text", "title": "Chocolate", "payload": "1000001"}, {"content_type": "text", "title": "Morango", "payload": "1000002"} ] } } ] } ``` ### Imagem, vídeo, áudio e arquivo O `type` é `image`, `video`, `audio` ou `file`, e o `url` aponta para o arquivo, num endereço público (sem login). Os tamanhos que cada canal aceita estão em [Tipos de arquivo e limites por canal](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/). ```json { "messages": [ { "message": { "attachment": { "type": "image", "payload": {"url": "https://seusistema.exemplo.com.br/img/bolo-de-chocolate.jpg"} } } } ] } ``` ### Cartão Título e subtítulo com até 80 caracteres cada, imagem e até 3 botões. O `image_aspect_ratio` é `horizontal` ou `square`. ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "generic", "image_aspect_ratio": "horizontal", "elements": [ { "title": "Bolo de chocolate", "subtitle": "R$ 89,90 · serve 12 pessoas", "image_url": "https://seusistema.exemplo.com.br/img/bolo-de-chocolate.jpg", "buttons": [ {"type": "postback", "title": "Quero este", "payload": "1000001"} ] } ] } } } } ] } ``` ### Galeria A galeria é um cartão com vários `elements`, até 10. ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "generic", "image_aspect_ratio": "square", "elements": [ { "title": "Bolo de chocolate", "subtitle": "R$ 89,90", "image_url": "https://seusistema.exemplo.com.br/img/chocolate.jpg", "buttons": [] }, { "title": "Bolo de morango", "subtitle": "R$ 94,90", "image_url": "https://seusistema.exemplo.com.br/img/morango.jpg", "buttons": [] } ] } } } } ] } ``` ### Mensagem só do WhatsApp Para o que só o WhatsApp tem, como lista de opções, contatos, localização e catálogo, mande o objeto no formato da API do WhatsApp (Cloud API), com `"to": null`: a NexTags preenche o destinatário. No `id` de cada botão vai o ID do fluxo ou da etapa. Os formatos de cada tipo estão na documentação da Meta, como a de [botões de resposta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-reply-buttons-messages) e a de [listas](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-list-messages). ```json { "messages": [ { "messaging_product": "whatsapp", "recipient_type": "individual", "to": null, "type": "interactive", "interactive": { "type": "button", "body": {"text": "Confirma a entrega para amanhã?"}, "action": { "buttons": [ {"type": "reply", "reply": {"id": "1000001", "title": "Confirmo"}}, {"type": "reply", "reply": {"id": "1000002", "title": "Outro dia"}} ] } } } ] } ``` ## Limites | Item | Limite | |---|---| | Botões num texto | 3 | | Título do botão | 20 caracteres | | Respostas rápidas numa mensagem | 11 | | Título e subtítulo do cartão | 80 caracteres cada | | Botões num cartão | 3 | | Cartões numa galeria | 10 | ## Botões e cartões em cada canal No editor de fluxo, numa mensagem para todos os canais, a NexTags tira da lista de quem recebe os canais que não aceitam o conteúdo: | Conteúdo | Não vai para | |---|---| | Cartão ou galeria | Telegram e TikTok | | Galeria com mais de um cartão | WhatsApp | | Botão que liga (`phone_number`) | WhatsApp | | Mais de um botão, quando um deles abre site (`web_url`) | WhatsApp | | Arquivo ou áudio | TikTok | No JSON, a conversão acontece na hora do envio, e o resultado de cada caso não foi conferido. Teste no canal de verdade antes de usar com clientes. As regras de cada conteúdo nos fluxos estão em [Texto, botões e respostas rápidas](https://help.nextags.com.br/tutoriais/fluxos/texto-e-botoes/) e [Cartão e carrossel](https://help.nextags.com.br/tutoriais/fluxos/cartoes-e-galeria/). ## Ações | Ação | O que faz | JSON | |---|---|---| | `add_tag` | Põe uma etiqueta, pelo nome | `{"action": "add_tag", "tag_name": "cliente-vip"}` | | `remove_tag` | Tira uma etiqueta, pelo nome | `{"action": "remove_tag", "tag_name": "cliente-vip"}` | | `set_field_value` | Preenche um campo, pelo nome. Vale também para `phone`, `email`, `full_name`, `first_name` e `last_name` | `{"action": "set_field_value", "field_name": "cidade", "value": "São Paulo"}` | | `unset_field_value` | Limpa um campo, pelo nome | `{"action": "unset_field_value", "field_name": "cidade"}` | | `send_flow` | Envia um fluxo | `{"action": "send_flow", "flow_id": 1000001}` | | `transfer_conversation_to` | Passa a conversa para a equipe (`human`) ou de volta para o robô (`bot`) | `{"action": "transfer_conversation_to", "value": "human"}` | | `assign_conversation` | Atribui a conversa a um administrador | `{"action": "assign_conversation", "admin_id": 10001}` | | `unassign_conversation` | Tira a atribuição da conversa | `{"action": "unassign_conversation"}` | Várias ações vão juntas na mesma lista. Ponha na ordem em que fazem sentido, como preencher o campo antes de enviar o fluxo que usa o campo, e confira o resultado no primeiro teste: ```json { "messages": [{"message": {"text": "Recebemos o seu pagamento. Obrigado, Ana!"}}], "actions": [ {"action": "add_tag", "tag_name": "cliente-vip"}, {"action": "set_field_value", "field_name": "cidade", "value": "São Paulo"}, {"action": "send_flow", "flow_id": 1000001} ] } ``` O ID do fluxo e do administrador: [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). Os campos e o formato de cada valor: [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/). ### Ações num botão O `payload` de um botão ou de uma resposta rápida pode levar ações no lugar do ID do fluxo. Como o `payload` é texto, as ações vão como JSON dentro do texto, com as aspas escapadas: ```json { "type": "postback", "title": "Quero o desconto", "payload": "{\"actions\":[{\"action\":\"add_tag\",\"tag_name\":\"cliente-vip\"},{\"action\":\"send_flow\",\"flow_id\":1000001}]}" } ``` Monte esse texto com a função de JSON da sua linguagem, em vez de escapar à mão: **Montar o payload com ações** ```javascript const payload = JSON.stringify({ actions: [ { action: 'add_tag', tag_name: 'cliente-vip' }, { action: 'send_flow', flow_id: 1000001 }, ], }); const botao = { type: 'postback', title: 'Quero o desconto', payload }; ``` ```python import json payload = json.dumps({ "actions": [ {"action": "add_tag", "tag_name": "cliente-vip"}, {"action": "send_flow", "flow_id": 1000001}, ], }) botao = {"type": "postback", "title": "Quero o desconto", "payload": payload} ``` ```php [ ['action' => 'add_tag', 'tag_name' => 'cliente-vip'], ['action' => 'send_flow', 'flow_id' => 1000001], ], ]); $botao = ['type' => 'postback', 'title' => 'Quero o desconto', 'payload' => $payload]; ``` ## A janela de 24 horas No WhatsApp, mensagem livre (texto, mídia, botões, cartões e as mensagens só do WhatsApp) só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, só sai um Modelo de Mensagem aprovado pela Meta, e pela API isso se faz por um fluxo que comece com o modelo, enviado com [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/). - A regra vale para tudo o que sai do número: a API, os fluxos, a **Caixa de Entrada** e os Broadcasts. - No Instagram e no Messenger, a Meta dá 24 horas para mensagens automáticas; os 7 dias valem só para a resposta da equipe pela **Caixa de Entrada**. Veja [Mensagens fora da janela no Instagram e no Messenger](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). - A ação `send_flow` envia mensagens e segue a mesma regra: fora da janela, o fluxo precisa começar com o modelo. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/), [Criar um modelo e enviar para aprovação](https://help.nextags.com.br/tutoriais/disparos/criar-modelo/) e [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/). --- # Guias > Receitas de ponta a ponta para os casos de uso mais comuns da API. Endereço: https://docs.nextags.com.br/guias/ Tipo: Seção ## Páginas - [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato.md): Procure o contato pelo telefone, crie se não existir (com etiqueta, campo e fluxo) e, se existir, atualize as etiquetas e os campos. Sem criar duplicados. - [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo.md): Envie um fluxo pronto a um contato a partir do seu sistema, com o ID do contato e o do fluxo, e respeite a janela de 24 horas do WhatsApp. - [Enviar texto, imagem e arquivo](https://docs.nextags.com.br/guias/enviar-texto-e-arquivos.md): Envie um texto, uma imagem, um vídeo, um áudio ou um arquivo a um contato pela API, escolha o canal e respeite a janela de 24 horas e os limites. - [Etiquetar contatos e preencher campos](https://docs.nextags.com.br/guias/etiquetas-e-campos.md): Ache ou crie a etiqueta, ponha e tire do contato, preencha e limpe campos personalizados e mude o valor de um campo do bot, tudo pela API. - [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo.md): Ache o contato pelo telefone, pelo e-mail ou pelo valor de um campo personalizado, e saiba o que fazer quando a busca traz mais de um resultado. - [Criar e mover oportunidades no pipeline](https://docs.nextags.com.br/guias/oportunidades-no-pipeline.md): Liste pipelines e etapas, crie a oportunidade do contato, mova de etapa, marque como ganha ou perdida, transfira para outro pipeline e comente, pela API. - [Carrinho, pedidos e produtos](https://docs.nextags.com.br/guias/carrinho-e-pedidos.md): Consulte e atualize produtos, envie produtos, mexa no carrinho e mude o status, a entrega e o pagamento dos pedidos pela API, com valores em centavos. - [Acompanhar, reenviar e cancelar disparos](https://docs.nextags.com.br/guias/disparos-pela-api.md): Liste e consulte os Broadcasts da conta, acompanhe o status, reenvie e cancele pela API. Criar o Broadcast continua na tela da NexTags. - [Agentes de IA pela API](https://docs.nextags.com.br/guias/agentes-de-ia-pela-api.md): Liste os agentes do AI Hub, atualize o prompt, o modelo e o limite de tokens, veja funções, MCP e arquivos e salve mensagens no histórico da IA. - [Usar a API no Make, n8n e Zapier](https://docs.nextags.com.br/guias/make-n8n-zapier.md): Chame a API da NexTags pelo módulo HTTP do Make, pelo HTTP Request do n8n e pelo Webhooks by Zapier, e faça o caminho contrário com webhooks. _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._ --- # Criar ou atualizar um contato > Procure o contato pelo telefone, crie se não existir (com etiqueta, campo e fluxo) e, se existir, atualize as etiquetas e os campos. Sem criar duplicados. Endereço: https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/ Tipo: Guia Atualizado em: 26/10/2026 Quando o seu sistema recebe um cadastro, uma venda ou um formulário, ele precisa deixar o contato pronto na NexTags. O caminho seguro tem três partes: procurar o contato pelo telefone, criar só se ele não existir e, se existir, atualizar as etiquetas e os campos. Procurar antes evita contatos repetidos, porque o contrato da API não diz o que acontece quando você cria um telefone que já existe. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - O telefone completo, só com números: código do país, DDD e número, como `5511988776655`. Veja [O formato certo do telefone](https://help.nextags.com.br/tutoriais/contatos/formato-do-telefone/). - A etiqueta e o campo que você vai usar, já criados na conta, com os IDs anotados (neste guia, a etiqueta `cliente-vip`, ID `2001`, e o campo `cidade`, ID `3001`). Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). - Se for enviar um fluxo ao contato novo: o ID do fluxo. No WhatsApp, o fluxo precisa começar com um Modelo de Mensagem aprovado, porque o contato novo ainda não falou com você. Veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/). ## Passo a passo ### Passo 1: Procure o contato pelo telefone Use [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/) com `field_id=phone` e o telefone em `value`. Para procurar pelo e-mail, use `field_id=email`. **Procurar pelo telefone** ```bash curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({ field_id: 'phone', value: '5511988776655', })}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/find_by_custom_field", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={ "field_id": "phone", "value": "5511988776655", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php 'phone', 'value' => '5511988776655', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Se o contato existe, ele vem na lista `data` (aqui, resumido; os campos estão em [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/)): ```json { "data": [ { "id": 123456789, "first_name": "Ana", "last_name": "Souza", "channel": 5, "tags": [{"id": 2001, "name": "cliente-vip"}], "custom_fields": [ {"id": 3001, "name": "cidade", "type": 0, "value": "São Paulo"} ] } ] } ``` Se `data` vier vazia ou não vier, o contato não existe: siga para o passo 2. Se vier, guarde o `id` e pule para o passo 3. Com mais de um resultado, veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/). ### Passo 2: Se não achou, crie o contato Use [Criar contato](https://docs.nextags.com.br/referencia/contatos/criar-contato/). O `phone` é obrigatório; `email`, `first_name`, `last_name` e `gender` (`male`, `female` ou `unknown`) são opcionais. Em `actions`, a mesma chamada já põe a etiqueta, preenche o campo e envia um fluxo, pelo nome da etiqueta e do campo. **Criar contato** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "gender": "female", "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" }, { "action": "send_flow", "flow_id": 1000001 } ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ phone: '5511988776655', email: 'ana@exemplo.com.br', first_name: 'Ana', last_name: 'Souza', gender: 'female', actions: [ { action: 'add_tag', tag_name: 'cliente-vip', }, { action: 'set_field_value', field_name: 'cidade', value: 'São Paulo', }, { action: 'send_flow', flow_id: 1000001, }, ], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "gender": "female", "actions": [ { "action": "add_tag", "tag_name": "cliente-vip", }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo", }, { "action": "send_flow", "flow_id": 1000001, }, ], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'phone' => '5511988776655', 'email' => 'ana@exemplo.com.br', 'first_name' => 'Ana', 'last_name' => 'Souza', 'gender' => 'female', 'actions' => [ [ 'action' => 'add_tag', 'tag_name' => 'cliente-vip', ], [ 'action' => 'set_field_value', 'field_name' => 'cidade', 'value' => 'São Paulo', ], [ 'action' => 'send_flow', 'flow_id' => 1000001, ], ], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` O contrato não descreve o que a criação responde. Para ter o ID do contato novo, procure de novo pelo telefone, como no passo 1. As ações e o formato de cada uma estão em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). ### Passo 3: Se achou, ponha a etiqueta Use [Adicionar etiqueta ao contato](https://docs.nextags.com.br/referencia/etiquetas/adicionar-etiqueta-ao-contato/), com o ID do contato e o da etiqueta no caminho. Não tem corpo. **Adicionar etiqueta ao contato** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. Para tirar uma etiqueta, use `DELETE` no mesmo endereço ([Remover etiqueta do contato](https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato/)). ### Passo 4: Preencha os campos Use [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/). Esta chamada recebe formulário, não JSON: o valor vai no campo `value`. **Preencher campo do contato** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'value=São Paulo' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, body: new URLSearchParams({ value: 'São Paulo', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, data={ "value": "São Paulo", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], CURLOPT_POSTFIELDS => http_build_query([ 'value' => 'São Paulo', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. Data vai em Unix timestamp em segundos e sim/não em `1` ou `0`. Veja [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/). ### Passo 5: Atualize o nome ou o e-mail, se mudaram A API não tem uma chamada de atualizar contato. Para trocar o nome, o e-mail ou o telefone de quem já existe, mande só ações em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/), com `set_field_value` e os campos do sistema `first_name`, `last_name`, `full_name`, `email` ou `phone`. **Atualizar o e-mail e o sobrenome** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send_content" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "actions": [ { "action": "set_field_value", "field_name": "email", "value": "ana.souza@exemplo.com.br" }, { "action": "set_field_value", "field_name": "last_name", "value": "Souza Lima" } ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send_content', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ actions: [ { action: 'set_field_value', field_name: 'email', value: 'ana.souza@exemplo.com.br', }, { action: 'set_field_value', field_name: 'last_name', value: 'Souza Lima', }, ], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/send_content", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "actions": [ { "action": "set_field_value", "field_name": "email", "value": "ana.souza@exemplo.com.br", }, { "action": "set_field_value", "field_name": "last_name", "value": "Souza Lima", }, ], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'actions' => [ [ 'action' => 'set_field_value', 'field_name' => 'email', 'value' => 'ana.souza@exemplo.com.br', ], [ 'action' => 'set_field_value', 'field_name' => 'last_name', 'value' => 'Souza Lima', ], ], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Sem `messages`, nada é enviado ao contato. Confira o resultado no painel do contato depois do primeiro teste. ### Passo 6: Junte tudo numa função A função procura pelo telefone, cria se não achar e, se achar, põe a etiqueta e preenche o campo. Rode com a chave em `NEXTAGS_API_KEY`. **Criar ou atualizar** ```javascript const BASE = 'https://app.nextagsai.com.br/api'; async function api(metodo, caminho, { json, form } = {}) { const headers = { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY }; let body; if (json) { headers['Content-Type'] = 'application/json'; body = JSON.stringify(json); } if (form) body = new URLSearchParams(form); const resposta = await fetch(BASE + caminho, { method: metodo, headers, body }); const texto = await resposta.text(); if (!resposta.ok) throw new Error(`${metodo} ${caminho}: ${resposta.status} ${texto}`); try { return JSON.parse(texto); } catch { return texto; } } async function acharPeloTelefone(telefone) { const consulta = new URLSearchParams({ field_id: 'phone', value: telefone }); const resposta = await api('GET', `/contacts/find_by_custom_field?${consulta}`); const lista = (resposta && resposta.data) || []; return lista[0] || null; // o de mudança mais recente vem primeiro } async function criarOuAtualizar({ telefone, email, nome, sobrenome, cidade }) { const contato = await acharPeloTelefone(telefone); if (!contato) { await api('POST', '/contacts', { json: { phone: telefone, email, first_name: nome, last_name: sobrenome, actions: [ { action: 'add_tag', tag_name: 'cliente-vip' }, { action: 'set_field_value', field_name: 'cidade', value: cidade }, ], }, }); return acharPeloTelefone(telefone); // para ter o ID do contato novo } await api('POST', `/contacts/${contato.id}/tags/2001`); await api('POST', `/contacts/${contato.id}/custom_fields/3001`, { form: { value: cidade } }); return contato; } const contato = await criarOuAtualizar({ telefone: '5511988776655', email: 'ana@exemplo.com.br', nome: 'Ana', sobrenome: 'Souza', cidade: 'São Paulo', }); console.log(contato && contato.id); ``` ```python import json import os import requests BASE = "https://app.nextagsai.com.br/api" def api(metodo, caminho, json_corpo=None, form=None, params=None): resposta = requests.request( metodo, BASE + caminho, headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json=json_corpo, data=form, params=params, timeout=30, ) if not resposta.ok: raise RuntimeError(f"{metodo} {caminho}: {resposta.status_code} {resposta.text}") try: return resposta.json() except json.JSONDecodeError: return resposta.text def achar_pelo_telefone(telefone): resposta = api("GET", "/contacts/find_by_custom_field", params={"field_id": "phone", "value": telefone}) lista = resposta.get("data") if isinstance(resposta, dict) else None return lista[0] if lista else None # o de mudança mais recente vem primeiro def criar_ou_atualizar(telefone, email, nome, sobrenome, cidade): contato = achar_pelo_telefone(telefone) if contato is None: api("POST", "/contacts", json_corpo={ "phone": telefone, "email": email, "first_name": nome, "last_name": sobrenome, "actions": [ {"action": "add_tag", "tag_name": "cliente-vip"}, {"action": "set_field_value", "field_name": "cidade", "value": cidade}, ], }) return achar_pelo_telefone(telefone) # para ter o ID do contato novo api("POST", f"/contacts/{contato['id']}/tags/2001") api("POST", f"/contacts/{contato['id']}/custom_fields/3001", form={"value": cidade}) return contato contato = criar_ou_atualizar("5511988776655", "ana@exemplo.com.br", "Ana", "Souza", "São Paulo") print(contato and contato["id"]) ``` ```php true, CURLOPT_CUSTOMREQUEST => $metodo, CURLOPT_TIMEOUT => 30]; if ($json !== null) { $cabecalhos[] = 'Content-Type: application/json'; $opcoes[CURLOPT_POSTFIELDS] = json_encode($json); } if ($form !== null) { $opcoes[CURLOPT_POSTFIELDS] = http_build_query($form); } $opcoes[CURLOPT_HTTPHEADER] = $cabecalhos; $ch = curl_init(BASE . $caminho); curl_setopt_array($ch, $opcoes); $texto = curl_exec($ch); $codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($codigo < 200 || $codigo >= 300) { throw new RuntimeException("$metodo $caminho: $codigo $texto"); } $dados = json_decode($texto, true); return $dados ?? $texto; } function acharPeloTelefone(string $telefone): ?array { $resposta = api('GET', '/contacts/find_by_custom_field?' . http_build_query(['field_id' => 'phone', 'value' => $telefone])); $lista = is_array($resposta) ? ($resposta['data'] ?? []) : []; return $lista[0] ?? null; // o de mudança mais recente vem primeiro } function criarOuAtualizar(string $telefone, string $email, string $nome, string $sobrenome, string $cidade): ?array { $contato = acharPeloTelefone($telefone); if ($contato === null) { api('POST', '/contacts', [ 'phone' => $telefone, 'email' => $email, 'first_name' => $nome, 'last_name' => $sobrenome, 'actions' => [ ['action' => 'add_tag', 'tag_name' => 'cliente-vip'], ['action' => 'set_field_value', 'field_name' => 'cidade', 'value' => $cidade], ], ]); return acharPeloTelefone($telefone); // para ter o ID do contato novo } api('POST', "/contacts/{$contato['id']}/tags/2001"); api('POST', "/contacts/{$contato['id']}/custom_fields/3001", null, ['value' => $cidade]); return $contato; } $contato = criarOuAtualizar('5511988776655', 'ana@exemplo.com.br', 'Ana', 'Souza', 'São Paulo'); echo $contato['id'] ?? 'não encontrado', PHP_EOL; ``` Repetir a função com os mesmos dados não cria outro contato: na segunda vez, a busca acha o primeiro. ## Pronto: como conferir - Procure de novo pelo telefone: o contato vem com a etiqueta em `tags` e o valor em `custom_fields`. - Na NexTags, abra o contato na **Caixa de Entrada**: o painel mostra a etiqueta e o campo. Veja [O painel Mais informações](https://help.nextags.com.br/tutoriais/caixa-de-entrada/card-do-cliente/). - Para conferir só as etiquetas ou só os campos, use [Listar etiquetas do contato](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas-do-contato/) e [Listar campos do contato](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-do-contato/). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### A busca não acha um contato que existe O telefone pode estar salvo noutro formato (sem o `55`, com `+` ou sem o 9), e não foi conferido se a busca acha esses casos. Procure também pelo e-mail e padronize os telefones do seu sistema no formato completo, só com números. ### O mesmo contato apareceu duas vezes A criação rodou sem a busca antes, ou a busca usou um formato de telefone diferente do salvo. Procure sempre antes de criar, com o mesmo formato de telefone. Para limpar os repetidos, use a tela: veja [Ações em massa](https://help.nextags.com.br/tutoriais/contatos/acoes-em-massa/). ### O contato novo não recebeu o fluxo No WhatsApp, o contato novo está fora da janela de 24 horas: o fluxo precisa começar com um Modelo de Mensagem aprovado. Confira também se o fluxo está publicado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo/). ### A etiqueta ou o campo não foram preenchidos na criação As ações acham a etiqueta e o campo pelo nome exato, com maiúsculas, acentos e espaços. Confira o nome em **Fluxos** › **Etiquetas** e **Campo Personalizados**, ou use os passos 3 e 4, que usam o ID. ### 400 ou 404 ao pôr a etiqueta ou preencher o campo O ID do contato, da etiqueta ou do campo está errado ou é de outra conta. Confira os IDs em [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/criar-ou-atualizar-contato.md e https://docs.nextags.com.br/comecar/mensagens-e-acoes.md. Escreva, em [linguagem], uma função que recebe um cadastro do [seu sistema, por exemplo: checkout da loja] com nome, e-mail, telefone e [outros dados] e cria ou atualiza o contato na NexTags: procura pelo telefone, cria se não existir (com a etiqueta [nome] e o campo [nome]) e, se existir, atualiza a etiqueta e o campo pelos IDs [IDs]. A chave vem da variável de ambiente NEXTAGS_API_KEY. Trate o erro 401 e não crie contato sem procurar antes. ``` --- # Enviar um fluxo para um contato > Envie um fluxo pronto a um contato a partir do seu sistema, com o ID do contato e o do fluxo, e respeite a janela de 24 horas do WhatsApp. Endereço: https://docs.nextags.com.br/guias/enviar-fluxo/ Tipo: Guia Atualizado em: 26/10/2026 Enviar um fluxo é o jeito mais completo de falar com o contato pela API: o fluxo pode ter texto, botões, mídia, perguntas, ações e, no WhatsApp, um Modelo de Mensagem. O seu sistema manda só o ID do contato e o do fluxo, e a NexTags faz o resto. Use para confirmar pedidos, dar boas-vindas, lembrar de um horário ou retomar uma conversa. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - O fluxo pronto e publicado na NexTags: o contato recebe a versão publicada. Veja [Rascunho, publicação e versões do fluxo](https://help.nextags.com.br/tutoriais/fluxos/publicar-e-rascunho/). - Para o WhatsApp, fora da janela de 24 horas: um fluxo que comece com um Modelo de Mensagem aprovado. Veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/). ## Passo a passo ### Passo 1: Ache o ID do fluxo Use [Listar fluxos](https://docs.nextags.com.br/referencia/fluxos/listar-fluxos/). A resposta é uma lista com o `id` e o `name` de cada fluxo: **Listar fluxos** ```bash curl "https://app.nextagsai.com.br/api/accounts/flows" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/flows', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/accounts/flows", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json [ {"id": 1000001, "name": "Pedido confirmado"}, {"id": 1000002, "name": "Boas-vindas"} ] ``` O ID também aparece na tela: no endereço do editor do fluxo (`flow?id=1000001`) e no **Obter Link** do menu ⋮ do fluxo. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). Guarde o ID no seu sistema: ele não muda quando o nome do fluxo muda. ### Passo 2: Ache o ID do contato Procure o contato pelo telefone (ou pelo e-mail, com `field_id=email`) e pegue o `id` em `data`: **Procurar pelo telefone** ```bash curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({ field_id: 'phone', value: '5511988776655', })}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/find_by_custom_field", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={ "field_id": "phone", "value": "5511988776655", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php 'phone', 'value' => '5511988776655', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Se o contato não existe, crie antes. Veja [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/). ### Passo 3: Envie o fluxo Use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/), com o ID do contato e o do fluxo no caminho. A chamada não tem corpo. **Enviar fluxo** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/1000001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/1000001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/send/1000001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` O contrato não descreve a resposta. Confira o código HTTP e, no primeiro teste, a conversa do contato na **Caixa de Entrada**. > **Um fluxo só, dentro e fora da janela:** > Comece o fluxo com uma etapa **Condição** que use **Interagiu nas últimas 24h**: quem interagiu recebe a mensagem livre; quem não interagiu recebe o Modelo de Mensagem. Assim o seu sistema envia sempre o mesmo fluxo. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e [Etapa Condição](https://help.nextags.com.br/tutoriais/fluxos/condicoes/). ### Passo 4: Envie o fluxo junto com outras ações Para pôr uma etiqueta ou preencher um campo e enviar o fluxo na mesma chamada, use [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/) com a ação `send_flow`. Ponha antes do `send_flow` as ações de que o fluxo precisa, como o campo que aparece na mensagem, e confira o resultado no primeiro teste. **Etiqueta e fluxo numa chamada** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send_content" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "actions": [ { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" }, { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "send_flow", "flow_id": 1000001 } ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send_content', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ actions: [ { action: 'set_field_value', field_name: 'cidade', value: 'São Paulo', }, { action: 'add_tag', tag_name: 'cliente-vip', }, { action: 'send_flow', flow_id: 1000001, }, ], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/send_content", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "actions": [ { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo", }, { "action": "add_tag", "tag_name": "cliente-vip", }, { "action": "send_flow", "flow_id": 1000001, }, ], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'actions' => [ [ 'action' => 'set_field_value', 'field_name' => 'cidade', 'value' => 'São Paulo', ], [ 'action' => 'add_tag', 'tag_name' => 'cliente-vip', ], [ 'action' => 'send_flow', 'flow_id' => 1000001, ], ], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` As oito ações estão em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). ## Pronto: como conferir - Na **Caixa de Entrada**, a conversa do contato mostra as mensagens do fluxo. - No painel do contato, o histórico mostra o fluxo executado. Veja [Ver os fluxos e ações executados](https://help.nextags.com.br/tutoriais/caixa-de-entrada/acoes-executadas/). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### O contato não recebeu nada no WhatsApp O contato pode estar fora da janela de 24 horas, com um fluxo que começa por uma mensagem livre. Comece o fluxo com um Modelo de Mensagem aprovado ou com a condição **Interagiu nas últimas 24h**, e confira o que falhou no **Registro de Erros**. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e [Registro de Erros: ler e resolver](https://help.nextags.com.br/tutoriais/fluxos/registro-de-erros/). No Instagram e no Messenger, a Meta dá 24 horas para mensagens automáticas; os 7 dias valem só para a resposta da equipe pela **Caixa de Entrada**. Veja [Mensagens fora da janela no Instagram e no Messenger](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). ### O contato recebeu uma versão antiga do fluxo O fluxo tem mudanças em rascunho. Clique em **Publicar** no editor e envie de novo. Veja [Rascunho, publicação e versões do fluxo](https://help.nextags.com.br/tutoriais/fluxos/publicar-e-rascunho/). ### O fluxo não chega a contatos de um canal Confira o canal das etapas do fluxo. Na **Caixa de Entrada**, o **Enviar Fluxo** só oferece fluxos do canal do contato ou para todos os canais: use etapas **Todos os canais** quando o mesmo fluxo vai para canais diferentes. Veja [Etapa Enviar Mensagem e o canal da mensagem](https://help.nextags.com.br/tutoriais/fluxos/etapa-enviar-mensagem/). ### 400 ou 404 com o ID do contato ou do fluxo O ID está errado ou é de outra conta. Liste os fluxos de novo e procure o contato pelo telefone. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/enviar-fluxo.md. Quando [o evento no seu sistema, por exemplo: um pedido é pago], quero enviar o fluxo [nome do fluxo] da NexTags para o cliente. Escreva, em [linguagem], o código que procura o contato pelo telefone, envia o fluxo pelo ID e registra no meu sistema que o envio foi feito, para não enviar duas vezes. A chave vem da variável de ambiente NEXTAGS_API_KEY. ``` --- # Enviar texto, imagem e arquivo > Envie um texto, uma imagem, um vídeo, um áudio ou um arquivo a um contato pela API, escolha o canal e respeite a janela de 24 horas e os limites. Endereço: https://docs.nextags.com.br/guias/enviar-texto-e-arquivos/ Tipo: Guia Atualizado em: 26/10/2026 Para um aviso rápido, como "seu pedido saiu para entrega" ou a nota fiscal em PDF, não é preciso montar um fluxo: a API envia um texto ou um arquivo direto ao contato. Neste guia, você envia um texto, um arquivo e os dois juntos, e vê o que cada canal aceita. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - O ID do contato. Veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/). - Para arquivos: o arquivo num endereço público, que abra direto o arquivo, sem login e sem página no meio. - No WhatsApp: o contato dentro da janela de 24 horas. Fora dela, envie um fluxo que comece com um Modelo de Mensagem. Veja [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo/). ## Passo a passo ### Passo 1: Ache o contato Procure pelo telefone e pegue o `id` em `data`: **Procurar pelo telefone** ```bash curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({ field_id: 'phone', value: '5511988776655', })}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/find_by_custom_field", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={ "field_id": "phone", "value": "5511988776655", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php 'phone', 'value' => '5511988776655', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` O `channel` de cada contato diz o canal dele: `5` WhatsApp, `10` Instagram, `0` Messenger, `8` Telegram, `9` webchat e `17` TikTok. ### Passo 2: Envie um texto Use [Enviar texto](https://docs.nextags.com.br/referencia/mensagens/enviar-texto/), com o texto em `text` e, se quiser, o canal em `channel`: **Enviar texto** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/text" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega.", "channel": "whatsapp" }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/text', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ text: 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.', channel: 'whatsapp', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/send/text", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega.", "channel": "whatsapp", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'text' => 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.', 'channel' => 'whatsapp', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. Monte o texto completo no seu sistema, com o nome e os dados do pedido já preenchidos. O `channel` escolhe o canal do envio. O contrato lista estes valores: | `channel` | Texto (`send/text`) | Arquivo (`send/file`) | |---|---|---| | `whatsapp` | Sim | Sim | | `instagram` | Sim | Sim | | `messenger` | Sim | Sim | | `telegram` | Sim | Sim | | `webchat` | Sim | Não está na lista do contrato | O TikTok não aparece nessas listas. Sem `channel`, confira no primeiro teste por qual canal a mensagem saiu. > **A janela de 24 horas:** > No WhatsApp, texto e arquivo só saem até 24 horas depois da última mensagem do contato. Fora dessa janela, só sai um Modelo de Mensagem aprovado, e pela API isso se faz enviando um fluxo que comece com o modelo. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/). No Instagram e no Messenger, a Meta dá 24 horas para mensagens automáticas; os 7 dias valem só para a resposta da equipe pela **Caixa de Entrada**. Veja [Mensagens fora da janela no Instagram e no Messenger](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). ### Passo 3: Envie uma imagem ou um arquivo Use [Enviar arquivo](https://docs.nextags.com.br/referencia/mensagens/enviar-arquivo/), com o endereço do arquivo em `url` e o tipo em `type`: `image`, `video`, `audio` ou `file`. **Enviar arquivo** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/file" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://seusistema.exemplo.com.br/notas/PED-1001.pdf", "type": "file", "channel": "whatsapp" }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/file', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://seusistema.exemplo.com.br/notas/PED-1001.pdf', type: 'file', channel: 'whatsapp', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/send/file", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "url": "https://seusistema.exemplo.com.br/notas/PED-1001.pdf", "type": "file", "channel": "whatsapp", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'url' => 'https://seusistema.exemplo.com.br/notas/PED-1001.pdf', 'type' => 'file', 'channel' => 'whatsapp', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. O arquivo precisa estar no ar enquanto o envio acontece: não apague nem troque o endereço logo depois de chamar a API. Os tipos de arquivo e os tamanhos que cada canal aceita estão em [Tipos de arquivo e limites por canal](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/). No WhatsApp, por exemplo, uma imagem vai até 5 MB e um documento até 100 MB. ### Passo 4: Envie texto e arquivo juntos Para mandar várias mensagens na ordem certa numa chamada só, use [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/), com as mensagens em `messages`: **Texto e imagem numa chamada** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send_content" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "message": { "text": "Oi, Ana! Olha como ficou o seu bolo:" } }, { "message": { "attachment": { "type": "image", "payload": { "url": "https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg" } } } } ], "channel": "whatsapp" }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send_content', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ messages: [ { message: { text: 'Oi, Ana! Olha como ficou o seu bolo:', }, }, { message: { attachment: { type: 'image', payload: { url: 'https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg', }, }, }, }, ], channel: 'whatsapp', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/send_content", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "messages": [ { "message": { "text": "Oi, Ana! Olha como ficou o seu bolo:", }, }, { "message": { "attachment": { "type": "image", "payload": { "url": "https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg", }, }, }, }, ], "channel": "whatsapp", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'messages' => [ [ 'message' => [ 'text' => 'Oi, Ana! Olha como ficou o seu bolo:', ], ], [ 'message' => [ 'attachment' => [ 'type' => 'image', 'payload' => [ 'url' => 'https://seusistema.exemplo.com.br/img/bolo-PED-1001.jpg', ], ], ], ], ], 'channel' => 'whatsapp', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` O mesmo formato aceita botões, respostas rápidas, cartões e ações. Veja [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). ## Pronto: como conferir - A resposta é `{"success": true}`. - Na **Caixa de Entrada**, a conversa do contato mostra o texto e o arquivo. ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### O contato não recebeu a mensagem No WhatsApp, o contato pode estar fora da janela de 24 horas: envie um fluxo que comece com um Modelo de Mensagem. Confira também se o `channel` é o canal em que o contato fala com você e veja o que falhou no **Registro de Erros**. Veja [Registro de Erros: ler e resolver](https://help.nextags.com.br/tutoriais/fluxos/registro-de-erros/). ### O arquivo não chega ou chega quebrado O endereço não abre o arquivo direto (pede login, é uma página de visualização ou redireciona) ou o arquivo passa do limite do canal. Abra o `url` numa janela anônima do navegador: ele precisa baixar ou mostrar o arquivo na hora. Confira também se o `type` combina com o arquivo. Veja [Tipos de arquivo e limites por canal](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/). ### O texto chega com {{first_name}} escrito A troca de variáveis do texto enviado pela API não foi conferida. Monte o texto completo no seu sistema antes de enviar, ou use um fluxo, que troca as variáveis. Veja [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/enviar-texto-e-arquivos.md. Escreva, em [linguagem], uma função que envia ao contato da NexTags [o aviso, por exemplo: o código de rastreio e o PDF da nota fiscal] quando [o evento no seu sistema]. Ela procura o contato pelo telefone, envia o texto e o arquivo numa chamada só (Enviar conteúdo) e, se o contato estiver fora da janela de 24 horas do WhatsApp, envia o fluxo [ID do fluxo com o Modelo de Mensagem] no lugar. A chave vem da variável de ambiente NEXTAGS_API_KEY. ``` --- # Etiquetar contatos e preencher campos > Ache ou crie a etiqueta, ponha e tire do contato, preencha e limpe campos personalizados e mude o valor de um campo do bot, tudo pela API. Endereço: https://docs.nextags.com.br/guias/etiquetas-e-campos/ Tipo: Guia Atualizado em: 26/10/2026 Etiquetas e campos guardam o que o seu sistema sabe do contato: quem comprou, de que cidade é, qual plano escolheu. Neste guia, você acha (ou cria) a etiqueta, põe e tira do contato, preenche e limpa um campo personalizado e muda o valor de um campo do bot, que vale para a conta toda. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - O ID do contato. Veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/). - O campo personalizado criado na conta (neste guia, `cidade`, do tipo Texto). Veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/). - Para o último passo: um campo do bot e o ID dele (neste guia, `3101`). Veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/). ## Passo a passo ### Passo 1: Ache a etiqueta pelo nome Use [Buscar etiqueta pelo nome](https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome/), com o nome no caminho. Nome com espaço ou acento vai codificado para URL (`Cliente%20VIP`). **Buscar etiqueta pelo nome** ```bash curl "https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json {"id": 2001, "name": "cliente-vip"} ``` O contrato não diz o que volta quando o nome não existe. Se a resposta não trouxer um `id`, crie a etiqueta no passo 2. Para ver todas, use [Listar etiquetas](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas/). ### Passo 2: Crie a etiqueta, se ela não existir Use [Criar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/). Esta chamada recebe formulário, com o nome em `name`: **Criar etiqueta** ```bash curl -X POST "https://app.nextagsai.com.br/api/accounts/tags" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'name=cliente-vip' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, body: new URLSearchParams({ name: 'cliente-vip', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/accounts/tags", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, data={ "name": "cliente-vip", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], CURLOPT_POSTFIELDS => http_build_query([ 'name' => 'cliente-vip', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta traz o ID da etiqueta nova: ```json {"id": 2001} ``` Guarde o ID. Crie só depois de procurar: o contrato não diz se a API recusa um nome repetido. ### Passo 3: Ponha a etiqueta no contato Use [Adicionar etiqueta ao contato](https://docs.nextags.com.br/referencia/etiquetas/adicionar-etiqueta-ao-contato/), com o ID do contato e o da etiqueta no caminho. A chamada não tem corpo. **Adicionar etiqueta ao contato** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. ### Passo 4: Tire a etiqueta do contato Use [Remover etiqueta do contato](https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato/), no mesmo endereço, com `DELETE`: **Remover etiqueta do contato** ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', { method: 'DELETE', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.delete( "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'DELETE', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. Apagar a etiqueta da conta inteira é outra chamada, [Apagar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/apagar-etiqueta/): use com cuidado. ### Passo 5: Ache o campo pelo nome Use [Buscar campo pelo nome](https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/). A resposta traz o ID e o tipo do campo: **Buscar campo pelo nome** ```bash curl "https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json {"id": 3001, "name": "cidade", "type": 0, "description": "Cidade do contato"} ``` O `type` diz o formato do valor: `0` texto, `1` número, `2` data, `3` data e hora, `4` sim/não. Veja a tabela completa em [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/). ### Passo 6: Preencha o campo do contato Use [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/). Esta chamada recebe formulário, com o valor em `value`: **Preencher campo do contato** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'value=São Paulo' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, body: new URLSearchParams({ value: 'São Paulo', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, data={ "value": "São Paulo", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], CURLOPT_POSTFIELDS => http_build_query([ 'value' => 'São Paulo', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. O valor segue o tipo do campo: | Tipo do campo | Exemplo de `value` | |---|---| | Texto, Texto longo | `São Paulo` | | Número | `42` | | Data | `1794279600` (Unix em segundos: 10/11/2026, 0h em Brasília) | | Data e hora | `1794331800` (10/11/2026, 14h30 em Brasília) | | Verdadeiro/Falso | `1` ou `0` | ### Passo 7: Limpe o campo do contato Use [Limpar campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/limpar-campo-do-contato/), no mesmo endereço, com `DELETE`: **Limpar campo do contato** ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', { method: 'DELETE', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.delete( "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'DELETE', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. ### Passo 8: Mude o valor de um campo do bot O campo do bot tem um valor só, que vale para a conta toda, como um link de promoção usado em vários fluxos. Use [Preencher campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot/), também com formulário e o valor em `value`: **Preencher campo do bot** ```bash curl -X POST "https://app.nextagsai.com.br/api/accounts/bot_fields/3101" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'value=https://seusistema.exemplo.com.br/promocao-de-novembro' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/bot_fields/3101', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, body: new URLSearchParams({ value: 'https://seusistema.exemplo.com.br/promocao-de-novembro', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/accounts/bot_fields/3101", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, data={ "value": "https://seusistema.exemplo.com.br/promocao-de-novembro", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], CURLOPT_POSTFIELDS => http_build_query([ 'value' => 'https://seusistema.exemplo.com.br/promocao-de-novembro', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. Para ler o valor, use [Consultar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/consultar-campo-do-bot/) (`GET` no mesmo endereço); para limpar, [Limpar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/limpar-campo-do-bot/) (`DELETE`). ## Pronto: como conferir Consulte o campo do contato: **Consultar campo do contato** ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json {"id": 3001, "name": "cidade", "type": 0, "value": "São Paulo"} ``` - Para todas as etiquetas do contato, use [Listar etiquetas do contato](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas-do-contato/); para todos os campos, [Listar campos do contato](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-do-contato/). - Na NexTags, o painel do contato, na **Caixa de Entrada**, mostra as etiquetas e os campos. Veja [Etiquetas e campos personalizados na conversa](https://help.nextags.com.br/tutoriais/caixa-de-entrada/etiquetas-e-campos-na-conversa/). > **Pelo nome, sem buscar o ID:** > Para pôr etiquetas e preencher campos pelo nome, numa chamada só, use as ações `add_tag`, `remove_tag`, `set_field_value` e `unset_field_value` em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### O campo ficou vazio ou com outro valor O valor não combina com o tipo do campo, ou foi enviado como JSON. Mande formulário com `value`, data em Unix timestamp em segundos e sim/não como `1` ou `0`. ### A data aparece um dia antes O painel mostra a data no fuso de quem está vendo. Mande a meia-noite no horário de Brasília (3h em UTC), não a meia-noite em UTC. ### A busca pelo nome não acha a etiqueta ou o campo O nome precisa ser igual ao da conta, com maiúsculas, acentos e espaços, e codificado na URL. Confira em [Listar etiquetas](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas/) ou [Listar campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-personalizados/). ### 400 ou 404 com um ID O ID do contato, da etiqueta ou do campo está errado ou é de outra conta. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/etiquetas-e-campos.md e https://docs.nextags.com.br/comecar/campos-e-variaveis.md. Quando [o evento no seu sistema, por exemplo: o cliente muda de plano], quero pôr a etiqueta [nome] e preencher os campos [nomes e tipos] do contato na NexTags. Escreva, em [linguagem], o código que acha os IDs pelo nome uma vez, guarda numa configuração e depois atualiza o contato pelos IDs, com o valor de cada campo no formato do tipo dele. A chave vem da variável de ambiente NEXTAGS_API_KEY. ``` --- # Encontrar um contato pelo e-mail ou telefone > Ache o contato pelo telefone, pelo e-mail ou pelo valor de um campo personalizado, e saiba o que fazer quando a busca traz mais de um resultado. Endereço: https://docs.nextags.com.br/guias/buscar-contato-por-campo/ Tipo: Guia Atualizado em: 26/10/2026 A API não tem uma lista de contatos: para achar alguém, você busca pelo valor de um campo. A mesma chamada, [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/), procura pelo telefone, pelo e-mail ou por qualquer campo personalizado, e devolve até 100 contatos, os de mudança mais recente no campo primeiro. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - O valor do jeito que ele está salvo na NexTags. O telefone vai completo e só com números, como `5511988776655`. Veja [O formato certo do telefone](https://help.nextags.com.br/tutoriais/contatos/formato-do-telefone/). - Para buscar por um campo personalizado: o ID do campo. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ## Passo a passo ### Passo 1: Busque pelo telefone Mande `field_id=phone` e o telefone em `value`: **Buscar pelo telefone** ```bash curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({ field_id: 'phone', value: '5511988776655', })}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/find_by_custom_field", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={ "field_id": "phone", "value": "5511988776655", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php 'phone', 'value' => '5511988776655', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Os contatos vêm na lista `data`, com o `id`, o nome, o canal, as etiquetas e os campos de cada um (aqui, resumido): ```json { "data": [ { "id": 123456789, "first_name": "Ana", "last_name": "Souza", "channel": 5, "subscribed_date": "2026-10-20 14:40:00", "tags": [{"id": 2001, "name": "cliente-vip"}], "custom_fields": [ {"id": 3001, "name": "cidade", "type": 0, "value": "São Paulo"} ] } ] } ``` Se `data` vier vazia ou não vier, a busca não achou ninguém com esse telefone. ### Passo 2: Busque pelo e-mail Mande `field_id=email` e o e-mail em `value`: **Buscar pelo e-mail** ```bash curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=email&value=ana%40exemplo.com.br" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({ field_id: 'email', value: 'ana@exemplo.com.br', })}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/find_by_custom_field", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={ "field_id": "email", "value": "ana@exemplo.com.br", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php 'email', 'value' => 'ana@exemplo.com.br', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ### Passo 3: Busque por um campo personalizado Mande o ID do campo em `field_id`. Um campo que identifica a pessoa, como o código do cliente no seu sistema, traz um contato só; um campo como a cidade traz vários: **Buscar pela cidade** ```bash curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=3001&value=S%C3%A3o%20Paulo" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({ field_id: '3001', value: 'São Paulo', })}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/find_by_custom_field", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={ "field_id": "3001", "value": "São Paulo", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php '3001', 'value' => 'São Paulo', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Os exemplos codificam o valor na URL: o espaço vira `%20` ou `+`, e o `ã` vira `%C3%A3`. Faça o mesmo no seu código. Um `+` de verdade, como o de um telefone salvo com `+55`, precisa ir como `%2B`; sem codificar, ele vira espaço. ### Passo 4: Escolha o contato certo quando vierem vários A busca traz até 100 contatos, os de mudança mais recente no campo primeiro. Isso acontece com campos que se repetem (cidade, plano) e pode acontecer também quando a mesma pessoa tem um contato em cada canal. Escolha pelo que o seu sistema sabe: o canal, o nome ou outro campo. Nunca atualize todos os resultados de uma vez. **Escolher o contato** ```javascript const consulta = new URLSearchParams({ field_id: 'phone', value: '5511988776655' }); const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${consulta}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY }, }); const { data = [] } = await resposta.json(); // prefere o contato do WhatsApp (channel 5); senão, o primeiro, que é o de mudança mais recente const contato = data.find((c) => c.channel === 5) || data[0] || null; console.log(data.length, contato && contato.id); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/find_by_custom_field", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={"field_id": "phone", "value": "5511988776655"}, timeout=30, ) lista = resposta.json().get("data") or [] # prefere o contato do WhatsApp (channel 5); senão, o primeiro, que é o de mudança mais recente contato = next((c for c in lista if c.get("channel") == 5), lista[0] if lista else None) print(len(lista), contato and contato["id"]) ``` ```php 'phone', 'value' => '5511988776655', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $lista = json_decode(curl_exec($ch), true)['data'] ?? []; // prefere o contato do WhatsApp (channel 5); senão, o primeiro, que é o de mudança mais recente $contato = $lista[0] ?? null; foreach ($lista as $item) { if (($item['channel'] ?? null) === 5) { $contato = $item; break; } } echo count($lista), ' ', $contato['id'] ?? '-', PHP_EOL; ``` O `channel` de cada contato: `5` WhatsApp, `10` Instagram, `0` Messenger, `8` Telegram, `9` webchat e `17` TikTok. ## Pronto: como conferir - A busca devolve o contato esperado em `data`, com o `id` que você vai usar nas próximas chamadas. - Confira o contato pelo ID com [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/) (`GET /contacts/123456789`). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### 400 com "Invalid parameters" Falta o `field_id` ou o `value`. Os dois são obrigatórios. ### Não acha um contato que existe O telefone pode estar salvo noutro formato, sem o `55`, com `+` ou sem o 9, e não foi conferido se a busca acha esses casos. Tente o e-mail, confira como o telefone aparece no painel do contato e padronize os telefones do seu sistema. ### Vieram contatos de mais O campo se repete entre contatos. Busque por um campo que identifique a pessoa (telefone, e-mail ou um código seu) ou escolha entre os resultados, como no passo 4. ### Falta alguém numa busca com muitos resultados A busca traz no máximo 100 contatos e não tem paginação. Para listas grandes, use um campo mais específico ou exporte os contatos na tela. Veja [Exportar contatos](https://help.nextags.com.br/tutoriais/contatos/exportar-contatos/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/buscar-contato-por-campo.md. Escreva, em [linguagem], uma função que acha o contato da NexTags de um cliente do [seu sistema]: procura pelo telefone (formato 55 + DDD + número, só números), depois pelo e-mail se não achar, e, quando vierem vários, escolhe [o critério, por exemplo: o do WhatsApp]. A chave vem da variável de ambiente NEXTAGS_API_KEY. Devolva o ID do contato ou nada. ``` --- # Criar e mover oportunidades no pipeline > Liste pipelines e etapas, crie a oportunidade do contato, mova de etapa, marque como ganha ou perdida, transfira para outro pipeline e comente, pela API. Endereço: https://docs.nextags.com.br/guias/oportunidades-no-pipeline/ Tipo: Guia Atualizado em: 26/10/2026 Os pipelines da NexTags acompanham negócios e atendimentos em etapas, como um quadro kanban. Pela API, o seu sistema cria a oportunidade quando o lead chega, move de etapa quando a proposta sai, marca como ganha quando o pagamento entra e deixa um comentário com o que aconteceu. Neste guia, você faz esse caminho inteiro. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - Um pipeline criado na NexTags. Veja [Criar um pipeline a partir de um modelo](https://help.nextags.com.br/tutoriais/pipelines/criar-pipeline/). - O ID do contato e, se for atribuir a oportunidade, o ID do administrador. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ## Passo a passo ### Passo 1: Liste os pipelines Use [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/) para achar o ID do pipeline: **Listar pipelines** ```bash curl "https://app.nextagsai.com.br/api/pipelines" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/pipelines", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json {"data": [{"id": 4001, "name": "Vendas"}, {"id": 4002, "name": "Pós-venda"}]} ``` A lista aceita `offset` e `limit` (padrão `0` e `100`). Veja [Limites, erros e boas práticas](https://docs.nextags.com.br/comecar/limites-e-erros/). ### Passo 2: Liste as etapas Use [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/). As etapas vêm na lista `data`: **Listar etapas do pipeline** ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/stages" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/stages', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/pipelines/4001/stages", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json { "data": [ {"id": 4101, "name": "Lead"}, {"id": 4102, "name": "Proposta enviada"}, {"id": 4103, "name": "Fechado"} ] } ``` Guarde os IDs das etapas no seu sistema: eles não aparecem na tela. ### Passo 3: Veja os campos do pipeline Cada pipeline pode ter campos próprios, criados nas **Definições** dele. Use [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/) para ver o `id`, o `name`, o `type` e a `description` de cada um: **Listar campos do pipeline** ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/custom_fields" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/custom_fields', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/pipelines/4001/custom_fields", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Esses campos são da oportunidade, não do contato. Veja [Comentários, anexos e campos do pipeline](https://help.nextags.com.br/tutoriais/pipelines/comentarios-e-anexos/). ### Passo 4: Procure antes de criar Use [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/) com o `contact_id` para ver se o contato já tem uma oportunidade neste pipeline: **Oportunidades do contato** ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities?contact_id=123456789" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch(`https://app.nextagsai.com.br/api/pipelines/4001/opportunities?${new URLSearchParams({ contact_id: '123456789', })}`, { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/pipelines/4001/opportunities", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, params={ "contact_id": "123456789", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php '123456789', ])); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Se a lista `data` vier com uma oportunidade aberta, atualize essa (passo 7) em vez de criar outra. ### Passo 5: Crie a oportunidade Use [Criar oportunidade](https://docs.nextags.com.br/referencia/pipelines/criar-oportunidade/). O `contact_id` e o `title` são obrigatórios; o resto é opcional: **Criar oportunidade** ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact_id": 123456789, "title": "Bolo de casamento - Ana Souza", "description": "Bolo de 3 andares para 120 pessoas", "value": 1200, "stage_id": 4101, "status": "open", "priority": "high", "assigned_admins": [ 10001 ], "custom_fields": [ { "name": "Origem", "value": "Site" } ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ contact_id: 123456789, title: 'Bolo de casamento - Ana Souza', description: 'Bolo de 3 andares para 120 pessoas', value: 1200, stage_id: 4101, status: 'open', priority: 'high', assigned_admins: [10001], custom_fields: [ { name: 'Origem', value: 'Site', }, ], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/pipelines/4001/opportunities", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "contact_id": 123456789, "title": "Bolo de casamento - Ana Souza", "description": "Bolo de 3 andares para 120 pessoas", "value": 1200, "stage_id": 4101, "status": "open", "priority": "high", "assigned_admins": [10001], "custom_fields": [ { "name": "Origem", "value": "Site", }, ], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'contact_id' => 123456789, 'title' => 'Bolo de casamento - Ana Souza', 'description' => 'Bolo de 3 andares para 120 pessoas', 'value' => 1200, 'stage_id' => 4101, 'status' => 'open', 'priority' => 'high', 'assigned_admins' => [10001], 'custom_fields' => [ [ 'name' => 'Origem', 'value' => 'Site', ], ], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` | Campo | O que é | |---|---| | `stage_id` | A etapa. Sem ele, a oportunidade entra na primeira etapa. | | `value` | O valor. O contrato não diz a unidade: confira no primeiro teste como ele aparece no cartão. | | `status` | `open` (**Aberto**, o padrão), `won` (**Ganho**) ou `lost` (**Perdido**). | | `priority` | `low` (**Baixa**), `medium` (**Média**, o padrão) ou `high` (**Alta**). | | `assigned_admins` | Os IDs dos administradores responsáveis. | | `custom_fields` | Os campos do pipeline, como `{"id": …, "value": …}` ou `{"name": …, "value": …}`. | A resposta traz a oportunidade criada dentro de `data`: ```json { "data": [ { "id": 4201, "contact_id": 123456789, "title": "Bolo de casamento - Ana Souza", "description": "Bolo de 3 andares para 120 pessoas", "value": 1200, "status": "open", "priority": "high", "stage": {"id": 4101, "name": "Lead"}, "assigned_admins": [10001], "created_at": "2026-10-26 12:00:00", "created_by": 10001, "updated_at": "2026-10-26 12:00:00", "updated_by": 10001 } ] } ``` ### Passo 6: Consulte a oportunidade antes de mudar Use [Consultar oportunidade](https://docs.nextags.com.br/referencia/pipelines/consultar-oportunidade/) para ter os valores atuais: **Consultar oportunidade** ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A atualização pede o `title` e mostra valores padrão para `value`, `status`, `priority` e `assigned_admins`, e o contrato não diz se os campos que faltam ficam como estão. Por isso, mande de volta os valores atuais junto com o que muda. ### Passo 7: Mova de etapa Use [Atualizar oportunidade](https://docs.nextags.com.br/referencia/pipelines/atualizar-oportunidade/) com o `stage_id` novo e os valores atuais do passo 6 (a etapa atual vem em `stage.id`): **Mover para Proposta enviada** ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Bolo de casamento - Ana Souza", "description": "Bolo de 3 andares para 120 pessoas", "stage_id": 4102, "value": 1200, "status": "open", "priority": "high", "assigned_admins": [ 10001 ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Bolo de casamento - Ana Souza', description: 'Bolo de 3 andares para 120 pessoas', stage_id: 4102, value: 1200, status: 'open', priority: 'high', assigned_admins: [10001], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "title": "Bolo de casamento - Ana Souza", "description": "Bolo de 3 andares para 120 pessoas", "stage_id": 4102, "value": 1200, "status": "open", "priority": "high", "assigned_admins": [10001], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'title' => 'Bolo de casamento - Ana Souza', 'description' => 'Bolo de 3 andares para 120 pessoas', 'stage_id' => 4102, 'value' => 1200, 'status' => 'open', 'priority' => 'high', 'assigned_admins' => [10001], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. ### Passo 8: Marque como ganha ou perdida Na mesma chamada, mude o `status` para `won` (ganha) ou `lost` (perdida). Dá para mover para a última etapa ao mesmo tempo: **Marcar como ganha** ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Bolo de casamento - Ana Souza", "description": "Bolo de 3 andares para 120 pessoas", "stage_id": 4103, "value": 1200, "status": "won", "priority": "high", "assigned_admins": [ 10001 ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'Bolo de casamento - Ana Souza', description: 'Bolo de 3 andares para 120 pessoas', stage_id: 4103, value: 1200, status: 'won', priority: 'high', assigned_admins: [10001], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "title": "Bolo de casamento - Ana Souza", "description": "Bolo de 3 andares para 120 pessoas", "stage_id": 4103, "value": 1200, "status": "won", "priority": "high", "assigned_admins": [10001], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'title' => 'Bolo de casamento - Ana Souza', 'description' => 'Bolo de 3 andares para 120 pessoas', 'stage_id' => 4103, 'value' => 1200, 'status' => 'won', 'priority' => 'high', 'assigned_admins' => [10001], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Para reabrir, mande `status` como `open`. Para apagar a oportunidade, use [Apagar oportunidade](https://docs.nextags.com.br/referencia/pipelines/apagar-oportunidade/) (`DELETE` no mesmo endereço). ### Passo 9: Transfira para outro pipeline Use [Transferir oportunidade de pipeline](https://docs.nextags.com.br/referencia/pipelines/transferir-oportunidade-de-pipeline/), com o pipeline e a etapa de destino. Os dois são obrigatórios: **Transferir para o Pós-venda** ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "target_pipeline_id": 4002, "target_stage_id": 4111 }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ target_pipeline_id: 4002, target_stage_id: 4111, }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "target_pipeline_id": 4002, "target_stage_id": 4111, }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'target_pipeline_id' => 4002, 'target_stage_id' => 4111, ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. Depois disso, use o pipeline de destino (`4002`) no caminho das próximas chamadas. Os IDs das etapas do outro pipeline vêm de [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/). ### Passo 10: Comente na oportunidade Use [Comentar na oportunidade](https://docs.nextags.com.br/referencia/pipelines/comentar-na-oportunidade/), com o texto em `content`: **Comentar na oportunidade** ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4002/opportunities/4201/comments" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "Pagamento confirmado. Entrega no sábado, às 10h." }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4002/opportunities/4201/comments', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ content: 'Pagamento confirmado. Entrega no sábado, às 10h.', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/pipelines/4002/opportunities/4201/comments", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "content": "Pagamento confirmado. Entrega no sábado, às 10h.", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'content' => 'Pagamento confirmado. Entrega no sábado, às 10h.', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta traz o comentário, com o texto em `data`: ```json { "id": 4301, "data": "Pagamento confirmado. Entrega no sábado, às 10h.", "created_at": "2026-10-26 12:05:00", "created_by": 10001 } ``` Para ler os comentários, use [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/); para apagar, [Apagar comentário](https://docs.nextags.com.br/referencia/pipelines/apagar-comentario/). ## Pronto: como conferir - [Consultar oportunidade](https://docs.nextags.com.br/referencia/pipelines/consultar-oportunidade/) mostra a etapa em `stage`, o `status` e os responsáveis. - Na NexTags, o cartão aparece na coluna da etapa, com o valor, a prioridade e o comentário. Veja [Oportunidades e tickets: criar, mover, ganhar e perder](https://help.nextags.com.br/tutoriais/pipelines/oportunidades/). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### A oportunidade foi criada duas vezes A criação rodou sem a busca antes. Liste as oportunidades do contato (passo 4) antes de criar. Para apagar a repetida, use [Apagar oportunidade](https://docs.nextags.com.br/referencia/pipelines/apagar-oportunidade/). ### Depois de mover, o valor, a prioridade ou os responsáveis mudaram Se a atualização foi sem os valores atuais, os campos que faltaram podem ter voltado ao padrão. Consulte a oportunidade antes (passo 6) e mande de volta tudo o que deve ficar igual. ### A oportunidade entrou na primeira etapa O `stage_id` não veio ou não é deste pipeline. Liste as etapas do pipeline (passo 2) e use um ID da lista. ### O campo do pipeline ficou vazio O nome ou o ID do campo não bate com os do pipeline. Liste os campos (passo 3) e use o `id` ou o `name` exatos. ### O pipeline de suporte mostra outros estados Nos pipelines de suporte, a tela mostra **Resolvido** e **Não Resolvido** no lugar de **Ganho** e **Perdido**. Confira no primeiro teste como `won` e `lost` aparecem no seu pipeline. ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/oportunidades-no-pipeline.md. Quero ligar o [seu sistema, por exemplo: o CRM ou o checkout] ao pipeline [nome] da NexTags: criar a oportunidade quando [evento], mover para a etapa [nome] quando [evento] e marcar como ganha quando [evento], com um comentário em cada mudança. Escreva, em [linguagem], o código com os IDs numa configuração, que procura a oportunidade do contato antes de criar e sempre manda os valores atuais na atualização. A chave vem da variável de ambiente NEXTAGS_API_KEY. ``` --- # Carrinho, pedidos e produtos > Consulte e atualize produtos, envie produtos, mexa no carrinho e mude o status, a entrega e o pagamento dos pedidos pela API, com valores em centavos. Endereço: https://docs.nextags.com.br/guias/carrinho-e-pedidos/ Tipo: Guia Atualizado em: 26/10/2026 O E-commerce da NexTags vende pela conversa: o contato vê os produtos, monta o carrinho e fecha o pedido. Pela API, o seu sistema mantém preço e estoque em dia, mexe no carrinho do contato e acompanha o pedido até a entrega e o pagamento. Atenção às unidades: o preço do produto vai em reais, e os totais do carrinho e do pedido, em centavos. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - Os produtos cadastrados em **Ferramentas** › **Ecommerce**. Veja [Cadastrar produtos](https://help.nextags.com.br/tutoriais/ecommerce/cadastrar-produtos/). - Os IDs do produto, do contato e do pedido. A API não lista produtos nem pedidos: veja onde achar cada ID em [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ## Passo a passo ### Passo 1: Consulte o produto Use [Consultar produto](https://docs.nextags.com.br/referencia/ecommerce/consultar-produto/): **Consultar produto** ```bash curl "https://app.nextagsai.com.br/api/products/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/products/6001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json { "id": 6001, "name": "Bolo de chocolate", "price": 89.9, "sale_price": 79.9, "category_id": 6101, "category_name": "Bolos", "stock": 12, "short_description": "Serve 12 pessoas", "image": "https://seusistema.exemplo.com.br/img/bolo-de-chocolate.jpg", "created_at": "2026-10-01 12:00:00" } ``` O `price` está em reais: `89.9` é R$ 89,90. ### Passo 2: Atualize o preço, o estoque e se está à venda Use [Atualizar produto](https://docs.nextags.com.br/referencia/ecommerce/atualizar-produto/). Mande só o que muda: `price`, `stock` e `active` (se os contatos podem comprar o produto). **Atualizar produto** ```bash curl -X POST "https://app.nextagsai.com.br/api/products/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "price": 94.9, "stock": 20, "active": true }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ price: 94.9, stock: 20, active: true, }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/products/6001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "price": 94.9, "stock": 20, "active": True, }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'price' => 94.9, 'stock' => 20, 'active' => true, ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true, "updated": true}`. Confira na lista de **Produtos** que o preço ficou R$ 94,90. ### Passo 3: Envie produtos ao contato Use [Enviar produtos ao contato](https://docs.nextags.com.br/referencia/ecommerce/enviar-produtos-ao-contato/). O `product_id` aceita um ID, uma lista de IDs ou IDs separados por vírgula: **Enviar produtos ao contato** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/products" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "product_id": [ 6001, 6002 ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/products', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ product_id: [6001, 6002], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/send/products", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "product_id": [6001, 6002], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'product_id' => [6001, 6002], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` O contrato não descreve a resposta: confira o código HTTP e a conversa na **Caixa de Entrada**. Como toda mensagem, o envio segue a janela de 24 horas do WhatsApp. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/). ### Passo 4: Ponha um produto no carrinho Use [Adicionar produto ao carrinho](https://docs.nextags.com.br/referencia/ecommerce/adicionar-produto-ao-carrinho/). Esta chamada recebe formulário, com a quantidade em `quantity`: **Adicionar produto ao carrinho** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'quantity=2' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, body: new URLSearchParams({ quantity: 2, }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, data={ "quantity": 2, }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], CURLOPT_POSTFIELDS => http_build_query([ 'quantity' => 2, ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. ### Passo 5: Consulte o carrinho Use [Consultar carrinho](https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/): **Consultar carrinho** ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/cart" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/123456789/cart", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta (aqui, resumida) traz o `order_id`, os totais em centavos e os itens, com o `price` de cada item em reais: ```json { "order_id": "PED-1001", "user_id": 123456789, "currency": "BRL", "total": 17980, "subtotal": 17980, "total_items": 2, "coupon_discount": 0, "coupon": "", "line_items": [ {"id": 6001, "name": "Bolo de chocolate", "price": 89.9, "amount": 2} ] } ``` | Campo | Unidade | No exemplo | |---|---|---| | `total`, `subtotal`, `coupon_discount` | Centavos | `17980` = R$ 179,80 | | `line_items[].price` | Reais | `89.9` = R$ 89,90 | | `line_items[].amount` | Quantidade | `2` | ### Passo 6: Tire um produto ou esvazie o carrinho Para tirar um produto, use [Remover produto do carrinho](https://docs.nextags.com.br/referencia/ecommerce/remover-produto-do-carrinho/): **Remover produto do carrinho** ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', { method: 'DELETE', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.delete( "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'DELETE', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Para tirar tudo, use [Esvaziar carrinho](https://docs.nextags.com.br/referencia/ecommerce/esvaziar-carrinho/): **Esvaziar carrinho** ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', { method: 'DELETE', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.delete( "https://app.nextagsai.com.br/api/contacts/123456789/cart", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'DELETE', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` As duas respondem `{"success": true}`. ### Passo 7: Consulte o pedido Use [Consultar pedido](https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/), com o ID do pedido. O ID é texto: mande do jeito que veio. **Consultar pedido** ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta tem o mesmo formato do carrinho, com os valores em centavos. ### Passo 8: Mude o status e a entrega Use [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/). O `status` aceita quatro valores, e os dados de entrega e a nota são opcionais: **Alterar pedido** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": 7, "name": "Ana Souza", "phone": "5511988776655", "city": "São Paulo", "state": "SP", "zip_code": "01310-100", "address": "Avenida Paulista, 1000", "note": "Saiu para entrega." }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ status: 7, name: 'Ana Souza', phone: '5511988776655', city: 'São Paulo', state: 'SP', zip_code: '01310-100', address: 'Avenida Paulista, 1000', note: 'Saiu para entrega.', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "status": 7, "name": "Ana Souza", "phone": "5511988776655", "city": "São Paulo", "state": "SP", "zip_code": "01310-100", "address": "Avenida Paulista, 1000", "note": "Saiu para entrega.", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'status' => 7, 'name' => 'Ana Souza', 'phone' => '5511988776655', 'city' => 'São Paulo', 'state' => 'SP', 'zip_code' => '01310-100', 'address' => 'Avenida Paulista, 1000', 'note' => 'Saiu para entrega.', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` | `status` | No contrato | Na tela | |---|---|---| | `6` | Em processamento | **Aceito** | | `7` | Enviado | **Entregando** | | `10` | Concluído | **Concluído** | | `13` | Cancelado | **Cancelado** | Os dados de entrega são `name`, `phone`, `email`, `country`, `state`, `city`, `zip_code`, `address`, `street_1` e `street_2`, e `note` guarda uma nota do pedido. A resposta é `{"success": true}`. ### Passo 9: Marque o pedido como pago Use [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/). Esta chamada recebe formulário, com o valor pago em centavos em `amount_received`: **Marcar pedido como pago** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'amount_received=17980' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, body: new URLSearchParams({ amount_received: 17980, }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, data={ "amount_received": 17980, }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], CURLOPT_POSTFIELDS => http_build_query([ 'amount_received' => 17980, ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. O valor não pode ser menor que o total do pedido. ## Pronto: como conferir - [Consultar pedido](https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/) mostra o pedido com os valores certos. - Na **Caixa de Entrada**, o painel do contato lista os **Pedidos**, com o valor, a data e a situação. Veja [Carrinho e pedidos na conversa](https://help.nextags.com.br/tutoriais/ecommerce/carrinho-e-pedidos/). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### Alterar pedido: 400 com "Order status must be 6, 7, 10, or 13" O `status` não é um dos quatro aceitos. Use `6`, `7`, `10` ou `13`, como número. ### Alterar pedido: 402 O pedido já está nesse status. Consulte o pedido antes e só mande o `status` quando ele mudar. ### Marcar pedido como pago: 400 O `amount_received` é menor que o total do pedido. Confira se mandou em centavos: R$ 179,80 é `17980`, não `179.80`. ### Marcar pedido como pago: 402 O pagamento não foi concluído. O contrato descreve assim: o contato recebe uma mensagem no Messenger com o motivo da falha do checkout. Consulte o pedido e a conversa do contato para entender o caso. ### 404 com "The order ID doesn't existe" O ID do pedido não existe para esse contato. Confira o `order_id` e o ID do contato: os dois vão no caminho. ### O preço do produto ficou cem vezes maior O `price` do produto vai em reais, não em centavos. Para R$ 94,90, mande `94.9`. ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/carrinho-e-pedidos.md. Quero manter o E-commerce da NexTags em dia com [o seu sistema, por exemplo: o ERP da loja]: atualizar preço e estoque dos produtos quando mudarem, mudar o status do pedido quando [eventos de entrega] e marcar como pago quando [o pagamento for aprovado]. Escreva, em [linguagem], o código com a conversão certa de unidades (preço do produto em reais; totais e valor pago em centavos) e o tratamento dos erros 400, 402 e 404. A chave vem da variável de ambiente NEXTAGS_API_KEY. ``` --- # Acompanhar, reenviar e cancelar disparos > Liste e consulte os Broadcasts da conta, acompanhe o status, reenvie e cancele pela API. Criar o Broadcast continua na tela da NexTags. Endereço: https://docs.nextags.com.br/guias/disparos-pela-api/ Tipo: Guia Atualizado em: 26/10/2026 Os Broadcasts são criados na tela da NexTags, com o público, o fluxo e o horário. Pela API, o seu sistema acompanha o que já foi criado: lista os Broadcasts, consulta o status de cada um, reenvia e cancela. Use para montar um painel próprio ou para parar um envio agendado a partir de outro sistema. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - Um Broadcast criado na NexTags. Veja [Criar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/criar-disparo/). ## Passo a passo ### Passo 1: Liste os Broadcasts Use [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/). A lista vem em `data`, com até 100 itens: **Listar disparos** ```bash curl "https://app.nextagsai.com.br/api/broadcasts" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/broadcasts", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json { "data": [ { "id": 7001, "name": "Promoção de Natal", "status": "SENT", "sent_at": "2026-10-20 15:00:00", "created_by": 10001, "created_at": "2026-10-20 14:40:00" } ] } ``` O ID do Broadcast não aparece na tela: guarde o `id` que vem aqui. ### Passo 2: Consulte um Broadcast Use [Consultar disparo](https://docs.nextags.com.br/referencia/disparos/consultar-disparo/), com o ID no caminho: **Consultar disparo** ```bash curl "https://app.nextagsai.com.br/api/broadcasts/7001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts/7001', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/broadcasts/7001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta tem os mesmos campos de cada item da lista. Se o ID não existe, a resposta é `404`. | `status` | O que o nome indica | |---|---| | `DRAFT` | Rascunho | | `NOT_SENT` | Ainda não enviado | | `SENTING` | Enviando | | `SENT` | Enviado | | `CANCELLED` | Cancelado | Na tela, os Broadcasts aparecem como **Agendado**, **Pendente**, **Enviando**, **Enviado** e **Cancelado**. Confira no seu teste qual `status` corresponde a cada um, em especial **Agendado** e **Pendente**. ### Passo 3: Reenvie um Broadcast Use [Reenviar disparo](https://docs.nextags.com.br/referencia/disparos/reenviar-disparo/). A chamada não tem corpo: **Reenviar disparo** ```bash curl -X POST "https://app.nextagsai.com.br/api/broadcasts/7001/resend" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts/7001/resend', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/broadcasts/7001/resend", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. O Broadcast sai de novo: não repita a chamada para conferir. Na tela, a mesma ação fica no menu ⋮ do Broadcast, em **Reenviar**. Veja [Reenviar, cancelar e exportar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/reenviar-e-cancelar/). ### Passo 4: Cancele um Broadcast Use [Cancelar disparo](https://docs.nextags.com.br/referencia/disparos/cancelar-disparo/). A chamada não tem corpo: **Cancelar disparo** ```bash curl -X POST "https://app.nextagsai.com.br/api/broadcasts/7001/cancel" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts/7001/cancel', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/broadcasts/7001/cancel", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta é `{"success": true}`. Na tela, o **Cancelar** só aparece para Broadcasts **Agendado**, **Pendente** e no começo do **Enviando**: o que já saiu não volta. Consulte o Broadcast depois para ver se o status virou `CANCELLED`. ## Pronto: como conferir - [Consultar disparo](https://docs.nextags.com.br/referencia/disparos/consultar-disparo/) mostra o `status` novo. - Na NexTags, a lista de **Broadcasts** mostra o mesmo estado e os resultados: enviados, entregues, abertos, clicados e falhas. Veja [Resultados: entregues, abertos, clicados e falhas](https://help.nextags.com.br/tutoriais/disparos/resultados-e-custos/). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### 404 com "Broadcast not found" O ID não existe nesta conta. Liste os Broadcasts de novo e use um `id` da lista. ### O cancelamento não parou o envio O Broadcast já tinha saído, ou estava no meio do envio. Na tela, só dá para cancelar o que está **Agendado**, **Pendente** ou começando a enviar. ### Quero criar um Broadcast pela API A API não cria Broadcasts. Crie na tela, com o público e o fluxo, e use a API para acompanhar. Para enviar a um contato só, use [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/disparos-pela-api.md. Escreva, em [linguagem], um script que lista os Broadcasts da minha conta na NexTags, mostra o nome, o status e a data de envio de cada um e cancela o Broadcast [nome ou ID] se ele ainda não tiver saído. A chave vem da variável de ambiente NEXTAGS_API_KEY. ``` --- # Agentes de IA pela API > Liste os agentes do AI Hub, atualize o prompt, o modelo e o limite de tokens, veja funções, MCP e arquivos e salve mensagens no histórico da IA. Endereço: https://docs.nextags.com.br/guias/agentes-de-ia-pela-api/ Tipo: Guia Atualizado em: 26/10/2026 Os agentes de IA são criados e ajustados no AI Hub. Pela API, o seu sistema mantém o agente em dia sem abrir a tela: troca o prompt quando o cardápio ou a tabela de preços muda, ajusta o modelo e o limite de tokens e consulta as funções, os servidores MCP e os arquivos ligados aos agentes. E pode contar à IA o que aconteceu fora da conversa, salvando mensagens no histórico da IA do contato. **Antes de começar** - A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). - Um provedor de IA conectado e um agente criado no AI Hub. Veja [Conheça o AI Hub](https://help.nextags.com.br/tutoriais/ia/ia-hub/) e [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/). ## Passo a passo ### Passo 1: Liste os agentes Use [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/). O caminho termina com barra (`/agents/`), e a lista vem em `data`: **Listar agentes de IA** ```bash curl "https://app.nextagsai.com.br/api/agents/" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/agents/', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/agents/", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ```json { "data": [ {"id": 5001, "name": "Bia — Doce Encanto", "created_by": 10001, "created_at": "2026-10-01 12:00:00"} ] } ``` O ID também aparece no endereço do editor do agente, no AI Hub (`agent?id=5001`). ### Passo 2: Consulte um agente Use [Consultar agente de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/consultar-agente-de-ia/): **Consultar agente de IA** ```bash curl "https://app.nextagsai.com.br/api/agents/5001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/agents/5001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` O contrato descreve só o `id`, o `name`, o `created_by` e o `created_at`. O prompt e os modelos atuais você confere no editor do agente, no AI Hub. ### Passo 3: Atualize o prompt Use [Atualizar agente de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/atualizar-agente-de-ia/), com o texto novo em `prompt`. Ele troca a **Mensagem do sistema (Prompt)** do agente: **Atualizar o prompt** ```bash curl -X POST "https://app.nextagsai.com.br/api/agents/5001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90)." }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ prompt: 'Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90).', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/agents/5001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "prompt": "Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90).", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'prompt' => 'Você é a Bia, da confeitaria Doce Encanto. Responda em frases curtas. Bolos de hoje: chocolate (R$ 89,90) e morango (R$ 94,90).', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` A resposta traz o agente. Guarde a versão do prompt no seu sistema: assim dá para voltar à anterior. Como escrever um bom prompt: [Escrever a mensagem do sistema (prompt)](https://help.nextags.com.br/tutoriais/ia/escrever-o-prompt/). ### Passo 4: Troque o modelo e o limite de tokens Na mesma chamada, `model` leva o modelo de cada provedor (`openAI`, `gemini`, `claude`, `xAI` ou `deepseek`) e `max_output_tokens`, o limite de tokens da resposta: **Trocar o modelo** ```bash curl -X POST "https://app.nextagsai.com.br/api/agents/5001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": { "openAI": "gpt-6-luna" }, "max_output_tokens": 2048 }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: { openAI: 'gpt-6-luna', }, max_output_tokens: 2048, }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/agents/5001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "model": { "openAI": "gpt-6-luna", }, "max_output_tokens": 2048, }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'model' => [ 'openAI' => 'gpt-6-luna', ], 'max_output_tokens' => 2048, ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` - Use o nome exato do modelo, como ele aparece no AI Hub em **Modelo (OpenAI)**, **Modelo (Claude)** e nos outros. A lista vem do provedor e muda com o tempo. - No editor, o **Max tokens** vai de 1 a 32768, e o agente novo começa com 2048. - O contrato marca os cinco provedores como obrigatórios dentro de `model`. Teste mandando só o provedor que você usa e confira no editor do agente se os outros ficaram como estavam. Veja [Modelo, temperatura e limite de tokens](https://help.nextags.com.br/tutoriais/ia/modelo-e-parametros/). ### Passo 5: Veja as funções, os servidores MCP e os arquivos Três chamadas listam o que os agentes podem usar, todas com a lista em `data`: **Listar funções dos agentes** ```bash curl "https://app.nextagsai.com.br/api/agents/functions" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/agents/functions', { headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.get( "https://app.nextagsai.com.br/api/agents/functions", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` | Chamada | O que lista | Campos | |---|---|---| | [Listar funções dos agentes](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-funcoes-dos-agentes/), `GET /agents/functions` | As **Funções de IA** | `id`, `name`, `created_by`, `created_at` | | [Listar servidores MCP](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-servidores-mcp/), `GET /agents/mcp` | Os **Servidores MCP** | `id`, `name`, `created_by`, `created_at` | | [Listar arquivos dos agentes](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-arquivos-dos-agentes/), `GET /agents/files` | Os **Arquivos** (a base de conhecimento) | `id`, `name`, `size`, `url`, `created_by`, `created_at` | A API só lista: criar e ligar funções, servidores e arquivos fica no AI Hub. Veja [Funções de IA](https://help.nextags.com.br/tutoriais/ia/funcoes-do-agente/), [Servidores MCP no agente](https://help.nextags.com.br/tutoriais/ia/mcp-no-agente/) e [Arquivos: a base de conhecimento do agente](https://help.nextags.com.br/tutoriais/ia/base-de-conhecimento/). ### Passo 6: Salve mensagens no histórico da IA do contato A IA guarda um histórico da conversa de cada contato. Use [Salvar mensagens no histórico da IA](https://docs.nextags.com.br/referencia/agentes-de-ia/salvar-mensagens-no-historico-da-ia/) para pôr nesse histórico o que aconteceu fora da conversa, como um pagamento ou uma resposta dada por outro canal, e a IA leva em conta nas próximas respostas: **Salvar mensagens no histórico da IA** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "text": "O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.", "type": "text", "role": "developer" }, { "text": "Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.", "type": "text", "role": "assistant" } ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ messages: [ { text: 'O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.', type: 'text', role: 'developer', }, { text: 'Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.', type: 'text', role: 'assistant', }, ], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "messages": [ { "text": "O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.", "type": "text", "role": "developer", }, { "text": "Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.", "type": "text", "role": "assistant", }, ], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'messages' => [ [ 'text' => 'O pedido PED-1001 foi pago e sai para entrega amanhã às 10h.', 'type' => 'text', 'role' => 'developer', ], [ 'text' => 'Seu pedido foi confirmado, Ana! A entrega é amanhã às 10h.', 'type' => 'text', 'role' => 'assistant', ], ], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Cada mensagem tem `text` e `role` (os dois obrigatórios) e, se quiser, `type` (`text`, `image`, `file` ou `audio`): | `role` | Quando usar | |---|---| | `user` | Algo que o contato disse fora desta conversa, como num e-mail. | | `assistant` | Algo que foi respondido ao contato fora do agente, como pelo seu sistema. | | `developer` | Uma informação ou instrução para a IA levar em conta, que não é fala de ninguém. | As mensagens salvas não são enviadas ao contato: elas só entram no histórico. Nos fluxos, a ação de IA lê o histórico com **Lembrar conversa** em **Sim**, e **Excluir histórico de mensagens** apaga o histórico. Veja [Chamar a IA no fluxo](https://help.nextags.com.br/tutoriais/fluxos/ia-no-fluxo/). ## Pronto: como conferir - No AI Hub, abra o agente: a **Mensagem do sistema (Prompt)** mostra o texto novo, e os ajustes mostram o modelo e o **Max tokens**. - Converse com o agente e veja se ele usa o prompt novo e o que foi salvo no histórico. Veja [Testar e ajustar o agente](https://help.nextags.com.br/tutoriais/ia/testar-agente/). ## Se não funcionou ### 401 com "No valid API key provided." A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ### 400 ao atualizar o agente O corpo tem um erro: confira o JSON, o nome do provedor em `model` (`openAI`, `gemini`, `claude`, `xAI` ou `deepseek`) e se `max_output_tokens` é um número. ### O agente continua com o modelo antigo O nome do modelo não está na lista do provedor. Abra o editor do agente no AI Hub, veja os nomes em **Modelo (OpenAI)** e nos outros, e use um deles. ### A resposta do agente sai cortada O `max_output_tokens` ficou baixo para o tamanho das respostas. Aumente o valor e teste de novo. ### A IA não levou em conta o que foi salvo no histórico Confira o ID do contato e o `role` de cada mensagem. No fluxo, a ação de IA precisa estar com **Lembrar conversa** em **Sim**, e o histórico some quando roda **Excluir histórico de mensagens**. Veja [Chamar a IA no fluxo](https://help.nextags.com.br/tutoriais/fluxos/ia-no-fluxo/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/agentes-de-ia-pela-api.md. Quero manter o agente de IA [nome] da NexTags em dia com [a fonte, por exemplo: o cardápio do dia no meu sistema]. Escreva, em [linguagem], um script que monta o prompt com os dados atuais, atualiza o agente pelo ID com POST /agents/{agent_id}, guarda a versão anterior do prompt para eu poder voltar e, quando [evento], salva uma mensagem com role developer no histórico da IA do contato. A chave vem da variável de ambiente NEXTAGS_API_KEY. ``` --- # Usar a API no Make, n8n e Zapier > Chame a API da NexTags pelo módulo HTTP do Make, pelo HTTP Request do n8n e pelo Webhooks by Zapier, e faça o caminho contrário com webhooks. Endereço: https://docs.nextags.com.br/guias/make-n8n-zapier/ Tipo: Guia Atualizado em: 26/10/2026 O Make, o n8n e o Zapier chamam qualquer API pelo módulo de HTTP de cada um. Com a chave da NexTags no cabeçalho `X-ACCESS-TOKEN`, eles criam contatos, enviam fluxos, preenchem campos e movem oportunidades, com os mesmos endereços e corpos desta documentação. Neste guia, você monta a chamada nas três ferramentas e liga o caminho contrário: a NexTags avisando a ferramenta e a ferramenta mandando dados para a NexTags. **Antes de começar** - A chave de API da conta, de **Configurações** › **Integrações** › **Chave de API do NexTags**. Veja [Gerar a chave de API](https://help.nextags.com.br/tutoriais/configuracoes/chave-de-api/). - A chamada que você quer fazer: o método, o endereço e o corpo, na [Referência](https://docs.nextags.com.br/referencia/). Os exemplos deste guia usam [Criar contato](https://docs.nextags.com.br/referencia/contatos/criar-contato/). - No Zapier, um plano com o **Webhooks by Zapier** (Professional, Team ou Enterprise), segundo a [ajuda do Zapier](https://help.zapier.com/hc/en-us/articles/8496326446989) (atualizada em 10/08/2026). ## Passo a passo ### Passo 1: No Make, use o HTTP › Make a request No cenário, adicione o módulo **HTTP** › **Make a request** e preencha: - **Authentication type**: **API key**. Em **Credentials**, crie a chave: **Key** com a chave da NexTags, **API key placement** no cabeçalho (**In the header**) e **API key parameter name** com `X-ACCESS-TOKEN`. - **URL**: o endereço completo, como `https://app.nextagsai.com.br/api/contacts`. - **Method**: o da chamada (aqui, **POST**). - **Body content type**: **application/JSON**, com **Body input method** em **JSON string**, e o corpo no campo do JSON. - **Parse response**: **Yes**, para usar a resposta nos próximos módulos. **Corpo de Criar contato** ```json { "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "actions": [ {"action": "add_tag", "tag_name": "cliente-vip"} ] } ``` Troque os valores pelos dados dos módulos anteriores. A própria documentação do Make recomenda guardar a chave em **Credentials**, e não nos **Headers**. Veja a [documentação do HTTP no Make](https://apps.make.com/http) e a [chave de API no Make](https://apps.make.com/api-key-authentication-type). ### Passo 2: No n8n, use o HTTP Request Adicione o nó **HTTP Request**. O jeito mais rápido é colar o cURL da chamada em **Import cURL**: **cURL para o Import cURL** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" } ] }' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ phone: '5511988776655', email: 'ana@exemplo.com.br', first_name: 'Ana', last_name: 'Souza', actions: [ { action: 'add_tag', tag_name: 'cliente-vip', }, ], }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, json={ "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "actions": [ { "action": "add_tag", "tag_name": "cliente-vip", }, ], }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'phone' => '5511988776655', 'email' => 'ana@exemplo.com.br', 'first_name' => 'Ana', 'last_name' => 'Souza', 'actions' => [ [ 'action' => 'add_tag', 'tag_name' => 'cliente-vip', ], ], ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` Depois de importar: - Em **Authentication**, escolha **Generic Credential Type** e o tipo **Header Auth**. Crie a credencial com **Name** `X-ACCESS-TOKEN` e **Value** com a chave da NexTags. - Em **Send Headers**, apague o `X-ACCESS-TOKEN` que veio do cURL: a credencial já manda a chave. - Em **Send Body**, deixe **Body Content Type** em **JSON** e **Specify Body** em **Using JSON**. O Import cURL traz os valores como texto; com **Using JSON**, os números continuam números. Veja a [documentação do HTTP Request](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/) e das [credenciais do HTTP Request](https://docs.n8n.io/integrations/builtin/credentials/httprequest/). ### Passo 3: No Zapier, use o Webhooks by Zapier › Custom Request No Zap, adicione a ação **Webhooks by Zapier** com o evento **Custom Request** e preencha: - **Method**: o da chamada (aqui, **POST**). - **URL**: o endereço completo, como `https://app.nextagsai.com.br/api/contacts`. - **Data**: o corpo em JSON, como abaixo. O Zapier manda o texto do jeito que você escreveu: confira as aspas e as vírgulas. - **Headers**: duas linhas, `X-ACCESS-TOKEN` com a chave da NexTags e `Content-Type` com `application/json`. **Data do Custom Request** ```json { "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "actions": [ {"action": "add_tag", "tag_name": "cliente-vip"} ] } ``` Troque os valores pelos dados das etapas anteriores do Zap. Veja a [ajuda do Webhooks by Zapier](https://help.zapier.com/hc/en-us/articles/8496326446989). No Pabbly Connect, a ação equivalente é o **API by Pabbly**, com o mesmo endereço, o mesmo corpo e o cabeçalho `X-ACCESS-TOKEN`. ### Passo 4: Nas chamadas com formulário, troque o tipo do corpo Algumas chamadas recebem formulário no lugar de JSON, como [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/) e [Criar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/). A lista completa está em [Visão geral da API](https://docs.nextags.com.br/comecar/visao-geral/). Nelas: - No Make, **Body content type**: **application/x-www-form-urlencoded**, com o campo e o valor em **Body content**. - No n8n, **Body Content Type**: **Form Urlencoded**, com o campo e o valor em **Using Fields Below**. - No Zapier, **Data** com `campo=valor`, codificado para URL, e o cabeçalho `Content-Type` com `application/x-www-form-urlencoded`. **Preencher campo do contato** ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'value=São Paulo' ``` ```javascript const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', { method: 'POST', headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY, }, body: new URLSearchParams({ value: 'São Paulo', }), }); const dados = await resposta.json(); console.log(resposta.status, dados); ``` ```python import os import requests resposta = requests.post( "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001", headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]}, data={ "value": "São Paulo", }, timeout=30, ) print(resposta.status_code, resposta.json()) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'), ], CURLOPT_POSTFIELDS => http_build_query([ 'value' => 'São Paulo', ]), ]); $dados = json_decode(curl_exec($ch), true); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL; print_r($dados); ``` ### Passo 5: O caminho contrário: o fluxo avisa a ferramenta Para a NexTags mandar dados para o Make, o n8n ou o Zapier, crie um webhook na ferramenta (**Webhooks** › **Custom webhook** no Make, o nó **Webhook** no n8n, o **Catch Hook** do Webhooks by Zapier) e, num fluxo, chame esse endereço com a requisição externa. No **Corpo** em **JSON**, use as variáveis do contato: **Corpo da requisição externa** ```json { "contato_id": "{{user_id}}", "nome": "{{full_name}}", "telefone": "{{phone}}", "email": "{{email}}" } ``` O passo a passo de tela está nas páginas do [Make](https://help.nextags.com.br/integracoes/make/), do [n8n](https://help.nextags.com.br/integracoes/n8n/) e do [Zapier](https://help.nextags.com.br/integracoes/zapier/). O lado técnico, com a resposta que o seu webhook pode devolver ao fluxo, está em [Requisição externa: o fluxo chama o seu sistema](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/). Para avisar a ferramenta quando algo acontece na conta, como uma etiqueta aplicada, use os [webhooks de saída](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/). ### Passo 6: E a ferramenta manda dados para a NexTags Além da API, a ferramenta pode mandar os dados em JSON para o link de um webhook de entrada da NexTags, criado em **Ferramentas** › **Webhooks de entrada**. O webhook acha o contato pelo e-mail ou pelo telefone (e cria, se não existir), salva os valores nos campos e aciona um fluxo: **Corpo enviado ao webhook de entrada** ```json { "cliente": { "nome": "Ana Souza", "email": "ana@exemplo.com.br", "telefone": "5511988776655" }, "pedido": {"id": "PED-1001", "total": "179.80"} } ``` No webhook de entrada, cada campo é ligado a um caminho do JSON, como `$.cliente.email`. Veja [Webhook de entrada: receber dados de outro sistema](https://docs.nextags.com.br/webhooks/webhook-de-entrada/) e [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/). ## Pronto: como conferir - Rode o módulo uma vez (no Make, **Run once**; no n8n, o teste do nó; no Zapier, o teste da ação) e veja a resposta da NexTags: `200` e os dados da chamada. - Na NexTags, confira o resultado: o contato em **Contatos**, a mensagem na **Caixa de Entrada** ou o cartão em **Pipelines**. ## Se não funcionou ### 401 com "No valid API key provided." A chave não foi no cabeçalho `X-ACCESS-TOKEN`, foi com espaço a mais ou é a antiga. No Make, confira o **API key parameter name** e o **API key placement**; no n8n, o **Name** da credencial; no Zapier, a linha do cabeçalho. ### 400 ou campo vazio numa chamada com formulário A chamada recebe formulário e foi com JSON. Troque o tipo do corpo como no passo 4. ### O n8n mandou o ID como texto O **Import cURL** traz os valores como texto. Troque **Specify Body** para **Using JSON** e cole o corpo em JSON. ### O Zapier diz que o JSON é inválido, ou a NexTags recebe o corpo errado O **Data** do **Custom Request** vai do jeito que foi escrito. Confira as aspas, as vírgulas e as chaves e os campos inseridos de etapas anteriores, que precisam estar entre aspas. ### A ferramenta não recebe o que o fluxo manda O endereço da requisição externa não é o do webhook ativo, ou o fluxo não está publicado. Veja [Erros de requisição externa, webhook e planilha](https://help.nextags.com.br/tutoriais/erros/erros-de-requisicao-externa/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Leia https://docs.nextags.com.br/guias/make-n8n-zapier.md e a página do endpoint que vou usar: [cole o link da referência, por exemplo https://docs.nextags.com.br/referencia/contatos/criar-contato.md]. Estou montando no [Make / n8n / Zapier] uma automação que [descreva: por exemplo, quando chega um lead no formulário, cria o contato na NexTags e envia o fluxo de boas-vindas]. Me diga, módulo por módulo, o que preencher em cada campo do HTTP da ferramenta (método, URL, autenticação com o cabeçalho X-ACCESS-TOKEN, tipo do corpo e corpo), sem pedir a minha chave. ``` --- # Webhooks > Receba dados de outros sistemas e envie eventos da NexTags para o seu. Endereço: https://docs.nextags.com.br/webhooks/ Tipo: Seção ## Páginas - [Webhooks na NexTags](https://docs.nextags.com.br/webhooks/visao-geral.md): As quatro formas de trocar dados com outro sistema (webhook de entrada, webhook de saída, requisição externa e API) e quando usar cada uma. - [Webhook de entrada: receber dados de outro sistema](https://docs.nextags.com.br/webhooks/webhook-de-entrada.md): Mande um JSON de outro sistema para o link de um webhook de entrada. O formato, o contato achado pelo telefone ou e-mail, o JSONPath aceito e um teste em cURL. - [Requisição externa: o fluxo chama o seu sistema](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo.md): Prepare o seu servidor para a requisição externa do fluxo: o que chega, o cabeçalho X-USER-ID, o que responder para guardar dados ou mandar mensagens e ações. - [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos.md): JSONPath na prática: o caminho de cada valor num JSON de exemplo, o tipo de campo certo e o que muda entre o webhook de entrada e o fluxo. - [Segurança, testes e novas tentativas](https://docs.nextags.com.br/webhooks/seguranca-e-testes.md): Como proteger o link do webhook de entrada, o endereço de saída e a requisição externa, como testar sem sistema pronto, tratar repetições e achar os erros. - [Exemplos: Hotmart, Kiwify, Shopify e formulários](https://docs.nextags.com.br/webhooks/exemplos-de-plataformas.md): O que a Hotmart, a Kiwify e a Shopify mandam por webhook e os caminhos de telefone, e-mail, nome, produto e status. E um formulário do site sem expor o link. _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._ --- # Webhooks na NexTags > As quatro formas de trocar dados com outro sistema (webhook de entrada, webhook de saída, requisição externa e API) e quando usar cada uma. Endereço: https://docs.nextags.com.br/webhooks/visao-geral/ Tipo: Conceito Atualizado em: 26/10/2026 A NexTags troca dados com outros sistemas de quatro jeitos. Em dois deles, quem chama é o outro sistema: o webhook de entrada e a API. Nos outros dois, quem chama é a NexTags: o webhook de saída e a requisição externa do fluxo. Esta página mostra a diferença e ajuda a escolher. O passo a passo de tela de cada recurso está na Central de Ajuda; aqui fica a parte técnica. ## Como funciona | Forma | Quem chama quem | Onde fica no app | O que acontece | |---|---|---|---| | Webhook de entrada | O outro sistema chama um link da sua conta | **Ferramentas** › **Webhooks de entrada** | A NexTags acha o contato pelo telefone ou pelo e-mail (ou cria um novo), salva os valores recebidos nos campos e inicia um fluxo. | | Webhook de saída | A NexTags chama um endereço do seu sistema | **Ferramentas** › **Webhooks de saída** | Quando um evento escolhido acontece na conta, como **Etiqueta Aplicada**, a NexTags avisa o endereço que está em **Notificar este URL**. | | Requisição externa | O fluxo chama a sua API | Etapa **Ações** do fluxo › **External API Request** | Quando o contato chega à etapa, o fluxo chama a sua API e usa a resposta: guarda dados em campos ou manda mensagens e executa ações. | | API | O seu sistema chama a NexTags | `https://app.nextagsai.com.br/api`, com a chave no cabeçalho `X-ACCESS-TOKEN` | O seu sistema cria e acha contatos, manda fluxos e mensagens, aplica etiquetas, preenche campos e move oportunidades. | ### Webhook de entrada Cada webhook de entrada tem um link próprio, copiado em **Obter Link**. O outro sistema manda um JSON para esse link. O link não pede a chave de API: quem tem o link consegue criar contatos e iniciar o fluxo, por isso ele é um segredo. - O JSON precisa trazer o telefone ou o e-mail do contato. Basta um dos dois. - Os valores vão para os campos do contato por caminhos JSONPath, como `$.cliente.email`. - Depois de salvar os campos, a NexTags inicia o fluxo escolhido em **Enviar Fluxo**. Detalhes em [Webhook de entrada: receber dados de outro sistema](https://docs.nextags.com.br/webhooks/webhook-de-entrada/) e [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos/). A tela, passo a passo: [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/). ### Webhook de saída O webhook de saída usa os mesmos eventos dos Acionadores e Ações, menos os de e-mail: contato novo, etiqueta aplicada ou removida, campo alterado, conversa atribuída, oportunidade criada ou movida, pedido novo e outros. A lista completa está em [Todos os eventos dos acionadores](https://help.nextags.com.br/tutoriais/ferramentas/eventos-dos-acionadores/). Na tela, a lista se chama **Webhooks**. - O endereço precisa começar com `https://`. Com `http://`, a tela mostra "The URL must start with https". - O formato do aviso (método, corpo e cabeçalhos) não aparece na tela. Confira o que chega num teste, antes de escrever o seu código. Veja [Segurança, testes e novas tentativas](https://docs.nextags.com.br/webhooks/seguranca-e-testes/). A tela, passo a passo: [Webhooks de saída: avisar outro sistema](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/). ### Requisição externa Num ponto do fluxo, a ação **External API Request** chama o endereço que você escolher, com o método (**GET**, **POST**, **PUT**, **PATCH** ou **DELETE**), os cabeçalhos e o corpo que você montar. A resposta pode: - preencher campos do contato, pelo **Mapeamento de resposta**; - mandar mensagens e executar ações, quando o seu servidor responde no formato `{"messages": [], "actions": []}` (o conteúdo dinâmico). No quadro, a ação tem as saídas **Sucesso** e **Falhado**. Detalhes em [Requisição externa: o fluxo chama o seu sistema](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/). A tela, passo a passo: [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/). ### API O seu sistema chama a API com a chave da conta no cabeçalho `X-ACCESS-TOKEN`. A chamada sai sempre do servidor, nunca do navegador nem do app do celular: lá, a chave ficaria exposta. Comece por [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/) e veja todos os endpoints na [Referência da API](https://docs.nextags.com.br/referencia/). ## Quando usar | Você quer… | Use | |---|---| | Que uma venda, um lead de formulário ou um evento de outro sistema inicie um fluxo | Webhook de entrada | | Saber no seu sistema quando algo acontece na conta, como uma etiqueta aplicada ou uma oportunidade movida | Webhook de saída | | Consultar ou gravar algo no seu sistema no meio da conversa, como o status de um pedido | Requisição externa | | Montar no seu servidor as mensagens que o contato recebe, como a segunda via de um boleto | Requisição externa com conteúdo dinâmico | | Que o seu sistema mande uma mensagem ou um fluxo, ou mova uma oportunidade, quando algo acontece lá | API | | Ligar a NexTags ao Make, ao n8n, ao Zapier ou ao Pabbly | As quatro formas servem. Veja [Usar a API no Make, n8n e Zapier](https://docs.nextags.com.br/guias/make-n8n-zapier/) | Webhook de entrada ou API para criar contatos? O webhook de entrada não pede chave nem código do lado da NexTags: o outro sistema só manda o JSON. A API pede código, mas devolve o ID do contato e deixa o seu sistema decidir, caso a caso, qual fluxo mandar. Veja [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/). Dentro do fluxo, duas ferramentas ajudam a tratar os dados sem sair da NexTags: **Obter dados de JSON**, que tira valores de um JSON guardado num campo ([Obter dados de JSON](https://help.nextags.com.br/tutoriais/fluxos/dados-de-json/)), e **Executar código JavaScript**, para cálculos curtos com os dados do contato ([Executar código JavaScript](https://help.nextags.com.br/tutoriais/fluxos/javascript-no-fluxo/)). O código JavaScript não acessa a internet: para chamar uma API, use a requisição externa. Para avisar o Zapier, o Make ou o Pabbly num ponto do fluxo, há também o grupo **Acionar** ([Acionar o Zapier, o Make e o Pabbly](https://help.nextags.com.br/tutoriais/fluxos/acionar-zapier-make-pabbly/)). ## Boas práticas > **Um webhook de entrada por origem:** > Crie um webhook de entrada para cada sistema ou formato de JSON, como "Compras da Hotmart" e "Leads do site". Cada um tem o seu link, os seus caminhos e o seu fluxo, e um erro num deles não afeta os outros. > **Teste antes de ligar de verdade:** > Use o **Testar Agora** da requisição externa e um endereço de teste, como o Test URL do n8n, para ver o que chega e o que volta. Veja [Segurança, testes e novas tentativas](https://docs.nextags.com.br/webhooks/seguranca-e-testes/). > **Guarde links e chaves fora do código:** > O link do webhook de entrada e a chave de API dão acesso à conta. Guarde os dois em variáveis de ambiente do servidor, como `NEXTAGS_WEBHOOK_URL` e `NEXTAGS_API_KEY`, e nunca num código que vai para o navegador. --- # Webhook de entrada: receber dados de outro sistema > Mande um JSON de outro sistema para o link de um webhook de entrada. O formato, o contato achado pelo telefone ou e-mail, o JSONPath aceito e um teste em cURL. Endereço: https://docs.nextags.com.br/webhooks/webhook-de-entrada/ Tipo: Guia Atualizado em: 26/10/2026 O webhook de entrada é um link da sua conta que recebe dados de outro sistema, como uma loja, uma plataforma de cursos ou o formulário do seu site. A cada envio, a NexTags acha o contato pelo telefone ou pelo e-mail (ou cria um novo), salva os valores recebidos nos campos do contato e inicia o fluxo escolhido. Este guia mostra o lado de quem envia: o formato do JSON, os caminhos aceitos pela tela e um teste com código. A configuração da tela, passo a passo, está em [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/). **Antes de começar** - Um webhook de entrada criado em **Ferramentas** › **Webhooks de entrada**. Veja [Webhooks de entrada: receber dados de outro sistema](https://help.nextags.com.br/tutoriais/ferramentas/webhook-de-entrada/). - Os campos personalizados que vão guardar os dados. Veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/). - O fluxo que roda depois, publicado. Se ele manda WhatsApp para quem não falou com você nas últimas 24 horas, precisa começar com um Modelo de Mensagem aprovado: veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/). - Um exemplo do JSON que o outro sistema vai mandar. ## Passo a passo ### Passo 1: Copie o link e guarde fora do código O link fica no ícone **Obter Link**, no topo do editor do webhook, ou no menu da linha, na lista **Webhooks de entrada**. A tela não mostra o link: o clique copia. Cole o link inteiro, como veio, no outro sistema. Cada webhook tem o seu link. O link não pede chave de API. Quem tem o link consegue criar contatos e iniciar o fluxo, então trate o link como uma senha: nos seus scripts, guarde numa variável de ambiente. **Guardar o link numa variável de ambiente** ```bash # macOS e Linux export NEXTAGS_WEBHOOK_URL="SEU_LINK_DO_WEBHOOK" ``` ```powershell # Windows (PowerShell) $env:NEXTAGS_WEBHOOK_URL = "SEU_LINK_DO_WEBHOOK" ``` Troque `SEU_LINK_DO_WEBHOOK` pelo link copiado. Se o link vazar, veja [como trocar](https://docs.nextags.com.br/webhooks/seguranca-e-testes/). ### Passo 2: Monte o JSON O corpo é um objeto JSON. Ele precisa trazer o telefone ou o e-mail do contato, no caminho que você vai configurar na tela. Basta um dos dois: com ele, a NexTags acha o contato ou cria um novo. - **Telefone**: mande só números, com o código do país e o DDD, como `5511988776655`. Veja [O formato certo do telefone](https://help.nextags.com.br/tutoriais/contatos/formato-do-telefone/). - **E-mail**: o endereço completo, como `ana@exemplo.com.br`. - **Outros dados**: qualquer chave, em qualquer nível. Cada dado que você quiser guardar ganha um caminho na tela. O exemplo deste guia, um pedido pago: ```json { "evento": "pedido_pago", "cliente": { "nome": "Ana Souza", "email": "ana@exemplo.com.br", "telefone": "5511988776655" }, "pedido": { "id": "PED-1001", "total": 249.9, "itens": [ { "produto": "Curso de Confeitaria", "quantidade": 1 } ] }, "dados-extras": { "origem": "site" } } ``` Cole esse exemplo em **Sample JSON**, no editor do webhook, e clique em **Load sample JSON**. O exemplo serve para montar e conferir os caminhos: ele não cria contato nem inicia fluxo. O limite é de 1 MB. ### Passo 3: Escreva os caminhos (JSONPath) Em **Find or create contact**, diga onde estão o telefone e o e-mail do contato. Para o JSON do exemplo: | Campo da tela | JSONPath | Valor no exemplo | |---|---|---| | **Número de telefone** | `$.cliente.telefone` | `5511988776655` | | **Endereço de e-mail** | `$.cliente.email` | `ana@exemplo.com.br` | | **Nome completo** (opcional) | `$.cliente.nome` | `Ana Souza` | Em **Save incoming data**, ligue cada valor a um campo, com **+ Adicionar associação de campo** para cada novo valor: | **Campo Personalizado** | **JSONPath** | Valor no exemplo | |---|---|---| | ID do pedido (texto) | `$.pedido.id` | `PED-1001` | | Valor do pedido (número) | `$.pedido.total` | `249.9` | | Produto (texto) | `$.pedido.itens[0].produto` | `Curso de Confeitaria` | | Origem (texto) | `$["dados-extras"]["origem"]` | `site` | A lista de **Save incoming data** também tem **Endereço de e-mail**, **Número de telefone**, **Nome**, **Sobrenome** e **Nome completo**, além dos campos personalizados. Embaixo de cada caminho, a tela mostra `Result:` com o valor achado no exemplo. A tela aceita só três formas de caminho, sempre começando com `$`, o JSON inteiro: | Forma | Quando usar | Exemplo | |---|---|---| | `.chave` | Chave com letras sem acento, números e `_`, que não começa com número | `$.cliente.email` | | `["chave"]` | Qualquer outra chave: com hífen, espaço, acento ou começando com número. Aspas simples também valem | `$["dados-extras"]["origem"]` | | `[n]` | Um item de lista, contando do zero | `$.pedido.itens[0].produto` | ```jsonpath $.cliente.telefone $["dados-extras"]["origem"] $.pedido.itens[0].produto ``` Filtros, curingas (`*`), dois pontos seguidos (`..`) e índices negativos não funcionam. O caminho precisa chegar num valor (um texto, um número, `true` ou `false`), e não num objeto ou numa lista inteira. Mais exemplos e o tipo de campo certo para cada valor estão em [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos/). ### Passo 4: Escolha o fluxo e salve Em **Após salvar os dados**, escolha o fluxo em **Enviar Fluxo**. Ele começa depois que os campos do contato são salvos, então já pode usar os valores recebidos, como `{{ID do pedido}}` numa mensagem. Clique em **Salvar**, no topo do editor, e confira na lista se o interruptor **Ativo** está ligado. Ao salvar, a tela exige o caminho do telefone ou do e-mail, pelo menos uma associação em **Save incoming data** e o fluxo. Ela confere os caminhos de **Find or create contact**, mas não os de **Save incoming data**: antes de salvar, olhe o `Result:` de cada um. Uma linha sem campo ou sem caminho é descartada ao salvar. ```text Find or create contact: $.cliente.telefone e $.cliente.email Save incoming data: $.pedido.id → ID do pedido Após salvar os dados: Enviar Fluxo → Pedido pago ``` ### Passo 5: Envie um teste Mande o JSON para o link com um POST, com o JSON no corpo e o cabeçalho `Content-Type: application/json`, o formato das plataformas que enviam webhooks. Use o seu próprio telefone ou e-mail no lugar dos dados de exemplo, para receber o fluxo. **Enviar um JSON de teste para o webhook de entrada** ```bash curl -X POST "$NEXTAGS_WEBHOOK_URL" \ -H "Content-Type: application/json" \ -d '{ "evento": "pedido_pago", "cliente": { "nome": "Ana Souza", "email": "ana@exemplo.com.br", "telefone": "5511988776655" }, "pedido": { "id": "PED-1001", "total": 249.9, "itens": [{ "produto": "Curso de Confeitaria", "quantidade": 1 }] }, "dados-extras": { "origem": "site" } }' ``` ```javascript const resposta = await fetch(process.env.NEXTAGS_WEBHOOK_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ evento: 'pedido_pago', cliente: { nome: 'Ana Souza', email: 'ana@exemplo.com.br', telefone: '5511988776655', }, pedido: { id: 'PED-1001', total: 249.9, itens: [{ produto: 'Curso de Confeitaria', quantidade: 1 }], }, 'dados-extras': { origem: 'site' }, }), }); console.log(resposta.status, await resposta.text()); ``` ```python import os import requests resposta = requests.post( os.environ["NEXTAGS_WEBHOOK_URL"], json={ "evento": "pedido_pago", "cliente": { "nome": "Ana Souza", "email": "ana@exemplo.com.br", "telefone": "5511988776655", }, "pedido": { "id": "PED-1001", "total": 249.9, "itens": [{"produto": "Curso de Confeitaria", "quantidade": 1}], }, "dados-extras": {"origem": "site"}, }, timeout=30, ) print(resposta.status_code, resposta.text) ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'evento' => 'pedido_pago', 'cliente' => [ 'nome' => 'Ana Souza', 'email' => 'ana@exemplo.com.br', 'telefone' => '5511988776655', ], 'pedido' => [ 'id' => 'PED-1001', 'total' => 249.9, 'itens' => [['produto' => 'Curso de Confeitaria', 'quantidade' => 1]], ], 'dados-extras' => ['origem' => 'site'], ]), CURLOPT_TIMEOUT => 30, ]); $corpo = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $corpo, PHP_EOL; ``` Os exemplos mostram o código HTTP e o corpo da resposta. O formato da resposta do link não está documentado: anote o que voltou no seu teste. Um código de 200 a 299 indica que o envio foi aceito. ## Pronto: como conferir - O contato aparece em **Contatos**, com os campos preenchidos. Pela API, procure pelo e-mail com [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/). - O fluxo chegou ao telefone do teste. No painel do contato, na **Caixa de Entrada**, ele aparece em **Histórico** › **Fluxos/Passos Executados**. - Um segundo envio com o mesmo telefone ou e-mail atualiza o mesmo contato, sem criar outro. ## Se não funcionou ### O teste devolveu um código de 400 em diante Confira se o link está inteiro, se o JSON é válido e se o cabeçalho `Content-Type: application/json` foi enviado. Anote o código e o corpo da resposta: eles ajudam o suporte a achar a causa. ### O envio foi aceito, mas nada aconteceu Confira se o webhook está **Ativo**, se o link é o deste webhook e se o caminho do telefone ou do e-mail acha o valor no JSON que você mandou. Confira também se o fluxo está publicado. Veja [Meu webhook de entrada não recebe os dados](https://help.nextags.com.br/perguntas/integracoes/webhook-nao-recebe/). ### O contato chegou, mas um campo ficou vazio O caminho daquele campo não achou o valor. Cole em **Sample JSON** um envio real, clique em **Load sample JSON** e confira o `Result:` de cada caminho em **Save incoming data**. Confira também o tipo do campo: um valor com letras não cabe num campo de número. ### O caminho mostra um aviso em inglês `Start the path with $.` pede o `$` no começo. `Use .key, ["key"], or [0]. Filters and wildcards are not supported.` quer dizer que a forma do caminho não é aceita. `Select a value rather than an object or array.` pede um valor, e não um grupo de dados. `No value found in sample data.` diz que o exemplo não tem esse caminho: se o dado é opcional, dá para salvar assim. A lista completa está em [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos/). ### O exemplo não carrega `Use sample JSON smaller than 1 MB.` pede um exemplo menor. `Sample JSON is too large or deeply nested. Use a smaller sample.` aparece com mais de 10 mil itens ou mais de 60 níveis: corte as listas longas do exemplo, deixando só o primeiro item. ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Vou mandar dados do meu sistema para um webhook de entrada da NexTags. Leia este guia: https://docs.nextags.com.br/webhooks/webhook-de-entrada.md Este é um exemplo do JSON que o meu sistema envia, sem dados reais: [cole aqui]. Me diga os caminhos (JSONPath só com .chave, ["chave"] e [0]) do telefone, do e-mail e do nome, os campos personalizados que devo criar, com o tipo de cada um, e escreva em [sua linguagem] o código que manda esse JSON por POST para o link guardado na variável de ambiente NEXTAGS_WEBHOOK_URL. ``` --- # Requisição externa: o fluxo chama o seu sistema > Prepare o seu servidor para a requisição externa do fluxo: o que chega, o cabeçalho X-USER-ID, o que responder para guardar dados ou mandar mensagens e ações. Endereço: https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/ Tipo: Guia Atualizado em: 26/10/2026 Na ação **External API Request**, o fluxo chama um endereço seu quando o contato chega à etapa. O seu servidor recebe a chamada e responde de um destes jeitos: com um JSON comum, que a NexTags guarda em campos do contato pelo **Mapeamento de resposta**, ou com conteúdo dinâmico, que a NexTags transforma em mensagens para o contato e em ações, como aplicar uma etiqueta. Este guia mostra o lado do seu servidor, com um exemplo que consulta um pedido e responde ao contato. A configuração da ação na tela, passo a passo, está em [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/). **Antes de começar** - Um endereço `https://` do seu servidor que aceite a chamada. Para só ver o que chega, comece com um endereço de teste, como o Test URL do n8n: veja [Segurança, testes e novas tentativas](https://docs.nextags.com.br/webhooks/seguranca-e-testes/). - Uma etapa **Ações** no fluxo, com a ação **External API Request**. Veja [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/). - Para responder com mensagens e ações, o formato de [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). ## Passo a passo ### Passo 1: Configure a chamada no fluxo Na janela **External Request**, escolha o método em **Request Type** (**GET**, **POST**, **PUT**, **PATCH** ou **DELETE**) e o endereço em **Request URL**. O endereço aceita variáveis do contato: digite `{` para escolher o campo. Na aba **Cabeçalhos**, um cabeçalho por linha, com **Adicionar** para mais um. Na aba **Corpo**, o formato: | Na aba **Corpo** | O que o seu servidor recebe | |---|---| | **Todos os dados do contato** | Os dados do contato num formato pronto. Marque **Incluir tags do contato** e **Incluir campos personalizados do contato** para juntar as etiquetas e os campos. A tela remete à documentação da API; o formato exato, confira em **Corpo da solicitação**, no **Testar Agora**. | | **JSON** | O JSON que você escrever, com as variáveis `{{campo}}` trocadas pelos valores do contato. Um JSON inválido faz a tela avisar "O JSON no corpo da solicitação não é válido". | | **Form-encoded** | Pares de nome e valor, como um formulário. | Com **GET**, a aba **Corpo** fica desligada. O corpo em **JSON** deste guia manda o código do pedido guardado num campo do contato. Os campos de texto vão entre aspas: ```json { "contato_id": "{{user_id}}", "nome": "{{full_name}}", "telefone": "{{phone}}", "pedido": "{{ID do pedido}}" } ``` No seu servidor chegam o método, os cabeçalhos que você montou e o corpo. A NexTags manda também o cabeçalho `X-USER-ID`, com o ID do contato, em toda requisição. Use esse ID para saber de que contato é a chamada ou para consultar o contato pela API, em [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/). Para o seu servidor saber que a chamada veio do seu fluxo, crie um cabeçalho com um segredo seu, como `X-Segredo`, e confira no servidor. Para não repetir o segredo em cada fluxo, guarde num campo do bot: veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/). ### Passo 2: Decida o que responder O seu servidor responde de um destes jeitos. **JSON comum, para guardar em campos.** Na aba **Mapeamento de resposta**, cada linha liga um caminho (**JSONPath**) a um campo, em **Salvar em um campo personalizado**. Para esta resposta: ```json { "pedido": { "id": "PED-1001", "status": "enviado", "rastreio": "https://seusistema.exemplo.com.br/rastreio/PED-1001" } } ``` | Valor | JSONPath | Campo | |---|---|---| | A situação do pedido | `$.pedido.status` | Status do pedido (texto) | | O link de acompanhamento | `$.pedido.rastreio` | Link de rastreio (texto) | Três nomes especiais, escritos no lugar do JSONPath, guardam a resposta inteira: | No lugar do JSONPath | O que guarda | |---|---| | `http_status_code` | O código HTTP da resposta, como `200` ou `404`. Guarde num campo de número e use numa condição. | | `http_response_body` | O corpo inteiro da resposta, como texto. Depois, dá para tirar valores dele com **Obter dados de JSON**. | | `http_download_` | Baixa a resposta como um arquivo com essa extensão, como `http_download_mp3` para um áudio. | **Conteúdo dinâmico, para mandar mensagens e executar ações.** Responda com `messages` (as mensagens que o contato recebe, na ordem) e `actions` (as ações, na ordem). A NexTags converte as mensagens para o canal do contato. O formato completo, com botões, imagens, cartões e as ações, está em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). ```json { "messages": [ { "message": { "text": "Seu pedido PED-1001 está a caminho." } }, { "message": { "text": "Acompanhe aqui: https://seusistema.exemplo.com.br/rastreio/PED-1001" } } ], "actions": [ { "action": "add_tag", "tag_name": "pedido-consultado" }, { "action": "set_field_value", "field_name": "Status do pedido", "value": "enviado" } ] } ``` O conteúdo dinâmico só funciona quando o endereço é seu: é o seu servidor que monta a resposta nesse formato. Para a API de outra empresa, use o **Mapeamento de resposta** e mostre os campos numa mensagem do fluxo. ### Passo 3: Escreva o servidor Um servidor mínimo para o exemplo: confere o segredo do cabeçalho `X-Segredo`, lê o corpo em JSON e o `X-USER-ID`, e responde com conteúdo dinâmico. O segredo fica na variável de ambiente `NEXTAGS_SEGREDO`, com o mesmo valor do cabeçalho configurado na requisição. Num sistema de verdade, a situação do pedido viria do seu banco de dados. **Servidor que responde com mensagens e ações** ```javascript // servidor.mjs (Node 18 ou mais novo): node servidor.mjs import http from 'node:http'; import { timingSafeEqual } from 'node:crypto'; const SEGREDO = process.env.NEXTAGS_SEGREDO; function igual(a, b) { const x = Buffer.from(String(a ?? '')); const y = Buffer.from(String(b ?? '')); return x.length === y.length && timingSafeEqual(x, y); } http.createServer(async (req, res) => { if (req.method !== 'POST' || req.url !== '/nextags/pedido') { res.writeHead(404).end(); return; } if (!SEGREDO || !igual(req.headers['x-segredo'], SEGREDO)) { res.writeHead(401).end(); return; } let corpo = ''; for await (const parte of req) corpo += parte; let dados; try { dados = JSON.parse(corpo || '{}'); } catch { res.writeHead(400).end(); return; } const contato = req.headers['x-user-id']; // o ID do contato na NexTags console.log(`Contato ${contato} consultou o pedido ${dados.pedido}`); const resposta = { messages: [ { message: { text: `Seu pedido ${dados.pedido} está a caminho.` } }, ], actions: [ { action: 'add_tag', tag_name: 'pedido-consultado' }, { action: 'set_field_value', field_name: 'Status do pedido', value: 'enviado' }, ], }; res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(resposta)); }).listen(3000); ``` ```python # servidor.py (Flask): flask --app servidor run --port 3000 import hmac import os from flask import Flask, jsonify, request app = Flask(__name__) SEGREDO = os.environ.get("NEXTAGS_SEGREDO", "") @app.post("/nextags/pedido") def pedido(): recebido = request.headers.get("X-Segredo", "") if not SEGREDO or not hmac.compare_digest(recebido.encode(), SEGREDO.encode()): return "", 401 dados = request.get_json(silent=True) or {} contato = request.headers.get("X-USER-ID") # o ID do contato na NexTags app.logger.info("Contato %s consultou o pedido %s", contato, dados.get("pedido")) return jsonify({ "messages": [ {"message": {"text": f"Seu pedido {dados.get('pedido')} está a caminho."}}, ], "actions": [ {"action": "add_tag", "tag_name": "pedido-consultado"}, {"action": "set_field_value", "field_name": "Status do pedido", "value": "enviado"}, ], }) ``` ```php [ ['message' => ['text' => "Seu pedido $pedido está a caminho."]], ], 'actions' => [ ['action' => 'add_tag', 'tag_name' => 'pedido-consultado'], ['action' => 'set_field_value', 'field_name' => 'Status do pedido', 'value' => 'enviado'], ], ], JSON_UNESCAPED_UNICODE); ``` Publique o servidor num endereço `https://`, como `https://seusistema.exemplo.com.br/nextags/pedido`, e use esse endereço em **Request URL**. ### Passo 4: Teste o servidor antes de ligar o fluxo Simule a chamada da NexTags com o cURL, no próprio servidor. A resposta deve ser o conteúdo dinâmico do passo anterior. ```bash curl -X POST "http://127.0.0.1:3000/nextags/pedido" \ -H "Content-Type: application/json" \ -H "X-Segredo: $NEXTAGS_SEGREDO" \ -H "X-USER-ID: 123456789" \ -d '{"contato_id": "123456789", "nome": "Ana Souza", "telefone": "5511988776655", "pedido": "PED-1001"}' ``` Sem o cabeçalho `X-Segredo`, ou com outro valor, o servidor responde `401`. ### Passo 5: Teste no fluxo e ligue as saídas Na janela da requisição, abra a aba **Testar Agora** e clique no botão **Testar Agora**. Escolha o canal em **Selecionar canal** e clique em **Continuar**. O resultado mostra: ```text Código do estado 200 Corpo da resposta o JSON que o seu servidor devolveu Cabeçalhos da resposta os cabeçalhos que o seu servidor devolveu Cabeçalhos da solicitação os cabeçalhos que a NexTags mandou, com os que você montou Corpo da solicitação o corpo que a NexTags mandou, já com os valores do contato ``` Confira em **Cabeçalhos da solicitação** e **Corpo da solicitação** o que o seu servidor recebe de verdade, principalmente com **Todos os dados do contato**. Clique no nome de cada parte para abrir. Clique em **Salvar**. No quadro, ligue a saída **Sucesso** à próxima etapa e a saída **Falhado** a um caminho de reserva, como uma mensagem de "tente mais tarde" ou a passagem para a equipe. Depois, publique o fluxo. ## Pronto: como conferir - O **Testar Agora** mostra o **Código do estado** `200` e o seu JSON em **Corpo da resposta**. - Clique em **Testar**, no topo do editor, e passe pela etapa no seu celular: as mensagens do conteúdo dinâmico chegam, e a etiqueta e o campo aparecem no seu contato. Veja [Testar o fluxo](https://help.nextags.com.br/tutoriais/fluxos/testar-fluxo/). - O log do seu servidor mostra o `X-USER-ID`: é o ID do seu contato na NexTags. ## Se não funcionou ### O teste mostra o código 401 O segredo não bateu. Confira o nome do cabeçalho na aba **Cabeçalhos** (`X-Segredo`, no exemplo) e o valor, sem espaços, e a variável `NEXTAGS_SEGREDO` no servidor. ### O teste mostra "Não foi possível concluir esta operação." O teste não chegou ao fim. Confira se o endereço em **Request URL** está certo, começa com `https://` e responde fora da sua rede. Veja [Erros de requisição externa, webhook e planilha](https://help.nextags.com.br/tutoriais/erros/erros-de-requisicao-externa/). ### O código é 200, mas as mensagens não chegaram Confira em **Corpo da resposta** se o JSON tem a lista `messages` e se cada item tem um objeto `message`, como em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). O servidor também deve responder com o cabeçalho `Content-Type: application/json`. ### O campo do Mapeamento de resposta ficou vazio O JSONPath não bate com a resposta. Abra o **Testar Agora**, copie o **Corpo da resposta** e confira o caminho. Para ver tudo o que voltou, guarde `http_response_body` num campo de texto. Veja [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos/). ### O contato foi pela saída Falhado Veja o código e a resposta no **Testar Agora** e confira o log do seu servidor: a chamada chegou? O servidor respondeu rápido e com um código de 200 a 299? As falhas dos fluxos ficam no **Registro de Erros**: veja [Registro de Erros: ler e resolver](https://help.nextags.com.br/tutoriais/fluxos/registro-de-erros/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Vou receber a requisição externa de um fluxo da NexTags no meu servidor. Leia este guia: https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo.md e o formato das mensagens: https://docs.nextags.com.br/comecar/mensagens-e-acoes.md Minha linguagem e framework: [ex.: Node com Express, Python com FastAPI, PHP com Laravel]. O que o servidor deve fazer: [descreva, por exemplo: consultar o pedido no meu banco e responder com a situação e um botão]. Escreva o servidor completo, que confere o segredo do cabeçalho X-Segredo (guardado numa variável de ambiente), lê o X-USER-ID e responde em JSON com messages e actions. Diga também o que configurar na External API Request: Request Type, Request URL, Cabeçalhos e Corpo. ``` --- # Mapear o corpo recebido para campos do contato > JSONPath na prática: o caminho de cada valor num JSON de exemplo, o tipo de campo certo e o que muda entre o webhook de entrada e o fluxo. Endereço: https://docs.nextags.com.br/webhooks/mapear-campos/ Tipo: Guia Atualizado em: 26/10/2026 Mapear é ligar cada valor de um JSON a um campo do contato, com um caminho JSONPath. Três lugares da NexTags fazem isso, cada um com as suas regras: | Onde | De onde vem o JSON | Onde fica o caminho | |---|---|---| | Webhook de entrada | O corpo que o outro sistema manda | **Find or create contact** e **Save incoming data** | | Requisição externa | A resposta da sua API | Aba **Mapeamento de resposta** | | **Obter dados de JSON** | Um campo de texto do contato que guarda um JSON | **Salve a resposta em um campo personalizado.** | Este guia usa um JSON de exemplo para mostrar o caminho de cada valor, o tipo de campo certo e o que muda em cada lugar. **Antes de começar** - Um exemplo real do JSON. Veja no passo 1 onde conseguir. - Os campos personalizados que vão receber os valores. Veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/). ## Passo a passo ### Passo 1: Pegue um exemplo real do JSON Monte os caminhos sobre um JSON de verdade, e não sobre a documentação de memória: um nome de chave diferente basta para o campo ficar vazio. - **Webhook de entrada**: o histórico de envios da outra plataforma, como o **Payload** da Hotmart ou o **Ver logs** da Kiwify, ou um envio de teste para o Test URL do n8n. Veja [Exemplos de plataformas](https://docs.nextags.com.br/webhooks/exemplos-de-plataformas/). - **Requisição externa**: o **Corpo da resposta**, no **Testar Agora** da ação. - **Obter dados de JSON**: o conteúdo do campo. Para ver, mostre o campo numa mensagem de teste. O exemplo deste guia, um pedido: ```json { "cliente": { "nome": "Ana Souza", "email": "ana@exemplo.com.br", "telefone": "5511988776655", "vip": true }, "pedido": { "id": "PED-1001", "numero": "000123", "total": 249.9, "pago_em": 1793030400, "itens": [ { "produto": "Curso de Confeitaria", "preco": 199.9 }, { "produto": "Apostila impressa", "preco": 50 } ] }, "utm": { "utm_source": "instagram" }, "dados-do-cupom": { "código": "BEMVINDO10" } } ``` ### Passo 2: Ache o caminho de cada valor O caminho começa com `$`, o JSON inteiro, e desce um nível a cada ponto. Item de lista vai entre colchetes, contando do zero. Chave com hífen, espaço ou acento vai entre aspas e colchetes. | Valor que você quer | JSONPath | Resultado | |---|---|---| | E-mail do cliente | `$.cliente.email` | `ana@exemplo.com.br` | | Telefone do cliente | `$.cliente.telefone` | `5511988776655` | | Cliente VIP | `$.cliente.vip` | `true` | | ID do pedido | `$.pedido.id` | `PED-1001` | | Número do pedido | `$.pedido.numero` | `000123` | | Total do pedido | `$.pedido.total` | `249.9` | | Data do pagamento | `$.pedido.pago_em` | `1793030400` | | Primeiro produto | `$.pedido.itens[0].produto` | `Curso de Confeitaria` | | Preço do segundo produto | `$.pedido.itens[1].preco` | `50` | | Origem da campanha | `$.utm.utm_source` | `instagram` | | Código do cupom | `$["dados-do-cupom"]["código"]` | `BEMVINDO10` | ```jsonpath $.cliente.email $.pedido.itens[0].produto $["dados-do-cupom"]["código"] ``` O caminho precisa chegar num valor: um texto, um número, `true` ou `false`. `$.pedido` e `$.pedido.itens` apontam para um grupo de dados, e não para um valor. Para listas de tamanho que muda, só dá para pegar posições fixas, como `[0]` e `[1]`: se precisar de todos os itens num texto só, monte esse texto no sistema que manda o JSON. ### Passo 3: Escolha o tipo de campo O tipo do campo personalizado decide o que dá para fazer com o valor depois, nas condições e nas mensagens. | Valor | Tipo de campo | Por quê | |---|---|---| | Valores e quantidades, como `249.9` | Número | Dá para comparar nas condições, como "maior que". Mande o número com ponto, sem `R$`. | | IDs e códigos, como `PED-1001` e `000123` | Texto | Um ID não entra em contas e pode ter letras e zeros à esquerda. Guarde como texto, mesmo quando só tem números. | | Datas, como `1793030400` | Data, ou Data e hora | Os campos de data guardam a data em Unix timestamp, em segundos. Uma data em outro formato, como `2026-10-26T13:00:00-03:00`, guarde num campo de texto. | | Verdadeiro ou falso, como `true` | Verdadeiro/Falso | O campo guarda `0` ou `1`. Confira no teste como o `true` e o `false` do seu JSON ficam. | | Textos grandes, como uma descrição ou o JSON inteiro | Texto longo | É o tipo para textos grandes. **Obter dados de JSON** lê o JSON de campos de texto e de texto longo. | Na API, o valor de um campo vem como texto quando o tipo é Texto (`0`) e como número nos outros tipos, como neste campo de número: ```json { "id": 3001, "name": "Valor do pedido", "type": 1, "value": 249.9 } ``` Os tipos e as variáveis estão em [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/). ### Passo 4: Mapeie no webhook de entrada A tela do webhook de entrada aceita só três formas: `.chave`, `["chave"]` (ou `['chave']`) e `[n]`. Use `.chave` só para chaves com letras sem acento, números e `_`, que não comecem com número; qualquer outra chave vai entre aspas e colchetes. ```text Aceitos Recusados $.cliente.email $.pedido.itens[*].produto (curinga) $["dados-do-cupom"]["código"] $..email (dois pontos seguidos) $.pedido.itens[0].produto $.pedido.itens[-1].produto (índice negativo) $['utm']['utm_source'] $.dados-do-cupom.código (hífen e acento fora das aspas) ``` Os avisos que a tela mostra, em inglês: | Aviso | O que quer dizer | |---|---| | `Start the path with $.` | O caminho não começa com `$`. | | `Use .key, ["key"], or [0]. Filters and wildcards are not supported.` | Uma parte do caminho não está numa das três formas aceitas. | | `Close the quoted key with ].` | Falta fechar as aspas ou o colchete de uma chave. | | `Select a value rather than an object or array.` | O caminho chega num grupo de dados (objeto ou lista), e não num valor. | | `No value found in sample data.` | O exemplo não tem esse caminho. Se o dado é opcional e só falta no exemplo, dá para salvar assim. | | `Load sample JSON to preview this path.` | Ainda não há exemplo carregado: cole em **Sample JSON** e clique em **Load sample JSON**. | | `Array index is too large.` | O número entre colchetes é grande demais. | Ao salvar, os avisos de **Find or create contact** aparecem com o nome do campo na frente, como `Número de telefone: Start the path with $.`. Os caminhos de **Save incoming data** não são conferidos ao salvar: olhe o `Result:` de cada um antes. ### Passo 5: Mapeie no fluxo Na requisição externa (**Mapeamento de resposta**) e em **Obter dados de JSON**, escreva o caminho do mesmo jeito: `$`, a chave depois de cada ponto e `[n]` para listas. Ao lado de **JSONPath**, na requisição externa, o ícone ⓘ abre um site que ajuda a achar o caminho num JSON colado. Em **Obter dados de JSON**, escolha em **Dados JSON** o campo de texto que guarda o JSON e, embaixo, uma linha por valor, com o caminho e o campo que recebe (até 100 linhas). A ação tem duas saídas: - **Sucesso**: pelo menos um campo foi preenchido. - **Falhado**: o JSON é inválido ou nenhum campo foi preenchido. ```text Dados JSON: o campo Resposta do pedido $.pedido.id → ID do pedido $.pedido.total → Valor do pedido $.cliente.vip → Cliente VIP ``` > **Um caminho errado apaga o valor do campo:** > Em **Obter dados de JSON**, se o caminho de uma linha está errado, o valor que o campo tinha é apagado. Com vários campos na mesma ação, o contato pode sair por **Sucesso** com um campo perdido. Antes de usar o valor, confira numa etapa **Condição** se o campo tem valor. Veja [Etapa Condição](https://help.nextags.com.br/tutoriais/fluxos/condicoes/). O passo a passo de tela está em [Obter dados de JSON](https://help.nextags.com.br/tutoriais/fluxos/dados-de-json/) e em [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/). ## Pronto: como conferir - No webhook de entrada, cada caminho mostra `Result:` com o valor esperado, depois de **Load sample JSON**. - Na requisição externa, o **Testar Agora** mostra o **Corpo da resposta**, e o caminho de cada linha bate com ele. - Depois de um teste de verdade, os campos aparecem preenchidos no painel do contato, na **Caixa de Entrada**, com o tipo certo. ## Se não funcionou ### O campo ficou vazio O caminho não achou o valor. Compare letra por letra com o JSON real, com maiúsculas e minúsculas, e confira o nível de cada chave. Um envio real pode não trazer um dado opcional. ### O campo perdeu o valor que tinha Em **Obter dados de JSON**, um caminho errado apaga o valor anterior. Corrija o caminho e, nos campos importantes, confira o valor com uma condição antes de usar. ### O valor ficou diferente do JSON Confira o tipo do campo: um texto como `PED-1001` não cabe num campo de número, e um valor com `R$` ou vírgula não é um número. Para datas, use um campo de data com Unix timestamp ou um campo de texto. ### A tela pede um valor, e não um objeto ou uma lista O caminho para num grupo de dados. Desça até o valor, como `$.pedido.itens[0].produto` em vez de `$.pedido.itens`. ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Preciso mapear um JSON para campos de contato da NexTags. Leia este guia: https://docs.nextags.com.br/webhooks/mapear-campos.md Onde vou mapear: [webhook de entrada / Mapeamento de resposta da requisição externa / Obter dados de JSON]. Este é o JSON, sem dados reais: [cole aqui]. Os dados que quero guardar: [liste]. Para cada um, me dê o JSONPath (no webhook de entrada, só com .chave, ["chave"] e [0]), o nome do campo personalizado e o tipo certo (Texto, Número, Data, Data e hora, Verdadeiro/Falso ou Texto longo). ``` --- # Segurança, testes e novas tentativas > Como proteger o link do webhook de entrada, o endereço de saída e a requisição externa, como testar sem sistema pronto, tratar repetições e achar os erros. Endereço: https://docs.nextags.com.br/webhooks/seguranca-e-testes/ Tipo: Referência Atualizado em: 26/10/2026 Cada forma de troca de dados tem um ponto que precisa de cuidado: o link do webhook de entrada, o endereço que recebe o webhook de saída, o endpoint da requisição externa e a chave da API. Esta página reúne o que fazer em cada caso, como testar antes de ter o sistema pronto, como tratar o mesmo evento chegando duas vezes e onde ver os erros. ## O que proteger | Recurso | O que dá acesso | O que fazer | |---|---|---| | Webhook de entrada | O link copiado em **Obter Link** | Guardar fora do código e longe do navegador. Se vazar, trocar. | | Webhook de saída | O endereço em **Notificar este URL** | Usar `https://` e um caminho difícil de adivinhar. | | Requisição externa | O endereço em **Request URL** | Mandar um segredo seu num cabeçalho e conferir no servidor. | | API | A chave de API da conta | Guardar em variável de ambiente e chamar só do servidor. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). | ## O link do webhook de entrada é um segredo O link não pede chave: quem tem o link cria contatos com qualquer telefone ou e-mail e inicia o fluxo do webhook. Se o fluxo manda mensagens, o link nas mãos erradas faz a sua conta mandar mensagens para quem não pediu. - Não ponha o link no HTML nem no JavaScript do site: quem abre a página vê o código. Mande os dados do formulário para o seu servidor, e o servidor manda para a NexTags. Veja o exemplo em [Exemplos: Hotmart, Kiwify, Shopify e formulários](https://docs.nextags.com.br/webhooks/exemplos-de-plataformas/). - Guarde o link numa variável de ambiente, como `NEXTAGS_WEBHOOK_URL`, e não em repositórios, prints ou chamados abertos. - A tela do webhook de entrada não tem campo para conferir a assinatura ou o token de quem envia, como o cabeçalho `X-HOTMART-HOTTOK` da Hotmart ou o parâmetro `signature` da Kiwify. Quem precisa dessa conferência recebe o webhook num servidor próprio, confere a assinatura e repassa os dados para a NexTags. ### Se o link vazar O menu do webhook de entrada tem só **Obter Link**, **Renomear** e **Excluir**: não há um botão para gerar outro link para o mesmo webhook. Para trocar: 1. Em **Ferramentas** › **Webhooks de entrada**, clique em **Adicionar Novo** e crie outro webhook. Ele vem com um link novo. 2. Refaça a configuração: **Sample JSON**, os caminhos, os campos e o fluxo. 3. Troque o link no sistema que envia os dados e faça um envio de teste. 4. No webhook antigo, desligue o interruptor **Ativo** e depois clique em **Excluir**. ## Webhook de saída - O endereço em **Notificar este URL** precisa começar com `https://`. Com `http://`, a tela mostra "The URL must start with https". Sem nada no começo, o app completa com `https://` ao salvar. - O formato do aviso (método, corpo, cabeçalhos e se há assinatura) não aparece na tela. Antes de escrever o código, aponte o webhook para um endereço de teste e veja o que chega (veja [Como testar](https://docs.nextags.com.br/webhooks/seguranca-e-testes/#como-testar-sem-um-sistema-pronto)). - Use no endereço um caminho difícil de adivinhar, como `https://seusistema.exemplo.com.br/webhooks/nextags/c8f2e1d94b7a`, e recuse no seu servidor os outros caminhos. - Trate o aviso como um sinal. Se a decisão depende de dados confiáveis, como liberar um acesso, consulte o contato pela API antes de agir. Veja [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/). ## Requisição externa - Crie na aba **Cabeçalhos** um cabeçalho com um segredo seu, como `X-Segredo`, e confira o valor no servidor. Sem o segredo certo, responda `401`. Para não espalhar o segredo pelos fluxos, guarde num campo do bot: veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/). - A NexTags manda o cabeçalho `X-USER-ID`, com o ID do contato, em toda requisição. Use para saber de que contato é a chamada, mas não como prova de origem: qualquer um consegue mandar esse cabeçalho. A prova é o seu segredo. - Use um endereço `https://`, para o segredo e os dados do contato não viajarem abertos. - O campo do sistema `{{page_api_key}}` traz a chave de API da conta. Mande essa chave só para a API da NexTags ou para sistemas seus, nunca para sistemas de terceiros. Veja [Campos do sistema](https://help.nextags.com.br/tutoriais/fluxos/campos-do-sistema/). A conferência do segredo, com comparação em tempo constante: **Conferir o segredo do cabeçalho** ```javascript import { timingSafeEqual } from 'node:crypto'; // true quando o cabeçalho X-Segredo tem o valor da variável NEXTAGS_SEGREDO export function segredoConfere(req) { const esperado = Buffer.from(process.env.NEXTAGS_SEGREDO ?? ''); const recebido = Buffer.from(String(req.headers['x-segredo'] ?? '')); return esperado.length > 0 && esperado.length === recebido.length && timingSafeEqual(esperado, recebido); } ``` ```python import hmac import os def segredo_confere(cabecalhos): """True quando o cabeçalho X-Segredo tem o valor da variável NEXTAGS_SEGREDO.""" esperado = os.environ.get("NEXTAGS_SEGREDO", "").encode() recebido = cabecalhos.get("X-Segredo", "").encode() return bool(esperado) and hmac.compare_digest(esperado, recebido) ``` ```php O que a Hotmart, a Kiwify e a Shopify mandam por webhook e os caminhos de telefone, e-mail, nome, produto e status. E um formulário do site sem expor o link. Endereço: https://docs.nextags.com.br/webhooks/exemplos-de-plataformas/ Tipo: Guia Atualizado em: 26/10/2026 Hotmart, Kiwify e Shopify avisam cada venda por webhook. O caminho é o mesmo nas três: o webhook da plataforma manda os dados para um webhook de entrada da NexTags, que acha ou cria o contato e inicia o fluxo. Para cada plataforma, este guia mostra um trecho do JSON da documentação oficial e o caminho (JSONPath) de cada dado. No fim, um formulário do seu site que manda os dados pelo seu servidor, sem expor o link. **Antes de começar** - Um webhook de entrada para cada plataforma, com o link copiado em **Obter Link**. Veja [Webhook de entrada: receber dados de outro sistema](https://docs.nextags.com.br/webhooks/webhook-de-entrada/). - O fluxo de cada aviso, publicado. Para quem não falou com você nas últimas 24 horas, um fluxo de WhatsApp começa com um Modelo de Mensagem aprovado. Veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/). - Um envio de teste de cada plataforma, para conferir os caminhos com dados reais. ## Passo a passo ### Passo 1: Hotmart: compras e outros eventos Na Hotmart, em **Ferramentas** › **Ver todas** › **Webhook (API e notificações)**, clique em **+ Cadastrar Webhook**, marque os eventos e cole o link da NexTags como URL. Os dados da venda vêm em `data`, e o nome do evento, em `event`. Trecho do exemplo oficial da Hotmart (evento de compra, versão 2.0.0), encurtado: ```json { "id": "1234567890123456789", "creation_date": 12345678, "event": "PURCHASE_APPROVED", "version": "2.0.0", "data": { "product": { "id": 213344, "name": "Product Name" }, "buyer": { "email": "buyer@email.com", "name": "Buyer Name", "first_name": "Buyer", "last_name": "Name", "checkout_phone": "999999999", "checkout_phone_code": "31" }, "purchase": { "status": "STARTED", "transaction": "HP02316330308193" } } } ``` | Dado | JSONPath | No exemplo | |---|---|---| | Telefone | `$.data.buyer.checkout_phone` | `999999999` | | DDD (só compradores do Brasil) | `$.data.buyer.checkout_phone_code` | `31` | | E-mail | `$.data.buyer.email` | `buyer@email.com` | | Nome | `$.data.buyer.name` | `Buyer Name` | | Produto | `$.data.product.name` | `Product Name` | | Status da compra | `$.data.purchase.status` | `STARTED` | | Evento | `$.event` | `PURCHASE_APPROVED` | | Código da transação | `$.data.purchase.transaction` | `HP02316330308193` | No exemplo oficial, o telefone vem sem o código do país e sem o DDD, que chega à parte em `checkout_phone_code`. A Hotmart diz que, nas vendas para fora do Brasil, o código do país vem junto ao telefone. Como a tela do webhook de entrada usa um caminho só para o telefone, confira um envio real no **Histórico** da Hotmart. Se o número vier incompleto, identifique o contato pelo e-mail e guarde o DDD e o telefone em campos, ou receba o webhook num servidor seu, monte o número completo (`55` + DDD + número) e repasse para a NexTags, como no formulário do último passo. A Hotmart manda em todas as requisições o cabeçalho `X-HOTMART-HOTTOK`, que identifica a sua conta. A tela do webhook de entrada não tem onde conferir esse cabeçalho: para conferir, receba o webhook num servidor seu. Fonte: [Eventos de pedidos do Webhook da Hotmart](https://developers.hotmart.com/docs/pt-BR/2.0.0/webhook/purchase-webhook/). A configuração na NexTags, passo a passo: [Hotmart](https://help.nextags.com.br/integracoes/hotmart/). ### Passo 2: Kiwify: compra aprovada, Pix e boleto Na Kiwify, em **Apps** › **Webhooks**, crie um webhook, cole o link da NexTags como URL, escolha os produtos e os eventos. Cada evento chega por POST com o JSON no corpo. A Kiwify acrescenta ao link o parâmetro `signature`, uma assinatura do corpo; a tela do webhook de entrada não tem onde conferir, mas um servidor seu pode. O exemplo oficial da Kiwify, que omite os dados do cliente: ```json { "order_id": "9b1c2d3e-0000-4000-8000-000000000001", "order_status": "paid", "webhook_event_type": "order_approved" } ``` | Dado | JSONPath | |---|---| | Telefone, e-mail e nome | No bloco `Customer`. Os exemplos oficiais omitem esse bloco: confira os nomes num **Testar Webhook**, em **Ver logs**, e escolha os caminhos com a lupa do editor. | | Produto | Confira no envio real, em **Ver logs**. | | Status do pedido | `$.order_status` | | Evento | `$.webhook_event_type` | | ID do pedido | `$.order_id` | O gatilho que você marca na Kiwify e o valor que chega em `webhook_event_type` nem sempre têm o mesmo nome: | Gatilho na Kiwify | `webhook_event_type` | `order_status` | |---|---|---| | `compra_aprovada` | `order_approved` | `paid` | | `pix_gerado` | `pix_created` | `waiting_payment` | | `boleto_gerado` | `billet_created` | `waiting_payment` | | `compra_recusada` | `order_rejected` | `refused` | | `compra_reembolsada` | `order_refunded` | `refunded` | | `chargeback` | `chargeback` | `chargedback` | O carrinho abandonado chega em outro formato, sem `webhook_event_type` nem `order_status`: use um webhook de entrada só para ele. A Kiwify espera uma resposta de 200 a 299 em até 40 segundos, tenta de novo quando falha e pode mandar o mesmo evento mais de uma vez. Fonte: [Receber e validar webhooks, da Kiwify](https://docs.kiwify.com.br/api-reference/webhooks/receiving). A configuração na NexTags, passo a passo: [Kiwify](https://help.nextags.com.br/integracoes/kiwify/). ### Passo 3: Shopify: pedidos No admin da Shopify, em **Configurações** › **Notificações** › **Webhooks**, clique em **Criar webhook**. Em **Evento**, escolha o aviso, como **Criação de pedido**; deixe o **Formato** em **JSON** e cole o link da NexTags em **URL**. O evento não muda depois: crie um webhook para cada aviso, como **Pagamento de pedido** e **Cancelamento de pedido**. Trecho do exemplo oficial do tópico `orders/create`, encurtado: ```json { "id": 820982911946154508, "email": "jon@example.com", "phone": null, "name": "#9999", "order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg", "financial_status": "voided", "fulfillment_status": null, "total_price": "404.95", "billing_address": { "name": "Steve Shipper", "phone": "555-555-SHIP" }, "customer": { "first_name": "John", "last_name": "Smith", "email": "john@example.com", "phone": null }, "line_items": [ { "title": "Aviator sunglasses", "quantity": 1, "price": "89.99" } ] } ``` | Dado | JSONPath | No exemplo | |---|---|---| | Telefone | `$.billing_address.phone` | `555-555-SHIP` | | E-mail | `$.email` | `jon@example.com` | | Nome | `$.billing_address.name` | `Steve Shipper` | | Produto (o primeiro do pedido) | `$.line_items[0].title` | `Aviator sunglasses` | | Status do pagamento | `$.financial_status` | `voided` | | Status do envio | `$.fulfillment_status` | `null` | | Número do pedido | `$.name` | `#9999` | | Link de acompanhamento | `$.order_status_url` | o endereço da página do pedido | O telefone depende de onde a sua loja pede o número: no endereço de cobrança, no de entrega (`$.shipping_address.phone`) ou no cliente (`$.customer.phone`). É um texto livre, digitado pelo cliente, e pode vir vazio: use o e-mail para identificar o contato quando o telefone não for confiável. A Shopify apaga o webhook quando o endereço responde com erro muitas vezes seguidas. Fontes: [Criar webhooks, na Central de Ajuda da Shopify](https://help.shopify.com/pt-BR/manual/fulfillment/setup/notifications/webhooks) e [tópicos de webhook da Shopify](https://shopify.dev/docs/api/webhooks/latest). A configuração na NexTags, passo a passo: [Shopify](https://help.nextags.com.br/integracoes/shopify/). ### Passo 4: Formulário do seu site O navegador não deve mandar os dados direto para o link do webhook de entrada: o link ficaria no código da página, à vista de qualquer um. O formulário manda os dados para o seu servidor, e o servidor manda o JSON para a NexTags, com o link guardado na variável de ambiente `NEXTAGS_WEBHOOK_URL`. O formulário: ```html
``` O servidor, que recebe o formulário, deixa o telefone só com números, com o `55` na frente, e repassa: **Repassar o formulário para o webhook de entrada** ```javascript // servidor.mjs (Node 18 ou mais novo): node servidor.mjs import http from 'node:http'; http.createServer(async (req, res) => { if (req.method !== 'POST' || req.url !== '/lead') { res.writeHead(404).end(); return; } let corpo = ''; for await (const parte of req) corpo += parte; const form = new URLSearchParams(corpo); const digitos = (form.get('telefone') || '').replace(/\D/g, ''); const telefone = digitos.length <= 11 ? `55${digitos}` : digitos; // 55 + DDD + número const resposta = await fetch(process.env.NEXTAGS_WEBHOOK_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ origem: 'formulario-site', lead: { nome: form.get('nome') || '', email: form.get('email') || '', telefone, }, }), }); if (resposta.ok) { res.writeHead(303, { Location: '/obrigado.html' }).end(); } else { res.writeHead(502).end('Não deu certo. Tente de novo em alguns minutos.'); } }).listen(3000); ``` ```python # servidor.py (Flask): flask --app servidor run --port 3000 import os import re import requests from flask import Flask, redirect, request app = Flask(__name__) @app.post("/lead") def lead(): digitos = re.sub(r"\D", "", request.form.get("telefone", "")) telefone = "55" + digitos if len(digitos) <= 11 else digitos # 55 + DDD + número resposta = requests.post( os.environ["NEXTAGS_WEBHOOK_URL"], json={ "origem": "formulario-site", "lead": { "nome": request.form.get("nome", ""), "email": request.form.get("email", ""), "telefone": telefone, }, }, timeout=30, ) if resposta.ok: return redirect("/obrigado.html", code=303) return "Não deu certo. Tente de novo em alguns minutos.", 502 ``` ```php true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'origem' => 'formulario-site', 'lead' => [ 'nome' => $_POST['nome'] ?? '', 'email' => $_POST['email'] ?? '', 'telefone' => $telefone, ], ]), CURLOPT_TIMEOUT => 30, ]); curl_exec($ch); $codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($codigo >= 200 && $codigo < 300) { header('Location: /obrigado.html', true, 303); } else { http_response_code(502); echo 'Não deu certo. Tente de novo em alguns minutos.'; } ``` | Dado | JSONPath | |---|---| | Telefone | `$.lead.telefone` | | E-mail | `$.lead.email` | | Nome | `$.lead.nome` | | Origem | `$.origem` | No formulário, peça a permissão para mandar mensagens pelo WhatsApp, com um texto claro ao lado do botão. Veja [Permissão para mensagens (opt-in) e descadastro](https://help.nextags.com.br/tutoriais/canais/opt-in/). ## Pronto: como conferir - Faça um envio de teste em cada plataforma: na Hotmart, pela aba **Minhas configurações** ou pelo reenvio no **Histórico**; na Kiwify, com **Testar Webhook**; na Shopify, com um pedido de teste. Depois do envio, o contato aparece em **Contatos**, com os campos preenchidos. - Cole o JSON de um envio real em **Sample JSON**, clique em **Load sample JSON** e confira o `Result:` de cada caminho. - No formulário, envie com o seu número: o fluxo chega no seu WhatsApp. ## Se não funcionou ### O contato foi criado com o telefone incompleto O caminho do telefone pegou um número sem o código do país ou sem o DDD, como o `checkout_phone` do exemplo da Hotmart. Identifique o contato pelo e-mail ou monte o número completo num servidor seu antes de mandar para a NexTags. ### A plataforma desativou ou apagou o webhook Hotmart e Shopify desativam ou apagam o webhook quando o endereço responde com erro. Confira se o webhook de entrada foi salvo e está **Ativo** e se o link está inteiro. Depois, reative ou recrie o webhook do lado da plataforma. ### O mesmo aviso iniciou o fluxo duas vezes As plataformas podem mandar o mesmo evento mais de uma vez. No fluxo, aplique uma etiqueta e confira com uma condição antes de mandar a mensagem. Veja [Segurança, testes e novas tentativas](https://docs.nextags.com.br/webhooks/seguranca-e-testes/). ### O formulário não chega Confira o log do seu servidor: a variável `NEXTAGS_WEBHOOK_URL` tem o link inteiro? O servidor recebeu a resposta da NexTags? Veja [Meu webhook de entrada não recebe os dados](https://help.nextags.com.br/perguntas/integracoes/webhook-nao-recebe/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Vou ligar [Hotmart / Kiwify / Shopify / o formulário do meu site] a um webhook de entrada da NexTags. Leia este guia: https://docs.nextags.com.br/webhooks/exemplos-de-plataformas.md Este é o JSON de um envio de teste, sem dados reais: [cole aqui]. Me diga os caminhos (JSONPath só com .chave, ["chave"] e [0]) do telefone, do e-mail, do nome, do produto e do status, os campos personalizados que devo criar e se o telefone já vem completo, com o código do país e o DDD. ``` --- # IA e MCP > Use a documentação com o ChatGPT e o Claude e prepare sua IA para operar a NexTags. Endereço: https://docs.nextags.com.br/ia/ Tipo: Seção ## Páginas - [A documentação pronta para IA](https://docs.nextags.com.br/ia/documentacao-para-ia.md): Cada página das duas centrais em Markdown, o llms.txt, o llms-full.txt, o contrato OpenAPI e a coleção do Postman: o que a sua IA pode ler da NexTags. - [Atalhos para o ChatGPT e o Claude](https://docs.nextags.com.br/ia/atalhos-chatgpt-e-claude.md): Abra qualquer página no ChatGPT ou no Claude, use os pedidos prontos, monte um projeto com a documentação e peça código sem expor a chave de API. - [Respostas ricas e ações do agente de IA](https://docs.nextags.com.br/ia/respostas-do-agente-em-json.md): Faça o agente de IA mandar imagem, botões e carrossel e executar ações: o que marcar no AI Hub, o que escrever no prompt e o formato JSON de mensagens e ações. - [Skill da NexTags no Claude Code](https://docs.nextags.com.br/ia/skill-claude-code.md): Instale a skill da NexTags no Claude Code e monte o seu agente de IA com uma entrevista guiada. Ela entrega os 3 textos para colar no AI Hub. - [Servidor MCP da NexTags (em breve)](https://docs.nextags.com.br/ia/servidor-mcp.md) - [Prompts prontos para montar agentes e integrações](https://docs.nextags.com.br/ia/prompts-prontos.md): Pedidos para colar no ChatGPT ou no Claude: integração com a API, mapeamento de webhook, servidor da requisição externa, prompt do agente e revisão de código. _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._ --- # A documentação pronta para IA > Cada página das duas centrais em Markdown, o llms.txt, o llms-full.txt, o contrato OpenAPI e a coleção do Postman: o que a sua IA pode ler da NexTags. Endereço: https://docs.nextags.com.br/ia/documentacao-para-ia/ Tipo: Conceito Atualizado em: 26/10/2026 As duas centrais da NexTags, a de Desenvolvedores e a Central de Ajuda, são feitas para pessoas e para IAs. Toda página tem uma versão em Markdown, cada central tem um índice para IA e a API tem um contrato OpenAPI. Assim, o ChatGPT, o Claude ou um agente seu leem a documentação atual, direto da fonte, em vez de responder de memória. ## Como funciona | O que | Onde | O que tem | |---|---|---| | Cada página em Markdown | O endereço da página com `.md` no lugar da barra final | O texto da página, sem menu nem visual. Links e imagens vêm com o endereço completo. | | Índice para IA | [/llms.txt](https://docs.nextags.com.br/llms.txt) e, na Central de Ajuda, [/llms.txt](https://help.nextags.com.br/llms.txt) | Todas as páginas da central, por seção, com o título, o resumo e o link do `.md`. As que ainda não têm o texto final aparecem com "(em produção)". | | A central inteira | [/llms-full.txt](https://docs.nextags.com.br/llms-full.txt) e, na Central de Ajuda, [/llms-full.txt](https://help.nextags.com.br/llms-full.txt) | Todas as páginas da central em Markdown, num arquivo só. | | Contrato da API | [/openapi.json](https://docs.nextags.com.br/openapi.json), também em [/.well-known/openapi.json](https://docs.nextags.com.br/.well-known/openapi.json) | A API em OpenAPI 3.1, em português: endpoints, parâmetros, objetos, respostas e exemplos de código. | | Coleção do Postman | [/nextags.postman_collection.json](https://docs.nextags.com.br/nextags.postman_collection.json) | Uma pasta por recurso da API. Preencha a variável `chave_api` com a chave da sua conta. | Os arquivos da API também estão em [Arquivos para baixar](https://docs.nextags.com.br/referencia/#arquivos-para-baixar), na Referência. ### O Markdown de uma página Troque a barra final do endereço por `.md`: ```text https://docs.nextags.com.br/webhooks/webhook-de-entrada/ https://docs.nextags.com.br/webhooks/webhook-de-entrada.md ``` O arquivo começa com o título, o resumo, o endereço da página e o tipo, e segue com o texto. Os blocos da página viram Markdown comum: os passos ganham títulos numerados ("Passo 1: …"), os avisos viram citações e o pedido de "Faça com a IA" vem num bloco de texto. Nas páginas da Referência, o Markdown traz o método e o caminho, as tabelas de parâmetros e de campos, o exemplo em cURL e as respostas. ```text # Webhook de entrada: receber dados de outro sistema > Mande um JSON de outro sistema para o link de um webhook de entrada. ... Endereço: https://docs.nextags.com.br/webhooks/webhook-de-entrada/ Tipo: Guia ``` Os arquivos `.md`, os `llms*.txt`, o `openapi.json` e a coleção respondem com o cabeçalho `Access-Control-Allow-Origin: *`: uma ferramenta no navegador também consegue ler. O `robots.txt` das duas centrais libera tudo (`Allow: /`) para buscadores e agentes de IA. ### O menu de cada página No topo de cada página, ao lado da data, fica o botão **Copiar página**. A seta ao lado abre o menu: | Opção | O que faz | |---|---| | **Copiar página** | Copia o Markdown da página, pronto para colar numa conversa com a IA. | | **Ver como Markdown** | Abre o `.md` da página numa nova aba. | | **Abrir no ChatGPT** | Abre o ChatGPT com um pedido que manda ler o `.md` da página. | | **Abrir no Claude** | Abre o Claude com o mesmo pedido. | | **Copiar link** | Copia o endereço da página. | Nos guias, o bloco **Faça com a IA** traz um pedido pronto, com o link do `.md` da página. O botão **Copiar pedido** copia o texto. Veja [Atalhos para o ChatGPT e o Claude](https://docs.nextags.com.br/ia/atalhos-chatgpt-e-claude/). ## Quando usar | Você quer… | Use | |---|---| | Tirar uma dúvida sobre uma página | **Abrir no ChatGPT** ou **Abrir no Claude**, no menu da página | | Que a IA escreva o código de uma integração | O `.md` das páginas que importam e o `/openapi.json`. Veja [Prompts prontos](https://docs.nextags.com.br/ia/prompts-prontos/). | | Dar a um projeto do ChatGPT ou do Claude o contexto da NexTags inteira | O `/llms-full.txt` das duas centrais e o `/openapi.json`, como arquivos do projeto | | Que um agente seu ache a página certa sozinho | O `/llms.txt`: ele lê o índice e abre só os `.md` de que precisa | | Gerar um cliente da API ou testar no Postman | O `/openapi.json` ou a coleção do Postman | ## Boas práticas > **Prefira o link à cópia:** > O `.md` no ar é sempre a versão atual. Uma cópia colada numa conversa ou num projeto fica velha quando a página muda: atualize os arquivos do projeto de tempos em tempos. > **Dê à IA só o que importa:** > Para uma tarefa só, os `.md` de duas ou três páginas funcionam melhor do que a central inteira. Deixe o `/llms-full.txt` para os projetos que tratam de muitos assuntos. > **Nunca mande a chave de API para a IA:** > A documentação não precisa da sua chave, e a IA também não: peça código que leia a chave de uma variável de ambiente, como `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). --- # Atalhos para o ChatGPT e o Claude > Abra qualquer página no ChatGPT ou no Claude, use os pedidos prontos, monte um projeto com a documentação e peça código sem expor a chave de API. Endereço: https://docs.nextags.com.br/ia/atalhos-chatgpt-e-claude/ Tipo: Guia Atualizado em: 26/10/2026 Cada página das centrais da NexTags abre direto no ChatGPT ou no Claude, com um pedido que manda a IA ler a página em Markdown. Para um trabalho maior, como escrever uma integração inteira, monte um projeto com a documentação como arquivos. Este guia mostra os dois caminhos e como pedir código sem nunca colar a chave de API na conversa. **Antes de começar** - Uma conta no ChatGPT ou no Claude. - Para pedir código: a chave de API da conta, guardada numa variável de ambiente do seu computador ou servidor. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Passo a passo ### Passo 1: Abra a página na IA No topo da página, clique na seta ao lado de **Copiar página** e escolha **Abrir no ChatGPT** ou **Abrir no Claude**. A conversa abre com este pedido, já com o endereço do `.md` da página: ```text Leia https://docs.nextags.com.br/webhooks/webhook-de-entrada.md e me ajude a usar a NexTags com base nesta página. ``` Continue a conversa com a sua dúvida. Se a IA disser que não consegue abrir o endereço, use **Copiar página** e cole o texto na conversa: ele vai em Markdown, com os links completos. ### Passo 2: Use o pedido pronto da página Os guias terminam com o bloco **Faça com a IA**: um pedido pronto, que cita o `.md` da página e tem lacunas entre colchetes para você completar. Clique em **Copiar pedido**, cole na conversa e troque o que está entre colchetes, como neste pedido do guia do webhook de entrada: ```text Vou mandar dados do meu sistema para um webhook de entrada da NexTags. Leia este guia: https://docs.nextags.com.br/webhooks/webhook-de-entrada.md Este é um exemplo do JSON que o meu sistema envia, sem dados reais: [cole aqui]. ... ``` Mais pedidos, para outras tarefas, estão em [Prompts prontos para montar agentes e integrações](https://docs.nextags.com.br/ia/prompts-prontos/). ### Passo 3: Monte um projeto com a documentação Para conversar sobre a NexTags em vários dias, crie um projeto no ChatGPT ou no Claude e ponha a documentação como arquivos do projeto. Baixe três arquivos: o `llms-full.txt` das duas centrais e o contrato da API. **Baixar a documentação** ```bash curl -o docs-llms-full.txt https://docs.nextags.com.br/llms-full.txt curl -o ajuda-llms-full.txt https://help.nextags.com.br/llms-full.txt curl -o openapi.json https://docs.nextags.com.br/openapi.json ``` ```powershell Invoke-WebRequest https://docs.nextags.com.br/llms-full.txt -OutFile docs-llms-full.txt Invoke-WebRequest https://help.nextags.com.br/llms-full.txt -OutFile ajuda-llms-full.txt Invoke-WebRequest https://docs.nextags.com.br/openapi.json -OutFile openapi.json ``` Depois: - **No ChatGPT**: crie um projeto e adicione os arquivos como fontes do projeto. As instruções do projeto ficam nas configurações dele. Veja [Projects in ChatGPT](https://help.openai.com/en/articles/10169521-projects-in-chatgpt), da OpenAI. - **No Claude**: em Projects, crie um projeto (**+ New Project**), envie os arquivos pelo **+** do conhecimento do projeto e escreva as instruções em **Set project instructions**. Veja [How can I create and manage projects?](https://support.claude.com/en/articles/9519177-how-can-i-create-and-manage-projects), da Anthropic. Nas instruções do projeto, diga como você quer as respostas: ```text Você me ajuda a integrar sistemas com a NexTags. Use os arquivos deste projeto como fonte: docs-llms-full.txt (central de desenvolvedores), ajuda-llms-full.txt (Central de Ajuda) e openapi.json (o contrato da API). Responda em português. Nos exemplos de código, use a URL base https://app.nextagsai.com.br/api e a chave no cabeçalho X-ACCESS-TOKEN, lida da variável de ambiente NEXTAGS_API_KEY. Use só endpoints que existem no openapi.json. Se a documentação não disser algo, diga que não está documentado, em vez de supor. ``` ### Passo 4: Peça o código da integração Descreva o que o seu sistema precisa fazer, a linguagem e onde o código vai rodar. Peça que a chave venha de uma variável de ambiente: ```text Quero criar o contato na NexTags e mandar o fluxo de boas-vindas quando alguém se cadastra no meu site. Meu servidor é Node 20. Escreva o código com fetch, lendo a chave de process.env.NEXTAGS_API_KEY, e trate os erros de cada chamada. Diga quais endpoints usou e o link da página de cada um. ``` Confira os endpoints da resposta na [Referência da API](https://docs.nextags.com.br/referencia/) e rode o código primeiro numa conta de testes ou com o seu próprio contato. ### Passo 5: Deixe a chave fora da conversa A IA não precisa da sua chave para escrever o código, e uma chave colada numa conversa fica guardada no histórico. Guarde a chave numa variável de ambiente, no terminal ou no servidor, e use o código que a lê de lá: **Guardar a chave numa variável de ambiente** ```bash # macOS e Linux export NEXTAGS_API_KEY="SUA_CHAVE_DE_API" ``` ```powershell # Windows (PowerShell) $env:NEXTAGS_API_KEY = "SUA_CHAVE_DE_API" ``` Troque `SUA_CHAVE_DE_API` pela chave, só no seu terminal. A chamada sai do servidor, nunca do navegador nem do app do celular: lá, a chave ficaria exposta. Para conferir a chave, veja [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/). ## Pronto: como conferir - A IA responde citando a página da NexTags que leu. - O código usa a URL base `https://app.nextagsai.com.br/api`, manda a chave no cabeçalho `X-ACCESS-TOKEN` e lê a chave de `NEXTAGS_API_KEY`. - Nenhuma mensagem da conversa tem a sua chave. ## Se não funcionou ### A IA diz que não consegue abrir o link Use **Copiar página** e cole o texto na conversa, ou envie o `.md` como arquivo. Para várias páginas, use os arquivos do projeto. ### A IA usou um endpoint que não existe Peça para conferir no `openapi.json` e use só os endpoints de lá. Confira o caminho na [Referência da API](https://docs.nextags.com.br/referencia/). ### A resposta não bate com a página atual Os arquivos do projeto ficaram velhos. Baixe de novo o `llms-full.txt` e o `openapi.json` e troque os arquivos do projeto. ### Colei a chave de API na conversa Troque a chave: em **Configurações** › **Integrações** › **Chave de API do NexTags**, clique em **Excluir** e depois em **Gerar**. Cole a chave nova nos sistemas que usavam a antiga. Veja [Gerar a chave de API](https://help.nextags.com.br/tutoriais/configuracoes/chave-de-api/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Quero montar um projeto no [ChatGPT / Claude] para integrar o meu sistema com a NexTags. Leia este guia: https://docs.nextags.com.br/ia/atalhos-chatgpt-e-claude.md Meu sistema: [descreva, por exemplo: uma loja em PHP que precisa criar contatos e mandar fluxos]. Escreva as instruções do projeto para mim, com a linguagem e as regras de código (a chave de API sempre lida de uma variável de ambiente), e uma lista de três pedidos para eu começar. ``` --- # Respostas ricas e ações do agente de IA > Faça o agente de IA mandar imagem, botões e carrossel e executar ações: o que marcar no AI Hub, o que escrever no prompt e o formato JSON de mensagens e ações. Endereço: https://docs.nextags.com.br/ia/respostas-do-agente-em-json/ Tipo: Guia Atualizado em: 26/10/2026 Por padrão, o agente de IA responde só com texto. Para ele mandar imagem, vídeo, áudio, arquivo, texto com botões e carrossel, e para executar ações, como aplicar uma etiqueta ou passar a conversa para a equipe, o editor do agente tem dois ajustes: o **Tipo de resposta da IA** e as **Ações de IA**. A NexTags converte as respostas para o canal do contato. Este guia mostra o que configurar e o que escrever no prompt. No fim, está o formato JSON de mensagens e ações que a central antiga ensinava a pedir no prompt, com o que mudou. **Antes de começar** - Um agente de IA criado no **AI Hub**. Veja [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/). - Para mandar mídia: cada arquivo publicado num endereço `https://` que abre o arquivo direto, sem login. - Os fluxos, as etiquetas e os campos personalizados que as ações vão usar. ## Passo a passo ### Passo 1: Marque os formatos em Tipo de resposta da IA No menu **AI Hub**, na aba **Agentes de IA**, clique no agente. No editor, clique no ícone de ajustes, à direita de **Mensagem do sistema**, e marque os formatos em **Tipo de resposta da IA**. Dá para marcar mais de um; um agente novo vem só com **Texto**. ```text Tipo de resposta da IA: Texto Imagem | Vídeo | Áudio | Arquivo Texto + Botões Carrossel ``` O ⓘ do campo avisa: a IA envia imagens, vídeos, áudios e arquivos quando os links deles estão no prompt. Clique em **Salvar**, no topo da tela. O passo a passo de tela está em [Tipos de resposta: texto, mídia, botões e carrossel](https://help.nextags.com.br/tutoriais/ia/respostas-elaboradas/). ### Passo 2: Diga no prompt quando usar cada formato Na **Mensagem do sistema**, liste as mídias que o agente pode mandar, cada uma com o link, e diga quando usar cada formato. Não é preciso pedir JSON nem descrever o formato técnico: a NexTags faz a conversão a partir do **Tipo de resposta da IA**. ```text ENVIO DE MÍDIA, BOTÕES E CARROSSEL - Quando o cliente pedir o cardápio, envie o PDF como arquivo: https://seusistema.exemplo.com.br/cardapio.pdf - Fotos de produto: envie como imagem, com a legenda "Nome – tamanho – preço". - Para mostrar de 2 a 10 produtos de uma vez, use o carrossel, um cartão por produto. - Para escolhas fechadas, como Retirada ou Entrega, use texto com até 3 botões de títulos curtos. - Nas outras respostas, use só texto. ``` Os limites do formato valem também aqui: até 3 botões por mensagem, com títulos de até 20 caracteres, e até 10 cartões num carrossel. Como escrever o resto do prompt: [Escrever a mensagem do sistema (prompt)](https://help.nextags.com.br/tutoriais/ia/escrever-o-prompt/). ### Passo 3: Configure as ações em Ações de IA No cartão **Ações de IA**, clique em **+ Adicionar regra**. Em **Quando**, descreva a situação da conversa; em **O que a IA deve fazer?**, escolha as ações, na ordem, com **+ Adicionar ação** para cada uma. Uma regra de transferência, por exemplo: ```text Quando: O cliente aprovou o resumo do pedido e o agente respondeu "Seu pedido foi pré-confirmado e já passei para a nossa equipe". Não vale se o cliente só pediu o resumo ou pediu uma mudança. Ação 1: Adicionar Etiqueta → Pedido pré-confirmado Ação 2: Definir Campo Personalizado → resumo_pedido (Da conversa) Ação 3: Transferir conversa para humano Ação 4: Atribuir conversa a um administrador → quem atende os pedidos ``` As ações disponíveis: **Enviar Fluxo**, **Atribuir conversa a um administrador**, **Remover atribuição**, **Transferir conversa para humano**, **Adicionar Etiqueta**, **Remover Etiqueta**, **Definir Campo Personalizado**, **Limpar Campo Personalizado**, **Seguir**, **Remover do acompanhamento**, **Transferir conversa para bot**, **Arquivar** e **Bloquear contato**. Com pelo menos uma regra, o ícone de ajustes do cartão abre o **Prompt da ação**: instruções que valem para todas as regras e que a NexTags junta ao prompt principal. Veja [Ações de IA: o agente que envia fluxos, etiqueta e transfere](https://help.nextags.com.br/tutoriais/ia/acoes-do-agente/). ### Passo 4: Teste o agente No AI Hub, abra o menu ⋮ do agente e clique em **Testar Agora**: o chat de teste abre numa nova aba. A opção aparece só no agente padrão; veja [Agente padrão e resposta automática por IA](https://help.nextags.com.br/tutoriais/ia/agente-padrao/). Faça as perguntas que levam a cada formato e a cada regra: ```text "Me manda o cardápio" → o PDF chega como arquivo "Quais sabores vocês têm?" → um carrossel com as fotos "Quero retirar na loja" → texto com botões "Pode confirmar o pedido" → a etiqueta, o campo e a transferência para a equipe ``` Ajuste o prompt e as regras e teste de novo. Veja [Testar e ajustar o agente](https://help.nextags.com.br/tutoriais/ia/testar-agente/). ## O formato JSON de mensagens e ações A NexTags usa um mesmo formato JSON para mensagens e ações em vários lugares: na API ([Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/)), na resposta da requisição externa (o conteúdo dinâmico) e no agente de IA que responde em JSON, como a central antiga ensinava. O formato completo está em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). Em resumo: - `messages`: a lista das mensagens, na ordem. Cada item é um objeto com a chave `message`, no formato de mensagens do Messenger, e a NexTags converte para o canal do contato. Alguns formatos não existem em todos os canais. - Um número sozinho entre duas mensagens mostra "digitando" por esse número de segundos. - `actions`: a lista das ações, executadas na ordem. ### O que mudou A central antiga da NexTags ensinava a pôr no fim da **Mensagem do sistema** um trecho que pedia ao agente respostas nesse JSON. Hoje, o **Tipo de resposta da IA** e as **Ações de IA** fazem esse trabalho pela tela, e a skill oficial da NexTags para o Claude Code orienta não pedir JSON no prompt. Para um agente novo, use os passos acima. > **Se o seu agente ainda usa o trecho antigo:** > Teste antes de mudar qualquer coisa: abra o **Testar Agora** e confira se as mensagens chegam como imagem, botões e carrossel, e não como texto com chaves e aspas. Ao migrar, marque os formatos em **Tipo de resposta da IA**, crie as regras em **Ações de IA** e só depois tire o trecho do prompt. O trecho da central antiga, revisado: ```text Responda sempre com um JSON válido, no formato de mensagens do Messenger. Regras: 1. O JSON tem a lista "messages", a lista "actions" ou as duas. 2. "messages" é uma lista de objetos, e cada objeto tem a chave "message". 3. O objeto "message" segue o formato de mensagens do Messenger. 4. Tipos de mensagem aceitos: texto, texto com botões, imagem, vídeo, áudio, arquivo e carrossel (template do tipo "generic"). 5. Responda só com o JSON: sem explicações, sem Markdown e sem texto antes ou depois. ``` ### Exemplos Várias mensagens: ```json { "messages": [ { "message": { "text": "Olá, Ana!" } }, { "message": { "text": "Esta é a segunda mensagem." } } ] } ``` Uma imagem. Para vídeo, áudio e arquivo, troque `"image"` por `"video"`, `"audio"` ou `"file"`: ```json { "messages": [ { "message": { "attachment": { "type": "image", "payload": { "url": "https://seusistema.exemplo.com.br/fotos/bolo.jpg" } } } } ] } ``` Um carrossel com dois cartões (até 10). `image_aspect_ratio` aceita `horizontal` ou `square`: ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "generic", "image_aspect_ratio": "horizontal", "elements": [ { "title": "Bolo de chocolate", "subtitle": "Fatia: R$ 12,00", "image_url": "https://seusistema.exemplo.com.br/fotos/bolo.jpg", "buttons": [] }, { "title": "Torta de limão", "subtitle": "Fatia: R$ 10,00", "image_url": "https://seusistema.exemplo.com.br/fotos/torta.jpg", "buttons": [] } ] } } } } ] } ``` Texto com dois botões: um abre um link e o outro manda o fluxo `1000001` (o `payload` do botão é o ID do fluxo): ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "button", "text": "Como você quer continuar?", "buttons": [ { "type": "web_url", "title": "Ver o cardápio", "url": "https://seusistema.exemplo.com.br/cardapio" }, { "type": "postback", "title": "Fazer um pedido", "payload": "1000001" } ] } } } } ] } ``` Uma pausa de 4 segundos, com "digitando", entre duas mensagens: ```json { "messages": [ { "message": { "text": "Vou conferir para você." } }, 4, { "message": { "text": "Pronto: o seu pedido está a caminho." } } ] } ``` Mensagens e ações juntas: ```json { "messages": [ { "message": { "text": "Anotado! Já passei o seu pedido para a equipe." } } ], "actions": [ { "action": "add_tag", "tag_name": "lead" }, { "action": "set_field_value", "field_name": "Valor do pedido", "value": "89" }, { "action": "send_flow", "flow_id": "1000001" } ] } ``` ### As ações | Ação | JSON | |---|---| | Adicionar uma etiqueta | `{"action": "add_tag", "tag_name": ""}` | | Remover uma etiqueta | `{"action": "remove_tag", "tag_name": ""}` | | Preencher um campo personalizado | `{"action": "set_field_value", "field_name": "", "value": ""}` | | Limpar um campo personalizado | `{"action": "unset_field_value", "field_name": ""}` | | Mandar um fluxo | `{"action": "send_flow", "flow_id": ""}` | | Passar a conversa para a equipe | `{"action": "transfer_conversation_to", "value": "human"}` | | Devolver a conversa ao robô | `{"action": "transfer_conversation_to", "value": "bot"}` | | Atribuir a conversa a um administrador | `{"action": "assign_conversation", "admin_id": ""}` | | Remover a atribuição | `{"action": "unassign_conversation"}` | O `set_field_value` também preenche os campos do sistema `phone`, `email`, `full_name`, `first_name` e `last_name`. Onde achar o ID de um fluxo e de um administrador: [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ## Pronto: como conferir - No **Testar Agora**, a mídia chega como arquivo, e não como link; o carrossel e os botões aparecem como cartões e botões. - Depois de uma regra disparar, a etiqueta, o campo e o responsável aparecem no painel do contato, na **Caixa de Entrada**. ## Se não funcionou ### O agente mandou o link em vez da mídia Confira se **Imagem | Vídeo | Áudio | Arquivo** está marcado em **Tipo de resposta da IA** e se você clicou em **Salvar**. Abra o link numa janela anônima: ele precisa abrir o arquivo, sem login. ### O contato recebeu um texto com chaves e aspas O agente escreveu o JSON como texto. Marque os formatos em **Tipo de resposta da IA**, use as **Ações de IA** para as ações e tire do prompt o trecho que pede JSON. ### A regra de Ações de IA não disparou Escreva o **Quando** com o que aparece na conversa, como a frase fixa que o agente manda, e uma situação só por regra. Veja [Ações de IA: o agente que envia fluxos, etiqueta e transfere](https://help.nextags.com.br/tutoriais/ia/acoes-do-agente/). ### O botão não abriu o fluxo O `payload` de um botão é o ID do fluxo, como texto. Confira o ID em [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Configuro um agente de IA na NexTags. Leia este guia: https://docs.nextags.com.br/ia/respostas-do-agente-em-json.md Meu negócio: [descreva]. Minhas mídias: [liste cada arquivo com o link]. Os fluxos, etiquetas e campos que já tenho: [liste]. Escreva o trecho da Mensagem do sistema que diz quando usar texto, mídia, botões e carrossel, as regras de Ações de IA (o Quando e as ações de cada uma) e um Prompt da ação curto. Não peça JSON no prompt. ``` > **O agente pela API:** > A API consulta e atualiza os agentes de IA. Veja [Agentes de IA pela API](https://docs.nextags.com.br/guias/agentes-de-ia-pela-api/). --- # Skill da NexTags no Claude Code > Instale a skill da NexTags no Claude Code e monte o seu agente de IA com uma entrevista guiada. Ela entrega os 3 textos para colar no AI Hub. Endereço: https://docs.nextags.com.br/ia/skill-claude-code/ Tipo: Guia Atualizado em: 26/10/2026 Uma skill é um pacote de instruções que ensina o Claude a fazer uma tarefa do jeito certo. A skill da NexTags, `criar-agente-ia`, faz o Claude Code trabalhar como um consultor de agentes: ele entrevista você sobre o negócio, coleta os produtos ou serviços (do site, de um cardápio em PDF, de uma planilha ou de uma lista colada), com as fotos, e entrega 3 textos prontos para colar no AI Hub. Serve para qualquer segmento, como delivery, loja, clínica, salão, imobiliária e serviços. A skill vem no plugin `nextags`, do catálogo público [guiipego/nextags](https://github.com/guiipego/nextags), no GitHub. **Antes de começar** - Uma conta do Claude com acesso ao Claude Code: planos Pro, Max, Team ou Enterprise, ou uma conta do Console. O plano gratuito do Claude não inclui o Claude Code. - Python 3, para os scripts da skill, que montam o catálogo e conferem os textos. Confira com `python3 --version` (no Windows, `python --version`). Se não tiver, instale pelo site do Python e, no Windows, marque **Add python.exe to PATH** na instalação. - No Windows, o Git for Windows: o Claude Code usa o Git para baixar o catálogo de plugins. - Um agente de IA criado no **AI Hub**, com um provedor de IA conectado. Veja [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/). ## Passo a passo ### Passo 1: Instale o Claude Code Se você já usa o Claude Code, pule para o próximo passo. Abra o Terminal (no macOS ou no Linux) ou o PowerShell (no Windows) e cole: **Instalar o Claude Code** ```bash # macOS, Linux e WSL curl -fsSL https://claude.ai/install.sh | bash ``` ```powershell # Windows (PowerShell) irm https://claude.ai/install.ps1 | iex ``` Depois, abra um terminal novo e rode `claude --version`: aparece o número da versão. Digite `claude` e entre com a sua conta do Claude. Fonte: [Advanced setup](https://code.claude.com/docs/en/setup), da Anthropic. ### Passo 2: Adicione o catálogo da NexTags No terminal, cole: ```bash claude plugin marketplace add guiipego/nextags ``` A resposta começa com `Successfully added marketplace: nextags`. O catálogo fica registrado no seu computador; não é preciso repetir. ### Passo 3: Instale o plugin ```bash claude plugin install nextags@nextags ``` A resposta começa com `Successfully installed plugin: nextags@nextags`. Instalado pelo terminal, o plugin vale para você em todos os projetos do computador. Para conferir, rode `claude plugin list`: o plugin `nextags@nextags` aparece com `Status: ✔ enabled`. Prefere fazer dentro do Claude Code? Numa sessão aberta, digite `/plugin marketplace add guiipego/nextags` e depois `/plugin install nextags@nextags`. O painel abre com os detalhes do plugin: escolha **Install for you (user scope)**. Os comandos estão em [Install and manage plugins](https://code.claude.com/docs/en/discover-plugins), da Anthropic. ### Passo 4: Abra o Claude Code numa pasta só para o agente Os 3 textos são salvos como arquivos, então crie uma pasta para eles, como "Agente NexTags", em Documentos, e abra o Claude Code nela: **Criar a pasta e abrir o Claude Code** ```bash # macOS e Linux mkdir -p ~/Documents/"Agente NexTags" && cd ~/Documents/"Agente NexTags" && claude ``` ```powershell # Windows (PowerShell) mkdir "$env:USERPROFILE\Documents\Agente NexTags"; cd "$env:USERPROFILE\Documents\Agente NexTags"; claude ``` No app do Claude para computador, abra a aba **Code** e escolha essa pasta. O plugin instalado pelo terminal também aparece no app. ### Passo 5: Comece a montar o agente Na sessão do Claude Code, digite: ```text /nextags:criar-agente-ia ``` Ou peça do seu jeito, como "quero criar meu agente de atendimento na NexTags para a minha confeitaria". A partir daí, a skill conduz o trabalho: 1. Pede o nome do negócio e onde estão os produtos ou serviços: site, cardápio, planilha ou lista. 2. Faz poucas perguntas por vez. O que você não souber fica marcado `[A DEFINIR]`, e o agente aprende a dizer que a equipe confirma. 3. Coleta o catálogo e confere as fotos. 4. Escreve os 3 textos, revisa e salva na pasta. Quando o Claude for ler o seu site ou rodar um script da skill, o Claude Code pede permissão. Escolha **Yes**; para não ser perguntado de novo pelo mesmo comando, escolha **Yes, and don't ask again**, quando a opção aparecer. ### Passo 6: Cole os 3 textos no AI Hub No fim, a pasta tem os 3 textos, além dos arquivos de trabalho da skill, como o catálogo: ```text Agente NexTags/ 1_mensagem_do_sistema.md 2_prompt_da_acao.md 3_acoes_de_ia.md ``` | Arquivo | Onde colar na NexTags | |---|---| | `1_mensagem_do_sistema.md` | **AI Hub** › aba **Agentes de IA** › o seu agente › **Mensagem do sistema** | | `3_acoes_de_ia.md` | No mesmo editor, cartão **Ações de IA** › **+ Adicionar regra**: uma regra para cada regra do arquivo, com o texto do **Quando** e as ações em **O que a IA deve fazer?**, na ordem | | `2_prompt_da_acao.md` | Cartão **Ações de IA** › ícone de ajustes › **Prompt da ação**. O ícone aparece quando o agente tem pelo menos uma regra: cole este texto depois das regras. | Antes de colar as regras, crie o que a skill listar no checklist da entrega: as etiquetas, os campos personalizados (com os nomes exatos do arquivo) e quem recebe as conversas transferidas. A skill também recomenda a configuração do agente: os formatos em **Tipo de resposta da IA**, o modelo e os ajustes **Max tokens**, **Reasoning effort** e **Verbosity**. Use o modelo que a skill recomendar, se ele estiver na lista do seu provedor. Onde fica cada ajuste: [Modelo, temperatura e limite de tokens](https://help.nextags.com.br/tutoriais/ia/modelo-e-parametros/). Depois, clique em **Salvar**, no topo da tela. ### Passo 7: Teste antes de ligar para os clientes Converse com o agente usando um número seu e passe pelos casos que mais dão erro: ```text Peça o cardápio ou a lista de serviços. Faça um pedido ou um agendamento completo. Mude o pedido no meio da conversa. Pergunte por um produto que não existe. Peça para falar com uma pessoa. ``` Confira se as transferências, as etiquetas e os campos funcionam. Veja [Testar e ajustar o agente](https://help.nextags.com.br/tutoriais/ia/testar-agente/) e [Agente padrão e resposta automática por IA](https://help.nextags.com.br/tutoriais/ia/agente-padrao/). ## Atualizar a skill Para buscar a versão mais nova do catálogo e atualizar o plugin: ```bash claude plugin marketplace update nextags claude plugin update nextags@nextags ``` A versão nova entra na próxima sessão, ou na hora, com `/reload-plugins` numa sessão aberta. Para atualizar sozinho, digite `/plugin` dentro do Claude Code, abra a aba **Marketplaces**, escolha **nextags** e clique em **Enable auto-update**: num catálogo de fora da Anthropic, a atualização automática começa desligada. ## Pronto: como conferir - `claude plugin list` mostra `nextags@nextags` com `Status: ✔ enabled`. - Ao digitar `/` numa sessão, aparece `/nextags:criar-agente-ia`. - A pasta do agente tem os 3 arquivos, e o agente no AI Hub está salvo com a mensagem do sistema, as regras e o prompt da ação. ## Se não funcionou ### O terminal não reconhece o comando claude Abra um terminal novo depois da instalação. Se continuar, a pasta do Claude Code não está no PATH: siga [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install), da Anthropic. ### O comando claude plugin não existe O Claude Code está numa versão antiga. Rode `claude update` e tente de novo. ### A instalação diz que não achou o plugin ou o catálogo No terminal, a mensagem é `Plugin "nextags" not found in marketplace "nextags"`; numa sessão, `Marketplace "nextags" not found`. O catálogo ainda não foi adicionado: rode `claude plugin marketplace add guiipego/nextags`, escrito exatamente assim, e instale o plugin de novo. ### No Windows, apareceu "Command 'git' not found" Instale o Git for Windows, abra um terminal novo e adicione o catálogo de novo. ### A skill não aparece na sessão Digite `/reload-plugins` ou abra uma sessão nova com `claude`. Para ver o que está instalado, digite `/plugin` e abra a aba **Installed**. ### Apareceu "python3: command not found" ou "python não é reconhecido" Instale o Python 3 e abra um terminal novo. No Windows, marque **Add python.exe to PATH** na instalação. ### As fotos dos produtos não chegam como imagem no WhatsApp O WhatsApp aceita imagens em PNG ou JPEG de até 5 MB. Se as fotos do seu site forem WebP, a skill avisa e oferece a conversão para JPG. Veja [Tipos de arquivo e limites por canal](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Vou montar o meu agente de IA da NexTags com a skill do Claude Code. Leia este guia: https://docs.nextags.com.br/ia/skill-claude-code.md Meu sistema: [macOS / Windows / Linux]. Meu negócio: [descreva em uma frase]. Me diga, na ordem, os comandos para instalar o Claude Code e o plugin da NexTags, e o que separar antes de começar a entrevista: o material dos produtos, as fotos e quem recebe as conversas transferidas. ``` --- # Servidor MCP da NexTags (em breve) Endereço: https://docs.nextags.com.br/ia/servidor-mcp/ Tipo: Conceito _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._ --- # Prompts prontos para montar agentes e integrações > Pedidos para colar no ChatGPT ou no Claude: integração com a API, mapeamento de webhook, servidor da requisição externa, prompt do agente e revisão de código. Endereço: https://docs.nextags.com.br/ia/prompts-prontos/ Tipo: Referência Atualizado em: 26/10/2026 Pedidos prontos para colar no ChatGPT ou no Claude. Cada um manda a IA ler as páginas certas, em Markdown, e tem lacunas entre colchetes para você completar. Nenhum pede a sua chave de API: o código que a IA escrever deve ler a chave de uma variável de ambiente. Para dar à IA a documentação inteira, veja [Atalhos para o ChatGPT e o Claude](https://docs.nextags.com.br/ia/atalhos-chatgpt-e-claude/). | Pedido | Para quê | O que a IA lê | |---|---|---| | [Escolher o caminho](https://docs.nextags.com.br/ia/prompts-prontos/#escolher-o-caminho) | Decidir entre webhook de entrada, webhook de saída, requisição externa e API | Webhooks na NexTags | | [Integração com a API](https://docs.nextags.com.br/ia/prompts-prontos/#integracao-com-a-api) | Escrever o código que chama a API, na sua linguagem | Autenticação, limites e o contrato OpenAPI | | [Mapeamento de um webhook de entrada](https://docs.nextags.com.br/ia/prompts-prontos/#mapeamento-de-um-webhook-de-entrada) | Achar os caminhos de cada dado num JSON de exemplo | Webhook de entrada e Mapear campos | | [Servidor da requisição externa](https://docs.nextags.com.br/ia/prompts-prontos/#servidor-da-requisicao-externa) | Escrever o endpoint que o fluxo chama e que responde com mensagens e ações | Requisição externa e Mensagens e ações em JSON | | [Prompt de um agente com mídia e ações](https://docs.nextags.com.br/ia/prompts-prontos/#prompt-de-um-agente-com-midia-e-acoes) | Escrever a mensagem do sistema e as regras de Ações de IA | Respostas ricas e ações do agente | | [Revisão de código](https://docs.nextags.com.br/ia/prompts-prontos/#revisao-de-codigo) | Achar chave exposta e erros num código que chama a API | Autenticação e limites | ## Escolher o caminho ```text Leia https://docs.nextags.com.br/webhooks/visao-geral.md Quero ligar a NexTags a [nome do sistema]. O que precisa acontecer: [descreva, por exemplo: quando uma venda é aprovada na minha loja, o cliente recebe uma mensagem no WhatsApp e ganha uma etiqueta]. Me diga qual das quatro formas usar (webhook de entrada, webhook de saída, requisição externa ou API), por quê, e os passos na ordem, com o link da página de cada passo. ``` ## Integração com a API ```text Leia https://docs.nextags.com.br/comecar/autenticacao.md e https://docs.nextags.com.br/comecar/limites-e-erros.md. Use o contrato https://docs.nextags.com.br/openapi.json como a lista oficial de endpoints. Escreva em [linguagem e versão, por exemplo: Python 3.12 com requests] o código que [descreva, por exemplo: acha o contato pelo e-mail e, se não existir, cria o contato e manda o fluxo de boas-vindas]. Regras: - a URL base é https://app.nextagsai.com.br/api; - a chave vai no cabeçalho X-ACCESS-TOKEN e é lida da variável de ambiente NEXTAGS_API_KEY; - o código roda no servidor, nunca no navegador; - trate os erros de cada chamada e leia o corpo da resposta como JSON; - use só endpoints que existem no openapi.json e diga o link da página de cada um. Não peça a minha chave. ``` ## Mapeamento de um webhook de entrada ```text Leia https://docs.nextags.com.br/webhooks/webhook-de-entrada.md e https://docs.nextags.com.br/webhooks/mapear-campos.md Vou receber dados de [nome do sistema] num webhook de entrada da NexTags. Este é um exemplo do JSON que ele envia, sem dados reais: [cole o JSON] Me devolva uma tabela com: o dado, o JSONPath (só com .chave, ["chave"] e [0], começando com $), o campo da NexTags que recebe o valor e o tipo do campo (Texto, Número, Data, Data e hora, Verdadeiro/Falso ou Texto longo). Diga qual caminho usar em Número de telefone e em Endereço de e-mail, e se o telefone vem completo, com o código do país e o DDD. ``` ## Servidor da requisição externa ```text Leia https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo.md e https://docs.nextags.com.br/comecar/mensagens-e-acoes.md Escreva em [linguagem e framework] o endpoint que a External API Request de um fluxo da NexTags vai chamar. Ele deve: - conferir o cabeçalho X-Segredo com o valor da variável de ambiente NEXTAGS_SEGREDO, em tempo constante, e responder 401 se não bater; - ler o cabeçalho X-USER-ID (o ID do contato) e o corpo em JSON: [descreva os campos]; - [descreva o que o servidor faz, por exemplo: consultar o pedido no meu banco]; - responder em JSON com "messages" e "actions": [descreva as mensagens, os botões e as ações]. Diga também o que preencher na External API Request: Request Type, Request URL, Cabeçalhos e Corpo. ``` ## Prompt de um agente com mídia e ações ```text Leia https://docs.nextags.com.br/ia/respostas-do-agente-em-json.md e https://help.nextags.com.br/tutoriais/ia/escrever-o-prompt.md Vou configurar um agente de IA no AI Hub da NexTags. Meu negócio: [descreva]. Minhas mídias, cada uma com o link: [liste]. Os fluxos, etiquetas e campos que já existem: [liste]. Quem recebe as conversas transferidas: [nome]. Escreva: 1. a Mensagem do sistema, com uma seção que diz quando usar texto, mídia, texto com botões e carrossel (sem pedir JSON no prompt); 2. as regras de Ações de IA, cada uma com o Quando e as ações na ordem; 3. um Prompt da ação curto; 4. os formatos que devo marcar em Tipo de resposta da IA. ``` ## Revisão de código ```text Leia https://docs.nextags.com.br/comecar/autenticacao.md e https://docs.nextags.com.br/comecar/limites-e-erros.md Revise este código, que chama a API da NexTags: [cole o código, sem a chave] Procure, nesta ordem: 1. chave de API escrita no código, em arquivo versionado ou enviada ao navegador ou ao app (a chave deve vir de uma variável de ambiente do servidor); 2. link de webhook de entrada exposto no código do site; 3. URL base, caminhos e métodos diferentes do contrato https://docs.nextags.com.br/openapi.json; 4. falta de tratamento de erro, como a resposta 401 e chamadas sem tempo limite. Para cada problema, mostre o trecho e a correção. ``` Se você colou uma chave numa conversa sem querer, troque a chave: em **Configurações** › **Integrações** › **Chave de API do NexTags**, clique em **Excluir** e depois em **Gerar**. Veja [Gerar a chave de API](https://help.nextags.com.br/tutoriais/configuracoes/chave-de-api/). --- # Referência da API > Todos os endpoints da API REST da NexTags, agrupados por recurso, gerados do contrato OpenAPI. Endereço: https://docs.nextags.com.br/referencia/ Tipo: Seção ## Páginas - [Conta](https://docs.nextags.com.br/referencia/conta.md): Dados da conta, administradores, equipes e integrações ligadas. - [Contatos](https://docs.nextags.com.br/referencia/contatos.md): Crie, encontre e consulte contatos. - [Mensagens](https://docs.nextags.com.br/referencia/mensagens.md): Envie fluxos, textos, arquivos e conteúdos para um contato. - [Etiquetas](https://docs.nextags.com.br/referencia/etiquetas.md): Etiquetas da conta e dos contatos. - [Campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados.md): Campos da conta e os valores de cada contato. - [Campos do bot](https://docs.nextags.com.br/referencia/campos-do-bot.md): Valores globais da conta, iguais para todos os contatos. - [Fluxos e modelos](https://docs.nextags.com.br/referencia/fluxos.md): Liste os fluxos e instale modelos prontos. - [Pipelines e oportunidades](https://docs.nextags.com.br/referencia/pipelines.md): Pipelines, etapas, oportunidades e comentários do CRM. - [Agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia.md): Agentes, funções, servidores MCP, arquivos e histórico da IA. - [E-commerce](https://docs.nextags.com.br/referencia/ecommerce.md): Produtos, carrinho e pedidos de cada contato. - [Disparos](https://docs.nextags.com.br/referencia/disparos.md): Consulte, reenvie e cancele disparos (broadcasts). - [Agenda](https://docs.nextags.com.br/referencia/agenda.md): Calendários usados nos agendamentos. - [Ferramentas](https://docs.nextags.com.br/referencia/ferramentas.md): Utilitários para usar nas requisições externas dos fluxos: texto, números, URLs, QR Code, hash e distância. _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._ --- # Conta > Dados da conta, administradores, equipes e integrações ligadas. Endereço: https://docs.nextags.com.br/referencia/conta/ Tipo: Referência Os dados da conta dona da chave de API: o nome, quantos contatos ela tem, os administradores, as equipes e as integrações ligadas. Use estas chamadas para conferir a chave e para achar os IDs de administradores e equipes que outras chamadas pedem. ## Endpoints - [Consultar a conta](https://docs.nextags.com.br/referencia/conta/consultar-a-conta.md): `GET /accounts/me` - [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores.md): `GET /accounts/admins` - [Listar equipes](https://docs.nextags.com.br/referencia/conta/listar-equipes.md): `GET /accounts/teams` - [Listar integrações da conta](https://docs.nextags.com.br/referencia/conta/listar-integracoes-da-conta.md): `GET /accounts/integrations` --- # Consultar a conta > Devolve os dados da conta dona da chave de API: o ID, o nome, se o acesso ao painel está liberado, quando a conta foi criada e quantos contatos ela tem. Endereço: https://docs.nextags.com.br/referencia/conta/consultar-a-conta/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/me X-ACCESS-TOKEN: ``` Devolve os dados da conta dona da chave de API: o ID, o nome, se o acesso ao painel está liberado, quando a conta foi criada e quantos contatos ela tem. É a chamada mais simples da API: use para conferir se a chave funciona. Veja [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/me" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os dados da conta. | Campo | Tipo | Descrição | |---|---|---| | `page_id` | integer | O ID da conta. | | `name` | string | O nome da conta. | | `active` | boolean | Se os administradores conseguem entrar no painel da conta. | | `created` | integer | Quando a conta foi criada, em Unix timestamp. | | `total_users` | integer | Quantos contatos a conta tem. | ```json { "page_id": 123456, "name": "Loja Exemplo", "active": true, "created": 1735700000, "total_users": 5230 } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar administradores > Lista os administradores da conta, as pessoas da equipe que entram no painel, com o ID de cada um. Endereço: https://docs.nextags.com.br/referencia/conta/listar-administradores/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/admins X-ACCESS-TOKEN: ``` Lista os administradores da conta, as pessoas da equipe que entram no painel, com o ID de cada um. Outras chamadas pedem esse ID: por exemplo, os responsáveis de uma oportunidade (`assigned_admins`) e a ação `assign_conversation`, que atribui a conversa a alguém. Veja [Administradores e permissões](https://help.nextags.com.br/tutoriais/configuracoes/administradores-e-permissoes/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/admins" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A lista de administradores. Uma lista de Administrador. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do administrador. | | `email` | string | O e-mail de acesso. | | `first_name` | string | O nome. | | `last_name` | string | O sobrenome. | | `full_name` | string | O nome completo. | | `profile_pic` | string | O endereço da foto do perfil. | | `available` | boolean | Se a pessoa está como **Disponível** para receber conversas. | ```json [ { "id": 10001, "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "full_name": "Ana Souza", "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "available": true } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar equipes > Lista as equipes de atendimento da conta (as equipes da Caixa de Entrada), com o ID e o nome de cada uma. Endereço: https://docs.nextags.com.br/referencia/conta/listar-equipes/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/teams X-ACCESS-TOKEN: ``` Lista as equipes de atendimento da conta (as equipes da Caixa de Entrada), com o ID e o nome de cada uma. Veja [Equipes de caixa de entrada](https://help.nextags.com.br/tutoriais/caixa-de-entrada/equipes-de-atendimento/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/teams" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A lista de equipes. Uma lista de Equipe. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da equipe. | | `name` | string | O nome da equipe. | ```json [ { "id": 501, "name": "Vendas" }, { "id": 502, "name": "Suporte" } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar integrações da conta > Mostra quais integrações estão ligadas na conta: os provedores de IA (OpenAI, Gemini, Claude, xAI e DeepSeek), o Google Sheets e o e-mail. Endereço: https://docs.nextags.com.br/referencia/conta/listar-integracoes-da-conta/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/integrations X-ACCESS-TOKEN: ``` Mostra quais integrações estão ligadas na conta: os provedores de IA (OpenAI, Gemini, Claude, xAI e DeepSeek), o Google Sheets e o e-mail. Cada uma vem com `active`: `true` quando está conectada. Veja [A aba Integrações](https://help.nextags.com.br/tutoriais/configuracoes/integracoes/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/integrations" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Cada integração com o seu estado. | Campo | Tipo | Descrição | |---|---|---| | `openai` | object | A OpenAI (ChatGPT). | | `openai.active` | boolean | | | `gemini` | object | O Google Gemini. | | `gemini.active` | boolean | | | `claude` | object | O Claude. | | `claude.active` | boolean | | | `xai` | object | O xAI. | | `xai.active` | boolean | | | `deepseek` | object | O DeepSeek. | | `deepseek.active` | boolean | | | `google_sheets` | object | O Google Sheets. | | `google_sheets.active` | boolean | | | `email` | object | O envio de e-mail. | | `email.active` | boolean | | ```json { "openai": { "active": true }, "gemini": { "active": false }, "claude": { "active": false }, "xai": { "active": false }, "deepseek": { "active": false }, "google_sheets": { "active": true }, "email": { "active": false } } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Contatos > Crie, encontre e consulte contatos. Endereço: https://docs.nextags.com.br/referencia/contatos/ Tipo: Referência Os contatos são as pessoas que falam com a conta, em qualquer canal. Crie um contato a partir do seu sistema, encontre um contato pelo telefone, pelo e-mail ou por um campo personalizado e consulte os dados, as etiquetas e os campos de cada um. O `id` do contato é o `contact_id` que as outras chamadas pedem: veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ## Endpoints - [Criar contato](https://docs.nextags.com.br/referencia/contatos/criar-contato.md): `POST /contacts` - [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato.md): `GET /contacts/{contact_id}` - [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado.md): `GET /contacts/find_by_custom_field` ## O objeto: Contato | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do contato: o `contact_id` das outras chamadas. | | `page_id` | integer | O ID da conta. | | `first_name` | string | O nome. | | `last_name` | string | O sobrenome. | | `channel` | integer | O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok. | | `profile_pic` | string | O endereço da foto de perfil. | | `locale` | string | O idioma do contato, como `pt_BR`. | | `gender` | integer | O gênero: 0 feminino, 1 masculino, 2 desconhecido. | | `timezone` | integer | O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília). | | `last_sent` | integer | Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos. | | `last_delivered` | integer | Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos. | | `last_seen` | integer | Quando o contato foi visto pela última vez (**Visto pela última vez**, no app), em Unix timestamp em milissegundos. | | `last_interaction` | integer | Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos. | | `subscribed_date` | string | Quando o contato entrou na conta, em UTC, no formato `2026-10-12 14:40:00`. | | `subscribed` | integer | 1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja [Contatos que pediram para sair das transmissões](https://help.nextags.com.br/tutoriais/contatos/cancelar-inscricao/). | | `tags` | array de objeto Etiqueta | As etiquetas do contato. | | `tags[].id` | integer | O ID da etiqueta. | | `tags[].name` | string | O nome da etiqueta. | | `custom_fields` | array de objeto Campo personalizado | Os campos personalizados do contato, com o valor de cada um. | | `custom_fields[].id` | integer | O ID do campo. | | `custom_fields[].name` | string | O nome do campo. | | `custom_fields[].type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `custom_fields[].value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792936930000, "last_delivered": 1792936932000, "last_seen": 1792937020000, "last_interaction": 1792936680000, "subscribed_date": "2026-10-12 14:40:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } ``` --- # Criar contato > Cria um contato e, na mesma chamada, roda ações nele: etiquetar, preencher campos e enviar um fluxo. Endereço: https://docs.nextags.com.br/referencia/contatos/criar-contato/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts X-ACCESS-TOKEN: ``` Cria um contato e, na mesma chamada, roda ações nele: etiquetar, preencher campos e enviar um fluxo. O telefone vai completo, com o código do país e o DDD, só com números, como `5511988776655`: veja [O formato certo do telefone](https://help.nextags.com.br/tutoriais/contatos/formato-do-telefone/). Para não criar o mesmo contato duas vezes, procure antes pelo telefone ou pelo e-mail em [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/). Veja [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/). > Se o contato nunca mandou mensagem para a conta, a janela de 24 horas do WhatsApp está fechada: o fluxo da ação `send_flow` precisa começar com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `phone` | string | sim | O telefone com o código do país (DDI) e o DDD, só com números. | | `email` | string | não | O e-mail do contato. | | `first_name` | string | não | O nome. | | `last_name` | string | não | O sobrenome. | | `gender` | string | não | O gênero: `male` (masculino), `female` (feminino) ou `unknown` (desconhecido). Valores: `male`, `female`, `unknown`. | | `actions` | array de objeto Ação | não | Ações para rodar no contato, na ordem da lista: `add_tag`, `set_field_value`, `send_flow` e as outras de [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). | | `actions[].action` | string | sim | Valores: `add_tag`, `remove_tag`, `set_field_value`, `unset_field_value`, `send_flow`, `transfer_conversation_to`, `assign_conversation`, `unassign_conversation`. | | `actions[].tag_name` | string | não | O nome da etiqueta (add_tag, remove_tag). | | `actions[].field_name` | string | não | O nome do campo (set_field_value, unset_field_value). | | `actions[].value` | string | não | O valor do campo (set_field_value) ou human/bot (transfer_conversation_to). | | `actions[].flow_id` | integer ou string | não | O ID do fluxo (send_flow). | | `actions[].admin_id` | integer ou string | não | O ID do administrador (assign_conversation). | ```json { "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "gender": "female", "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" }, { "action": "send_flow", "flow_id": 1000001 } ] } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "gender": "female", "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" }, { "action": "send_flow", "flow_id": 1000001 } ] }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Deu certo: o contato foi criado. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar contato > Devolve um contato, com os dados do perfil, as etiquetas e os campos personalizados. Endereço: https://docs.nextags.com.br/referencia/contatos/consultar-contato/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/contacts/{contact_id} X-ACCESS-TOKEN: ``` Devolve um contato, com os dados do perfil, as etiquetas e os campos personalizados. Vêm o nome, o canal atual, o gênero, o idioma, o fuso, as datas da última mensagem e da última interação e a inscrição. Para achar o ID a partir do telefone ou do e-mail, use [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O contato. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do contato: o `contact_id` das outras chamadas. | | `page_id` | integer | O ID da conta. | | `first_name` | string | O nome. | | `last_name` | string | O sobrenome. | | `channel` | integer | O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok. | | `profile_pic` | string | O endereço da foto de perfil. | | `locale` | string | O idioma do contato, como `pt_BR`. | | `gender` | integer | O gênero: 0 feminino, 1 masculino, 2 desconhecido. | | `timezone` | integer | O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília). | | `last_sent` | integer | Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos. | | `last_delivered` | integer | Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos. | | `last_seen` | integer | Quando o contato foi visto pela última vez (**Visto pela última vez**, no app), em Unix timestamp em milissegundos. | | `last_interaction` | integer | Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos. | | `subscribed_date` | string | Quando o contato entrou na conta, em UTC, no formato `2026-10-12 14:40:00`. | | `subscribed` | integer | 1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja [Contatos que pediram para sair das transmissões](https://help.nextags.com.br/tutoriais/contatos/cancelar-inscricao/). | | `tags` | array de objeto Etiqueta | As etiquetas do contato. | | `tags[].id` | integer | O ID da etiqueta. | | `tags[].name` | string | O nome da etiqueta. | | `custom_fields` | array de objeto Campo personalizado | Os campos personalizados do contato, com o valor de cada um. | | `custom_fields[].id` | integer | O ID do campo. | | `custom_fields[].name` | string | O nome do campo. | | `custom_fields[].type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `custom_fields[].value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792936930000, "last_delivered": 1792936932000, "last_seen": 1792937020000, "last_interaction": 1792936680000, "subscribed_date": "2026-10-12 14:40:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } ``` ### 400 Requisição inválida O `contact_id` não é um ID válido. ### 404 Não encontrado Não existe contato com esse ID nesta conta. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Buscar contato por campo personalizado > Encontra contatos pelo valor de um campo: o telefone, o e-mail ou um campo personalizado. Endereço: https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/contacts/find_by_custom_field X-ACCESS-TOKEN: ``` Encontra contatos pelo valor de um campo: o telefone, o e-mail ou um campo personalizado. Devolve no máximo 100 contatos, os mais recentes primeiro, pela última mudança do campo. É o jeito de achar o `contact_id` de quem você conhece pelo telefone ou pelo e-mail: veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de consulta | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `field_id` | string | sim | Onde procurar: `phone` (telefone), `email` (e-mail) ou o ID de um campo personalizado. | | `value` | string | sim | O valor procurado. O telefone vai completo e só com números, como `5511988776655`. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os contatos encontrados, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Contato | Os contatos, no máximo 100, os mais recentes primeiro. | | `data[].id` | integer | O ID do contato: o `contact_id` das outras chamadas. | | `data[].page_id` | integer | O ID da conta. | | `data[].first_name` | string | O nome. | | `data[].last_name` | string | O sobrenome. | | `data[].channel` | integer | O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok. | | `data[].profile_pic` | string | O endereço da foto de perfil. | | `data[].locale` | string | O idioma do contato, como `pt_BR`. | | `data[].gender` | integer | O gênero: 0 feminino, 1 masculino, 2 desconhecido. | | `data[].timezone` | integer | O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília). | | `data[].last_sent` | integer | Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos. | | `data[].last_delivered` | integer | Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos. | | `data[].last_seen` | integer | Quando o contato foi visto pela última vez (**Visto pela última vez**, no app), em Unix timestamp em milissegundos. | | `data[].last_interaction` | integer | Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos. | | `data[].subscribed_date` | string | Quando o contato entrou na conta, em UTC, no formato `2026-10-12 14:40:00`. | | `data[].subscribed` | integer | 1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja [Contatos que pediram para sair das transmissões](https://help.nextags.com.br/tutoriais/contatos/cancelar-inscricao/). | | `data[].tags` | array de objeto Etiqueta | As etiquetas do contato. | | `data[].tags[].id` | integer | O ID da etiqueta. | | `data[].tags[].name` | string | O nome da etiqueta. | | `data[].custom_fields` | array de objeto Campo personalizado | Os campos personalizados do contato, com o valor de cada um. | | `data[].custom_fields[].id` | integer | O ID do campo. | | `data[].custom_fields[].name` | string | O nome do campo. | | `data[].custom_fields[].type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `data[].custom_fields[].value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "data": [ { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792936930000, "last_delivered": 1792936932000, "last_seen": 1792937020000, "last_interaction": 1792936680000, "subscribed_date": "2026-10-12 14:40:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } ] } ``` ### 400 Requisição inválida Faltou `field_id` ou `value`, ou um deles não vale. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Mensagens > Envie fluxos, textos, arquivos e conteúdos para um contato. Endereço: https://docs.nextags.com.br/referencia/mensagens/ Tipo: Referência Envie conteúdo a um contato a partir do seu sistema: um fluxo pronto, um texto, um arquivo ou várias mensagens com ações numa chamada só. As regras de cada canal valem para a API como para a Caixa de Entrada: no WhatsApp, fora da janela de 24 horas, só sai Modelo de Mensagem aprovado. O formato das mensagens e das ações está em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). ## Endpoints - [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo.md): `POST /contacts/{contact_id}/send/{flow_id}` - [Enviar texto](https://docs.nextags.com.br/referencia/mensagens/enviar-texto.md): `POST /contacts/{contact_id}/send/text` - [Enviar arquivo](https://docs.nextags.com.br/referencia/mensagens/enviar-arquivo.md): `POST /contacts/{contact_id}/send/file` - [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo.md): `POST /contacts/{contact_id}/send_content` ```json { "message": { "text": "Oi! Seu pedido saiu para entrega." } } ``` --- # Enviar fluxo > Envia um fluxo ao contato, como o Enviar Fluxo da Caixa de Entrada: o contato recebe as mensagens e passa pelas ações do fluxo, na versão publicada. Endereço: https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/send/{flow_id} X-ACCESS-TOKEN: ``` Envia um fluxo ao contato, como o **Enviar Fluxo** da Caixa de Entrada: o contato recebe as mensagens e passa pelas ações do fluxo, na versão publicada. É o jeito mais completo de mandar conteúdo pela API, porque o fluxo pode ter botões, perguntas e o Modelo de Mensagem do WhatsApp. O ID do fluxo sai de [Listar fluxos](https://docs.nextags.com.br/referencia/fluxos/listar-fluxos/). Veja [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo/). > No WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, o fluxo precisa começar com um Modelo de Mensagem aprovado: veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/) e [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/). Para o Instagram e o Messenger, veja [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato que recebe. | | `flow_id` | integer | sim | O ID do fluxo. | ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/1000001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O envio do fluxo foi aceito. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Enviar texto > Envia uma mensagem de texto ao contato. Endereço: https://docs.nextags.com.br/referencia/mensagens/enviar-texto/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/send/text X-ACCESS-TOKEN: ``` Envia uma mensagem de texto ao contato. Para mandar mais de uma mensagem, botões ou ações na mesma chamada, use [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Enviar texto, imagem e arquivo](https://docs.nextags.com.br/guias/enviar-texto-e-arquivos/). > No WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) com um fluxo que comece com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e, para o Instagram e o Messenger, [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato que recebe. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto da mensagem. | | `channel` | string | não | Por qual canal a mensagem sai. Valores: `messenger`, `whatsapp`, `webchat`, `telegram`, `instagram`. | ```json { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega.", "channel": "whatsapp" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/text" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega.", "channel": "whatsapp" }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O envio foi aceito. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando a NexTags aceitou o envio. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Enviar arquivo > Envia ao contato uma imagem, um vídeo, um áudio ou um documento, a partir do endereço do arquivo. Endereço: https://docs.nextags.com.br/referencia/mensagens/enviar-arquivo/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/send/file X-ACCESS-TOKEN: ``` Envia ao contato uma imagem, um vídeo, um áudio ou um documento, a partir do endereço do arquivo. Os formatos e os tamanhos aceitos mudam de canal para canal: veja [Tipos de arquivo e limites por canal](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/) e [Enviar texto, imagem e arquivo](https://docs.nextags.com.br/guias/enviar-texto-e-arquivos/). > No WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) com um fluxo que comece com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e, para o Instagram e o Messenger, [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato que recebe. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `url` | string | sim | O endereço público do arquivo, que abra sem login. | | `type` | string | sim | O tipo do arquivo: `image` (imagem), `video` (vídeo), `audio` (áudio) ou `file` (documento). Valores: `file`, `image`, `audio`, `video`. | | `channel` | string | não | Por qual canal o arquivo sai. Valores: `messenger`, `whatsapp`, `telegram`, `instagram`. | ```json { "url": "https://exemplo.com.br/arquivos/catalogo.pdf", "type": "file", "channel": "whatsapp" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/file" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://exemplo.com.br/arquivos/catalogo.pdf", "type": "file", "channel": "whatsapp" }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O envio foi aceito. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando a NexTags aceitou o envio. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Enviar conteúdo > Envia várias mensagens e roda ações no contato, numa chamada só. Endereço: https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/send_content X-ACCESS-TOKEN: ``` Envia várias mensagens e roda ações no contato, numa chamada só. As mensagens (texto, botões, respostas rápidas, mídia e cartões) e as ações (`add_tag`, `set_field_value`, `send_flow` e as outras) seguem o formato de [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/), e a NexTags converte cada mensagem para o canal do contato. No WhatsApp, `messages` aceita também mensagens no formato da API do WhatsApp (lista, localização, contatos), com `"to": null`: a NexTags preenche o número. > No WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) com um fluxo que comece com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e, para o Instagram e o Messenger, [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato que recebe. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `messages` | array de objeto Mensagem | não | As mensagens, na ordem de envio. | | `actions` | array de objeto Ação | não | As ações para rodar no contato, na ordem da lista. | | `actions[].action` | string | sim | Valores: `add_tag`, `remove_tag`, `set_field_value`, `unset_field_value`, `send_flow`, `transfer_conversation_to`, `assign_conversation`, `unassign_conversation`. | | `actions[].tag_name` | string | não | O nome da etiqueta (add_tag, remove_tag). | | `actions[].field_name` | string | não | O nome do campo (set_field_value, unset_field_value). | | `actions[].value` | string | não | O valor do campo (set_field_value) ou human/bot (transfer_conversation_to). | | `actions[].flow_id` | integer ou string | não | O ID do fluxo (send_flow). | | `actions[].admin_id` | integer ou string | não | O ID do administrador (assign_conversation). | | `channel` | string | não | Por qual canal as mensagens saem. Valores: `messenger`, `whatsapp`, `telegram`, `instagram`. | ```json { "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } }, { "message": { "attachment": { "type": "template", "payload": { "template_type": "button", "text": "Quer falar com a equipe?", "buttons": [ { "type": "postback", "title": "Falar com a equipe", "payload": "1000001" } ] } } } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" } ], "channel": "whatsapp" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send_content" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } }, { "message": { "attachment": { "type": "template", "payload": { "template_type": "button", "text": "Quer falar com a equipe?", "buttons": [ { "type": "postback", "title": "Falar com a equipe", "payload": "1000001" } ] } } } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" } ], "channel": "whatsapp" }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O envio foi aceito. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Etiquetas > Etiquetas da conta e dos contatos. Endereço: https://docs.nextags.com.br/referencia/etiquetas/ Tipo: Referência As etiquetas marcam contatos para separar, filtrar e disparar automações, como `cliente-vip` ou `lead-quente`. Crie e consulte as etiquetas da conta e ponha ou tire cada uma de um contato. Na conta, elas ficam em **Fluxos** › **Etiquetas**, e o ID de cada uma sai do menu **⋮** › **Obter ID**: veja [Criar e usar etiquetas](https://help.nextags.com.br/tutoriais/fluxos/etiquetas/). ## Endpoints - [Listar etiquetas](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas.md): `GET /accounts/tags` - [Criar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta.md): `POST /accounts/tags` - [Consultar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/consultar-etiqueta.md): `GET /accounts/tags/{tag_id}` - [Apagar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/apagar-etiqueta.md): `DELETE /accounts/tags/{tag_id}` - [Buscar etiqueta pelo nome](https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome.md): `GET /accounts/tags/name/{tag_name}` - [Listar etiquetas do contato](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas-do-contato.md): `GET /contacts/{contact_id}/tags` - [Adicionar etiqueta ao contato](https://docs.nextags.com.br/referencia/etiquetas/adicionar-etiqueta-ao-contato.md): `POST /contacts/{contact_id}/tags/{tag_id}` - [Remover etiqueta do contato](https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato.md): `DELETE /contacts/{contact_id}/tags/{tag_id}` ## O objeto: Etiqueta | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da etiqueta. | | `name` | string | O nome da etiqueta. | ```json { "id": 2001, "name": "cliente-vip" } ``` --- # Listar etiquetas > Lista as etiquetas da conta, com o ID e o nome de cada uma. Endereço: https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/tags X-ACCESS-TOKEN: ``` Lista as etiquetas da conta, com o ID e o nome de cada uma. Use o ID para pôr ou tirar a etiqueta de um contato. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/tags" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso As etiquetas da conta. Uma lista de Etiqueta. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da etiqueta. | | `name` | string | O nome da etiqueta. | ```json [ { "id": 2001, "name": "cliente-vip" }, { "id": 2002, "name": "lead-quente" } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Criar etiqueta > Cria uma etiqueta na conta e devolve o ID dela. Endereço: https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/accounts/tags X-ACCESS-TOKEN: ``` Cria uma etiqueta na conta e devolve o ID dela. O nome vai em formulário (`application/x-www-form-urlencoded`), não em JSON. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `name` | string | sim | O nome da etiqueta. | ```json { "name": "cliente-vip" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/accounts/tags" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'name=cliente-vip' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A etiqueta criada. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da etiqueta nova. | ```json { "id": 2001 } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar etiqueta > Devolve o nome de uma etiqueta a partir do ID. Endereço: https://docs.nextags.com.br/referencia/etiquetas/consultar-etiqueta/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/tags/{tag_id} X-ACCESS-TOKEN: ``` Devolve o nome de uma etiqueta a partir do ID. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `tag_id` | integer | sim | O ID da etiqueta. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/tags/2001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A etiqueta. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da etiqueta. | | `name` | string | O nome da etiqueta. | ```json { "id": 2001, "name": "cliente-vip" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Apagar etiqueta > Apaga a etiqueta da conta, sem volta. Endereço: https://docs.nextags.com.br/referencia/etiquetas/apagar-etiqueta/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/accounts/tags/{tag_id} X-ACCESS-TOKEN: ``` Apaga a etiqueta da conta, sem volta. Antes, confira os fluxos e os acionadores que usam a etiqueta. Para só tirar a etiqueta de um contato, use [Remover etiqueta do contato](https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `tag_id` | integer | sim | O ID da etiqueta. | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/accounts/tags/2001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A etiqueta foi apagada. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando a etiqueta foi apagada. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Buscar etiqueta pelo nome > Encontra uma etiqueta pelo nome e devolve o ID dela. Endereço: https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/tags/name/{tag_name} X-ACCESS-TOKEN: ``` Encontra uma etiqueta pelo nome e devolve o ID dela. O nome vai no caminho, codificado para URL: `lead quente` vira `lead%20quente`. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `tag_name` | string | sim | O nome da etiqueta, codificado para URL. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A etiqueta. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da etiqueta. | | `name` | string | O nome da etiqueta. | ```json { "id": 2001, "name": "cliente-vip" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar etiquetas do contato > Lista as etiquetas que o contato tem. Endereço: https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas-do-contato/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/contacts/{contact_id}/tags X-ACCESS-TOKEN: ``` Lista as etiquetas que o contato tem. O contato inteiro, com os campos personalizados, sai de [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/tags" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso As etiquetas do contato. Uma lista de Etiqueta. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da etiqueta. | | `name` | string | O nome da etiqueta. | ```json [ { "id": 2001, "name": "cliente-vip" } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Adicionar etiqueta ao contato > Põe a etiqueta no contato, como a ação Adicionar Etiqueta de um fluxo. Endereço: https://docs.nextags.com.br/referencia/etiquetas/adicionar-etiqueta-ao-contato/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/tags/{tag_id} X-ACCESS-TOKEN: ``` Põe a etiqueta no contato, como a ação **Adicionar Etiqueta** de um fluxo. Para usar o nome da etiqueta no lugar do ID, mande a ação `add_tag` em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Etiquetar contatos e preencher campos](https://docs.nextags.com.br/guias/etiquetas-e-campos/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `tag_id` | integer | sim | O ID da etiqueta. | ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A etiqueta foi aplicada. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando a etiqueta foi aplicada. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Remover etiqueta do contato > Tira a etiqueta do contato, como a ação Remover Etiqueta de um fluxo. Endereço: https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/contacts/{contact_id}/tags/{tag_id} X-ACCESS-TOKEN: ``` Tira a etiqueta do contato, como a ação **Remover Etiqueta** de um fluxo. A etiqueta continua na conta. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `tag_id` | integer | sim | O ID da etiqueta. | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A etiqueta foi tirada do contato. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando a etiqueta foi tirada. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Campos personalizados > Campos da conta e os valores de cada contato. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/ Tipo: Referência Os campos personalizados guardam uma informação de cada contato, como a cidade ou o plano de interesse. Crie e consulte os campos da conta e leia, preencha ou limpe o valor de um contato. Na conta, eles ficam em **Fluxos** › **Campo Personalizados**, e o ID de cada um sai do menu **⋮** › **Obter ID**: veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/) e [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/). ## Endpoints - [Listar campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-personalizados.md): `GET /accounts/custom_fields` - [Criar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado.md): `POST /accounts/custom_fields` - [Consultar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/consultar-campo-personalizado.md): `GET /accounts/custom_fields/{custom_field_id}` - [Buscar campo pelo nome](https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome.md): `GET /accounts/custom_fields/name/{custom_field_name}` - [Listar campos do contato](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-do-contato.md): `GET /contacts/{contact_id}/custom_fields` - [Consultar campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/consultar-campo-do-contato.md): `GET /contacts/{contact_id}/custom_fields/{custom_field_id}` - [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato.md): `POST /contacts/{contact_id}/custom_fields/{custom_field_id}` - [Limpar campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/limpar-campo-do-contato.md): `DELETE /contacts/{contact_id}/custom_fields/{custom_field_id}` ## O objeto: Campo personalizado | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo. | | `name` | string | O nome do campo. | | `type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ``` --- # Listar campos personalizados > Lista os campos personalizados da conta. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-personalizados/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/custom_fields X-ACCESS-TOKEN: ``` Lista os campos personalizados da conta. Cada campo traz o ID (`id`), o nome (`name`), o tipo (`type`: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla) e a descrição (`description`). Use o ID para ler ou preencher o valor de um contato. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/custom_fields" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os campos da conta. Uma lista de object. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo. | | `name` | string | O nome do campo. | | `type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. | | `description` | string | A descrição do campo. | ```json [ { "id": 3001, "name": "cidade", "type": 0, "description": "Cidade de entrega" }, { "id": 3002, "name": "data_nascimento", "type": 2, "description": "" } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Criar campo personalizado > Cria um campo personalizado na conta e devolve o ID dele. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/accounts/custom_fields X-ACCESS-TOKEN: ``` Cria um campo personalizado na conta e devolve o ID dele. Pela API, o tipo vai de 0 a 4 (texto, número, data, data e hora e sim/não); texto longo e seleções se criam no app. Com `isBotField: true`, o campo nasce como [campo do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/), com um valor só para a conta toda, que vai em `value`. Use um nome novo: no app, um nome repetido ou reservado é recusado. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `name` | string | sim | O nome do campo, como ele aparece nas listas e nas variáveis das mensagens (`{{cidade}}`). | | `type` | integer | sim | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não. Depois de criado, o campo não muda de tipo. Valores: `0`, `1`, `2`, `3`, `4`. | | `isBotField` | boolean | não | `true` cria um campo do bot (um valor para a conta toda) no lugar de um campo do contato. Padrão: `false`. | | `value` | string | não | O valor do campo do bot, no formato do tipo. Num campo do contato, é ignorado. | | `description` | string | não | Uma descrição, que aparece embaixo do nome na lista de campos. | ```json { "name": "cidade", "type": 0, "description": "Cidade de entrega" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/accounts/custom_fields" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "cidade", "type": 0, "description": "Cidade de entrega" }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O campo criado. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo novo. | | `name` | string | O nome do campo. | ```json { "id": 3001, "name": "cidade" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar campo personalizado > Devolve o nome, o tipo e a descrição de um campo personalizado a partir do ID. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/consultar-campo-personalizado/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/custom_fields/{custom_field_id} X-ACCESS-TOKEN: ``` Devolve o nome, o tipo e a descrição de um campo personalizado a partir do ID. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `custom_field_id` | integer | sim | O ID do campo personalizado. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O campo. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo. | | `name` | string | O nome do campo. | | `type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. | | `description` | string | A descrição do campo. | ```json { "id": 3001, "name": "cidade", "type": 0, "description": "Cidade de entrega" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Buscar campo pelo nome > Encontra um campo personalizado pelo nome e devolve o ID, o tipo e a descrição. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/custom_fields/name/{custom_field_name} X-ACCESS-TOKEN: ``` Encontra um campo personalizado pelo nome e devolve o ID, o tipo e a descrição. O nome vai no caminho, codificado para URL: `data de nascimento` vira `data%20de%20nascimento`. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `custom_field_name` | string | sim | O nome do campo, codificado para URL. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O campo. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo. | | `name` | string | O nome do campo. | | `type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. | | `description` | string | A descrição do campo. | ```json { "id": 3001, "name": "cidade", "type": 0, "description": "Cidade de entrega" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar campos do contato > Lista os campos personalizados do contato, com o valor de cada um. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-do-contato/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/contacts/{contact_id}/custom_fields X-ACCESS-TOKEN: ``` Lista os campos personalizados do contato, com o valor de cada um. O contato inteiro, com as etiquetas, sai de [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os campos do contato, com o valor. Uma lista de Campo personalizado. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo. | | `name` | string | O nome do campo. | | `type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" }, { "id": 3002, "name": "data_nascimento", "type": 2, "value": 642643200 } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar campo do contato > Devolve o valor de um campo personalizado do contato. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/consultar-campo-do-contato/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/contacts/{contact_id}/custom_fields/{custom_field_id} X-ACCESS-TOKEN: ``` Devolve o valor de um campo personalizado do contato. Data e data e hora vêm em Unix timestamp, em segundos; sim/não vem como 1 ou 0. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `custom_field_id` | integer | sim | O ID do campo personalizado. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O campo, com o valor do contato. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo. | | `type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. | | `name` | string | O nome do campo. | | `value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Preencher campo do contato > Grava um valor num campo personalizado do contato, como a ação Definir Campo Personalizado de um fluxo. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/custom_fields/{custom_field_id} X-ACCESS-TOKEN: ``` Grava um valor num campo personalizado do contato, como a ação **Definir Campo Personalizado** de um fluxo. O valor vai em formulário, no formato do tipo do campo: data e data e hora em Unix timestamp (segundos) e sim/não como `1` ou `0`. Para preencher pelo nome do campo no lugar do ID, mande a ação `set_field_value` em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Etiquetar contatos e preencher campos](https://docs.nextags.com.br/guias/etiquetas-e-campos/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `custom_field_id` | string | sim | O ID do campo personalizado. | ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `value` | string | sim | O valor, no formato do tipo do campo. | ```json { "value": "São Paulo" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'value=São Paulo' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O valor foi gravado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando o valor foi gravado. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Limpar campo do contato > Apaga o valor de um campo personalizado do contato, como a ação Limpar Campo Personalizado de um fluxo. Endereço: https://docs.nextags.com.br/referencia/campos-personalizados/limpar-campo-do-contato/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/contacts/{contact_id}/custom_fields/{custom_field_id} X-ACCESS-TOKEN: ``` Apaga o valor de um campo personalizado do contato, como a ação **Limpar Campo Personalizado** de um fluxo. O campo continua na conta. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `custom_field_id` | integer | sim | O ID do campo personalizado. | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O valor foi apagado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando o valor foi apagado. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Campos do bot > Valores globais da conta, iguais para todos os contatos. Endereço: https://docs.nextags.com.br/referencia/campos-do-bot/ Tipo: Referência O campo do bot guarda um valor só para a conta toda, igual para todos os contatos, como o horário de atendimento ou a chave PIX. Leia, troque ou apague esse valor pelo ID do campo. O campo se cria em **Fluxos** › **Campo Personalizados**, na seção **Campo Personalizados do Bot** (ou pela API, em [Criar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/) com `isBotField: true`), e o ID sai do menu **⋮** › **Obter ID**. Veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/). ## Endpoints - [Consultar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/consultar-campo-do-bot.md): `GET /accounts/bot_fields/{bot_field_id}` - [Preencher campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot.md): `POST /accounts/bot_fields/{bot_field_id}` - [Limpar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/limpar-campo-do-bot.md): `DELETE /accounts/bot_fields/{bot_field_id}` --- # Consultar campo do bot > Devolve o nome, o tipo e o valor de um campo do bot. Endereço: https://docs.nextags.com.br/referencia/campos-do-bot/consultar-campo-do-bot/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/bot_fields/{bot_field_id} X-ACCESS-TOKEN: ``` Devolve o nome, o tipo e o valor de um campo do bot. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `bot_field_id` | integer | sim | O ID do campo do bot. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/bot_fields/3101" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O campo do bot, com o valor. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo do bot. | | `type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo. | | `name` | string | O nome do campo. | | `value` | string ou number | O valor, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "id": 3101, "name": "Horário de atendimento", "type": 0, "value": "Seg a sex, das 9h às 18h" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Preencher campo do bot > Troca o valor de um campo do bot: todos os fluxos que usam o campo passam a mostrar o valor novo. Endereço: https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/accounts/bot_fields/{bot_field_id} X-ACCESS-TOKEN: ``` Troca o valor de um campo do bot: todos os fluxos que usam o campo passam a mostrar o valor novo. Use quando o valor vem de outro sistema, como o preço do dia ou o cupom da semana. O valor vai em formulário, no formato do tipo do campo: data e data e hora em Unix timestamp (segundos) e sim/não como `1` ou `0`. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `bot_field_id` | integer | sim | O ID do campo do bot. | ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `value` | string | sim | O valor novo, no formato do tipo do campo. | ```json { "value": "Seg a sex, das 9h às 18h" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/accounts/bot_fields/3101" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'value=Seg a sex, das 9h às 18h' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O valor foi gravado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando o valor foi gravado. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Limpar campo do bot > Apaga o valor de um campo do bot. Endereço: https://docs.nextags.com.br/referencia/campos-do-bot/limpar-campo-do-bot/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/accounts/bot_fields/{bot_field_id} X-ACCESS-TOKEN: ``` Apaga o valor de um campo do bot. O campo continua na conta, sem valor. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `bot_field_id` | integer | sim | O ID do campo do bot. | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/accounts/bot_fields/3101" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O valor foi apagado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando o valor foi apagado. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Fluxos e modelos > Liste os fluxos e instale modelos prontos. Endereço: https://docs.nextags.com.br/referencia/fluxos/ Tipo: Referência Liste os fluxos da conta para pegar o ID que [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) e a ação `send_flow` pedem, e instale modelos prontos: os pacotes de **Templates**, montados em **Ferramentas** › **Templates**, com fluxos, pipelines, agentes de IA e outros itens de uma conta. Os Templates não têm relação com o Modelo de Mensagem do WhatsApp. Veja [Templates: copiar conteúdo entre contas](https://help.nextags.com.br/tutoriais/ferramentas/templates/). ## Endpoints - [Listar fluxos](https://docs.nextags.com.br/referencia/fluxos/listar-fluxos.md): `GET /accounts/flows` - [Instalar modelo na conta](https://docs.nextags.com.br/referencia/fluxos/instalar-modelo-na-conta.md): `POST /accounts/templates/{template_id}/install` - [Gerar link de uso único do modelo](https://docs.nextags.com.br/referencia/fluxos/gerar-link-de-uso-unico-do-modelo.md): `POST /accounts/templates/{template_id}/generateSingleUseLink` --- # Listar fluxos > Lista os fluxos da conta, com o ID e o nome de cada um. Endereço: https://docs.nextags.com.br/referencia/fluxos/listar-fluxos/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/accounts/flows X-ACCESS-TOKEN: ``` Lista os fluxos da conta, com o ID e o nome de cada um. Use o ID em [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) e na ação `send_flow`. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/accounts/flows" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os fluxos da conta. Uma lista de object. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do fluxo. | | `name` | string | O nome do fluxo. | ```json [ { "id": 1000001, "name": "Boas-vindas" }, { "id": 1000002, "name": "Recuperar carrinho" } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Instalar modelo na conta > Instala um modelo de Templates na conta dona da chave de API, sem abrir o link de instalação. Endereço: https://docs.nextags.com.br/referencia/fluxos/instalar-modelo-na-conta/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/accounts/templates/{template_id}/install X-ACCESS-TOKEN: ``` Instala um modelo de **Templates** na conta dona da chave de API, sem abrir o link de instalação. O ID e a chave saem do link que o **Obter Link** copia, em **Ferramentas** › **Templates** › **⋮**: ele termina em `store/template?id=9001&key=b7Xk29QpLm4R`, e o `id` vai no caminho e o `key` vai em `template_key`. No app, a conta que criou o modelo não pode instalá-lo. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `template_id` | integer | sim | O ID do modelo: o `id` do link de instalação. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `template_key` | string | sim | A chave do modelo: o `key` do link de instalação. | ```json { "template_key": "b7Xk29QpLm4R" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/accounts/templates/9001/install" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "template_key": "b7Xk29QpLm4R" }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O modelo foi instalado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando o modelo foi instalado. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Gerar link de uso único do modelo > Gera um link de instalação do modelo que vale para um uso só. Endereço: https://docs.nextags.com.br/referencia/fluxos/gerar-link-de-uso-unico-do-modelo/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/accounts/templates/{template_id}/generateSingleUseLink X-ACCESS-TOKEN: ``` Gera um link de instalação do modelo que vale para um uso só. Use para entregar o modelo a uma pessoa sem passar o link fixo do **Obter Link**. O `template_id` é o `id` do link de instalação: veja [Instalar modelo na conta](https://docs.nextags.com.br/referencia/fluxos/instalar-modelo-na-conta/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `template_id` | integer | sim | O ID do modelo: o `id` do link de instalação. | ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/accounts/templates/9001/generateSingleUseLink" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O link gerado. | Campo | Tipo | Descrição | |---|---|---| | `link` | string | O link de instalação, de uso único. | ```json { "link": "https://app.nextagsai.com.br/store/template?id=9001&key=Q4mZ81xTr6Wd" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Pipelines e oportunidades > Pipelines, etapas, oportunidades e comentários do CRM. Endereço: https://docs.nextags.com.br/referencia/pipelines/ Tipo: Referência O CRM em quadro da NexTags: cada pipeline tem etapas (as colunas) e oportunidades (os cartões), com o contato, o valor, o estado, a prioridade e os responsáveis. Use estas chamadas para levar ao pipeline as vendas e os atendimentos do seu sistema, mudar os cartões de etapa, fechar como ganho ou perdido e registrar comentários. O passo a passo está no guia [Criar e mover oportunidades no pipeline](https://docs.nextags.com.br/guias/oportunidades-no-pipeline/); a tela, em [O que é um pipeline](https://help.nextags.com.br/tutoriais/pipelines/o-que-e-um-pipeline/). ## Endpoints - [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines.md): `GET /pipelines` - [Consultar pipeline](https://docs.nextags.com.br/referencia/pipelines/consultar-pipeline.md): `GET /pipelines/{pipeline_id}` - [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline.md): `GET /pipelines/{pipeline_id}/stages` - [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline.md): `GET /pipelines/{pipeline_id}/custom_fields` - [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades.md): `GET /pipelines/{pipeline_id}/opportunities` - [Criar oportunidade](https://docs.nextags.com.br/referencia/pipelines/criar-oportunidade.md): `POST /pipelines/{pipeline_id}/opportunities` - [Consultar oportunidade](https://docs.nextags.com.br/referencia/pipelines/consultar-oportunidade.md): `GET /pipelines/{pipeline_id}/opportunities/{opportunity_id}` - [Atualizar oportunidade](https://docs.nextags.com.br/referencia/pipelines/atualizar-oportunidade.md): `POST /pipelines/{pipeline_id}/opportunities/{opportunity_id}` - [Apagar oportunidade](https://docs.nextags.com.br/referencia/pipelines/apagar-oportunidade.md): `DELETE /pipelines/{pipeline_id}/opportunities/{opportunity_id}` - [Transferir oportunidade de pipeline](https://docs.nextags.com.br/referencia/pipelines/transferir-oportunidade-de-pipeline.md): `POST /pipelines/{pipeline_id}/opportunities/{opportunity_id}/transfer-to-pipeline` - [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade.md): `GET /pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments` - [Comentar na oportunidade](https://docs.nextags.com.br/referencia/pipelines/comentar-na-oportunidade.md): `POST /pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments` - [Apagar comentário](https://docs.nextags.com.br/referencia/pipelines/apagar-comentario.md): `DELETE /pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments/{comment_id}` ## O objeto: Oportunidade | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da oportunidade. | | `contact_id` | integer | O ID do contato. | | `title` | string | O nome da oportunidade. | | `description` | string | A descrição. | | `value` | number | O valor, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00. | | `status` | string | O estado: `open` (Aberto), `won` (Ganho; Resolvido nos pipelines de suporte e nos personalizados) ou `lost` (Perdido; Não Resolvido). Valores: `open`, `won`, `lost`. | | `priority` | string | A prioridade: `low` (Baixa), `medium` (Média) ou `high` (Alta). Valores: `low`, `medium`, `high`. | | `stage` | object | A etapa onde a oportunidade está. | | `stage.id` | integer | O ID da etapa. | | `stage.name` | string | O nome da etapa. | | `assigned_admins` | array de integer | Os IDs dos administradores atribuídos. | | `created_at` | string | Quando a oportunidade foi criada, em UTC. | | `created_by` | integer | O ID do administrador que criou. | | `updated_at` | string | A última mudança, em UTC. | | `updated_by` | integer | O ID do administrador que fez a última mudança. | ```json { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } ``` --- # Listar pipelines > Lista os pipelines da conta, com o ID e o nome de cada um. Endereço: https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/pipelines X-ACCESS-TOKEN: ``` Lista os pipelines da conta, com o ID e o nome de cada um. É daqui que sai o `pipeline_id` das outras chamadas. A lista vem em páginas: ande por ela com `offset` e `limit`. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de consulta | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `offset` | integer | não | Quantos registros pular antes do primeiro da página. Comece em 0 e some o `limit` a cada página. Padrão: `0`. | | `limit` | integer | não | Quantos registros trazer por página. Padrão: `100`. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/pipelines" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os pipelines, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Pipeline | A lista de pipelines. | | `data[].id` | integer | O ID do pipeline. | | `data[].name` | string | O nome do pipeline. | ```json { "data": [ { "id": 4001, "name": "Funil de vendas" }, { "id": 4002, "name": "Onboarding de clientes" } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar pipeline > Devolve um pipeline pelo ID: o ID e o nome. Endereço: https://docs.nextags.com.br/referencia/pipelines/consultar-pipeline/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/pipelines/{pipeline_id} X-ACCESS-TOKEN: ``` Devolve um pipeline pelo ID: o ID e o nome. As colunas do quadro vêm em [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O pipeline. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do pipeline. | | `name` | string | O nome do pipeline. | ```json { "id": 4001, "name": "Funil de vendas" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar etapas do pipeline > Lista as etapas do pipeline (as colunas do quadro), com o ID e o nome de cada uma. Endereço: https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/stages X-ACCESS-TOKEN: ``` Lista as etapas do pipeline (as colunas do quadro), com o ID e o nome de cada uma. O ID da etapa vai em `stage_id`, para criar a oportunidade numa etapa ou mudá-la de etapa, e em `target_stage_id`, para transferir. Veja [Etapas: criar, ordenar e configurar](https://help.nextags.com.br/tutoriais/pipelines/etapas/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/stages" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso As etapas, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Etapa do pipeline | A lista de etapas. | | `data[].id` | integer | O ID da etapa: o `stage_id` das oportunidades. | | `data[].name` | string | O nome da etapa. | ```json { "data": [ { "id": 4101, "name": "Novo lead" }, { "id": 4102, "name": "Proposta enviada" }, { "id": 4103, "name": "Fechamento" } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar campos do pipeline > Lista os campos do pipeline: os campos próprios das oportunidades, criados nas definições do pipeline em Campo Personalizados. Endereço: https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/custom_fields X-ACCESS-TOKEN: ``` Lista os campos do pipeline: os campos próprios das oportunidades, criados nas definições do pipeline em **Campo Personalizados**. Não são os campos personalizados do contato. Use o `id` ou o `name` deles em `custom_fields`, ao criar ou atualizar uma oportunidade. Veja [Comentários, anexos e campos do pipeline](https://help.nextags.com.br/tutoriais/pipelines/comentarios-e-anexos/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/custom_fields" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A lista de campos, sem `data` em volta. Uma lista de object. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do campo. | | `name` | string | O **Nome** do campo, como aparece na oportunidade. | | `type` | integer ou string | O código do tipo, como na tela: 0 Texto, 1 Número, 2 Data, 3 Data e hora, 4 Verdadeiro/Falso, 6 Seleção única e 7 Seleção múltipla. | | `description` | string | A descrição do campo. A tela não pede descrição ao criar o campo. | ```json [ { "id": 3201, "name": "Origem do lead", "type": 0, "description": "" }, { "id": 3202, "name": "Previsão de fechamento", "type": 2, "description": "" } ] ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar oportunidades > Lista as oportunidades de um pipeline, em páginas (offset e limit). Endereço: https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities X-ACCESS-TOKEN: ``` Lista as oportunidades de um pipeline, em páginas (`offset` e `limit`). Com `contact_id`, traz só as de um contato: o jeito de saber se o cliente já tem uma oportunidade aberta antes de criar outra. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | ## Parâmetros de consulta | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | number | não | O ID de um contato: traz só as oportunidades dele. | | `offset` | integer | não | Quantos registros pular antes do primeiro da página. Comece em 0 e some o `limit` a cada página. Padrão: `0`. | | `limit` | integer | não | Quantos registros trazer por página. Padrão: `100`. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities?contact_id=123456789" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso As oportunidades, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Oportunidade | A lista de oportunidades. | | `data[].id` | integer | O ID da oportunidade. | | `data[].contact_id` | integer | O ID do contato. | | `data[].title` | string | O nome da oportunidade. | | `data[].description` | string | A descrição. | | `data[].value` | number | O valor, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00. | | `data[].status` | string | O estado: `open` (Aberto), `won` (Ganho; Resolvido nos pipelines de suporte e nos personalizados) ou `lost` (Perdido; Não Resolvido). Valores: `open`, `won`, `lost`. | | `data[].priority` | string | A prioridade: `low` (Baixa), `medium` (Média) ou `high` (Alta). Valores: `low`, `medium`, `high`. | | `data[].stage` | object | A etapa onde a oportunidade está. | | `data[].stage.id` | integer | O ID da etapa. | | `data[].stage.name` | string | O nome da etapa. | | `data[].assigned_admins` | array de integer | Os IDs dos administradores atribuídos. | | `data[].created_at` | string | Quando a oportunidade foi criada, em UTC. | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].updated_at` | string | A última mudança, em UTC. | | `data[].updated_by` | integer | O ID do administrador que fez a última mudança. | ```json { "data": [ { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Criar oportunidade > Cria uma oportunidade (ou um ticket, nos pipelines de suporte) para um contato. Endereço: https://docs.nextags.com.br/referencia/pipelines/criar-oportunidade/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities X-ACCESS-TOKEN: ``` Cria uma oportunidade (ou um ticket, nos pipelines de suporte) para um contato. Sem `stage_id`, ela entra na primeira etapa do pipeline. Os IDs vêm de [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/), [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores/) e [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/). Veja o guia [Criar e mover oportunidades no pipeline](https://docs.nextags.com.br/guias/oportunidades-no-pipeline/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato dono da oportunidade. | | `title` | string | sim | O nome da oportunidade (o **Nome da Oportunidade** da tela), como "Plano Pro anual". | | `description` | string | não | A descrição (a **Descrição da Oportunidade**). | | `stage_id` | integer | não | O ID da etapa onde a oportunidade entra. Sem ele, a primeira etapa do pipeline. | | `value` | number | não | O **Valor da Oportunidade**, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00. Padrão: `0`. | | `status` | string | não | O **Estado**: `open` (Aberto), `won` (Ganho) ou `lost` (Perdido). Nos pipelines de suporte e nos personalizados, `won` aparece como **Resolvido** e `lost` como **Não Resolvido**. Valores: `open`, `won`, `lost`. Padrão: `open`. | | `priority` | string | não | A **Prioridade**: `low` (Baixa), `medium` (Média) ou `high` (Alta). Valores: `low`, `medium`, `high`. Padrão: `medium`. | | `assigned_admins` | array de integer | não | Os **Administradores atribuídos**: uma lista de IDs de administradores (veja [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores/)). Padrão: `[]`. | | `custom_fields` | array de object | não | Os valores dos campos do pipeline (veja [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/)). Cada item leva o `id` ou o `name` do campo e o `value`. | | `custom_fields[].id` | integer | não | O ID do campo do pipeline. | | `custom_fields[].name` | string | não | O nome do campo do pipeline, no lugar do `id`. | | `custom_fields[].value` | string ou number | não | O valor do campo: texto ou número, conforme o tipo. | ```json { "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "stage_id": 4101, "value": 1500, "status": "open", "priority": "high", "assigned_admins": [ 10001 ], "custom_fields": [ { "id": 3201, "value": "Anúncio no Instagram" } ] } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "stage_id": 4101, "value": 1500, "status": "open", "priority": "high", "assigned_admins": [ 10001 ], "custom_fields": [ { "id": 3201, "value": "Anúncio no Instagram" } ] }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A oportunidade criada, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Oportunidade | Uma lista com a oportunidade criada. | | `data[].id` | integer | O ID da oportunidade. | | `data[].contact_id` | integer | O ID do contato. | | `data[].title` | string | O nome da oportunidade. | | `data[].description` | string | A descrição. | | `data[].value` | number | O valor, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00. | | `data[].status` | string | O estado: `open` (Aberto), `won` (Ganho; Resolvido nos pipelines de suporte e nos personalizados) ou `lost` (Perdido; Não Resolvido). Valores: `open`, `won`, `lost`. | | `data[].priority` | string | A prioridade: `low` (Baixa), `medium` (Média) ou `high` (Alta). Valores: `low`, `medium`, `high`. | | `data[].stage` | object | A etapa onde a oportunidade está. | | `data[].stage.id` | integer | O ID da etapa. | | `data[].stage.name` | string | O nome da etapa. | | `data[].assigned_admins` | array de integer | Os IDs dos administradores atribuídos. | | `data[].created_at` | string | Quando a oportunidade foi criada, em UTC. | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].updated_at` | string | A última mudança, em UTC. | | `data[].updated_by` | integer | O ID do administrador que fez a última mudança. | ```json { "data": [ { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar oportunidade > Devolve uma oportunidade: o contato, o título, o valor, o estado, a prioridade, a etapa, os responsáveis e as datas. Endereço: https://docs.nextags.com.br/referencia/pipelines/consultar-oportunidade/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities/{opportunity_id} X-ACCESS-TOKEN: ``` Devolve uma oportunidade: o contato, o título, o valor, o estado, a prioridade, a etapa, os responsáveis e as datas. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | | `opportunity_id` | integer | sim | O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)). | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A oportunidade. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID da oportunidade. | | `contact_id` | integer | O ID do contato. | | `title` | string | O nome da oportunidade. | | `description` | string | A descrição. | | `value` | number | O valor, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00. | | `status` | string | O estado: `open` (Aberto), `won` (Ganho; Resolvido nos pipelines de suporte e nos personalizados) ou `lost` (Perdido; Não Resolvido). Valores: `open`, `won`, `lost`. | | `priority` | string | A prioridade: `low` (Baixa), `medium` (Média) ou `high` (Alta). Valores: `low`, `medium`, `high`. | | `stage` | object | A etapa onde a oportunidade está. | | `stage.id` | integer | O ID da etapa. | | `stage.name` | string | O nome da etapa. | | `assigned_admins` | array de integer | Os IDs dos administradores atribuídos. | | `created_at` | string | Quando a oportunidade foi criada, em UTC. | | `created_by` | integer | O ID do administrador que criou. | | `updated_at` | string | A última mudança, em UTC. | | `updated_by` | integer | O ID do administrador que fez a última mudança. | ```json { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Atualizar oportunidade > Muda uma oportunidade: o título, a descrição, a etapa, o valor, o estado, a prioridade, os responsáveis e os campos do pipeline. Endereço: https://docs.nextags.com.br/referencia/pipelines/atualizar-oportunidade/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities/{opportunity_id} X-ACCESS-TOKEN: ``` Muda uma oportunidade: o título, a descrição, a etapa, o valor, o estado, a prioridade, os responsáveis e os campos do pipeline. Para mudar de etapa, mande o `stage_id` novo; para fechar, o `status` com `won` (ganha) ou `lost` (perdida); para reabrir, `open`. O `title` vai sempre, mesmo quando não muda. Veja [Valor, prioridade, vencimento e responsáveis](https://help.nextags.com.br/tutoriais/pipelines/campos-do-card/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | | `opportunity_id` | integer | sim | O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)). | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `title` | string | sim | O nome da oportunidade. Vai sempre: mande o atual quando não for mudar. | | `description` | string | não | A descrição (a **Descrição da Oportunidade**). | | `stage_id` | integer | não | O ID da etapa para onde a oportunidade vai. | | `value` | number | não | O **Valor da Oportunidade**, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00. Padrão: `0`. | | `status` | string | não | O **Estado**: `open` (Aberto), `won` (Ganho) ou `lost` (Perdido). Nos pipelines de suporte e nos personalizados, `won` aparece como **Resolvido** e `lost` como **Não Resolvido**. Valores: `open`, `won`, `lost`. Padrão: `open`. | | `priority` | string | não | A **Prioridade**: `low` (Baixa), `medium` (Média) ou `high` (Alta). Valores: `low`, `medium`, `high`. Padrão: `medium`. | | `assigned_admins` | array de integer | não | Os **Administradores atribuídos**: uma lista de IDs de administradores (veja [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores/)). Padrão: `[]`. | | `custom_fields` | array de object | não | Os valores dos campos do pipeline (veja [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/)). Cada item leva o `id` ou o `name` do campo e o `value`. | | `custom_fields[].id` | integer | não | O ID do campo do pipeline. | | `custom_fields[].name` | string | não | O nome do campo do pipeline, no lugar do `id`. | | `custom_fields[].value` | string ou number | não | O valor do campo: texto ou número, conforme o tipo. | ```json { "title": "Plano Pro anual", "stage_id": 4103, "status": "won", "value": 1800, "custom_fields": [ { "name": "Origem do lead", "value": "Indicação" } ] } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Plano Pro anual", "stage_id": 4103, "status": "won", "value": 1800, "custom_fields": [ { "name": "Origem do lead", "value": "Indicação" } ] }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A oportunidade foi atualizada. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Apagar oportunidade > Apaga a oportunidade do pipeline, como o Excluir do menu do cartão. Endereço: https://docs.nextags.com.br/referencia/pipelines/apagar-oportunidade/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities/{opportunity_id} X-ACCESS-TOKEN: ``` Apaga a oportunidade do pipeline, como o **Excluir** do menu do cartão. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | | `opportunity_id` | integer | sim | O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)). | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A oportunidade foi apagada. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Transferir oportunidade de pipeline > Leva a oportunidade para outro pipeline, numa etapa escolhida, como o Transferir para o Pipeline do cartão. Endereço: https://docs.nextags.com.br/referencia/pipelines/transferir-oportunidade-de-pipeline/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities/{opportunity_id}/transfer-to-pipeline X-ACCESS-TOKEN: ``` Leva a oportunidade para outro pipeline, numa etapa escolhida, como o **Transferir para o Pipeline** do cartão. A etapa é do pipeline de destino: pegue o ID dela em [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/), com o ID do pipeline novo. Veja [Oportunidades e tickets](https://help.nextags.com.br/tutoriais/pipelines/oportunidades/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline onde a oportunidade está agora. | | `opportunity_id` | integer | sim | O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)). | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `target_pipeline_id` | integer | sim | O ID do pipeline de destino. | | `target_stage_id` | integer | sim | O ID da etapa do pipeline de destino onde a oportunidade entra. | ```json { "target_pipeline_id": 4002, "target_stage_id": 4111 } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "target_pipeline_id": 4002, "target_stage_id": 4111 }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A oportunidade mudou de pipeline. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar comentários da oportunidade > Lista os comentários de uma oportunidade (a seção Comentários do cartão), em páginas (offset e limit). Endereço: https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments X-ACCESS-TOKEN: ``` Lista os comentários de uma oportunidade (a seção **Comentários** do cartão), em páginas (`offset` e `limit`). Veja [Comentários, anexos e campos do pipeline](https://help.nextags.com.br/tutoriais/pipelines/comentarios-e-anexos/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | | `opportunity_id` | integer | sim | O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)). | ## Parâmetros de consulta | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `offset` | integer | não | Quantos registros pular antes do primeiro da página. Comece em 0 e some o `limit` a cada página. Padrão: `0`. | | `limit` | integer | não | Quantos registros trazer por página. Padrão: `100`. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os comentários, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Comentário da oportunidade | A lista de comentários. | | `data[].id` | integer | O ID do comentário. | | `data[].data` | string | O texto do comentário. | | `data[].created_at` | string | Quando o comentário foi escrito, em UTC. | | `data[].created_by` | integer | O ID do administrador que escreveu. | ```json { "data": [ { "id": 4301, "data": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.", "created_at": "2026-10-21 13:15:00", "created_by": 10001 } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Comentar na oportunidade > Escreve um comentário na oportunidade, como o Adicionar Comentário do cartão. Endereço: https://docs.nextags.com.br/referencia/pipelines/comentar-na-oportunidade/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments X-ACCESS-TOKEN: ``` Escreve um comentário na oportunidade, como o **Adicionar Comentário** do cartão. Serve para registrar no pipeline o que aconteceu no seu sistema, como uma proposta enviada ou um pagamento. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | | `opportunity_id` | integer | sim | O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)). | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `content` | string | sim | O texto do comentário. | ```json { "content": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto." } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto." }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O comentário criado. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do comentário. | | `data` | string | O texto do comentário. | | `created_at` | string | Quando o comentário foi escrito, em UTC. | | `created_by` | integer | O ID do administrador que escreveu. | ```json { "id": 4301, "data": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.", "created_at": "2026-10-21 13:15:00", "created_by": 10001 } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Apagar comentário > Apaga um comentário da oportunidade, como o Excluir do menu do comentário. Endereço: https://docs.nextags.com.br/referencia/pipelines/apagar-comentario/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments/{comment_id} X-ACCESS-TOKEN: ``` Apaga um comentário da oportunidade, como o **Excluir** do menu do comentário. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `pipeline_id` | integer | sim | O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)). | | `opportunity_id` | integer | sim | O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)). | | `comment_id` | integer | sim | O ID do comentário (veja [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/)). | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments/4301" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O comentário foi apagado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Agentes de IA > Agentes, funções, servidores MCP, arquivos e histórico da IA. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/ Tipo: Referência Os agentes de IA do **AI Hub**: as instruções e os modelos com que a IA responde os contatos, usando o provedor conectado na conta (OpenAI, Gemini, Claude, xAI ou DeepSeek). Pela API, você lista e consulta os agentes, troca a mensagem do sistema, o limite de tokens e os modelos, lista as funções, os servidores MCP e os arquivos, e põe mensagens no histórico da IA de um contato. Veja o guia [Agentes de IA pela API](https://docs.nextags.com.br/guias/agentes-de-ia-pela-api/) e [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/). ## Endpoints - [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia.md): `GET /agents/` - [Consultar agente de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/consultar-agente-de-ia.md): `GET /agents/{agent_id}` - [Atualizar agente de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/atualizar-agente-de-ia.md): `POST /agents/{agent_id}` - [Listar funções dos agentes](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-funcoes-dos-agentes.md): `GET /agents/functions` - [Listar servidores MCP](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-servidores-mcp.md): `GET /agents/mcp` - [Listar arquivos dos agentes](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-arquivos-dos-agentes.md): `GET /agents/files` - [Salvar mensagens no histórico da IA](https://docs.nextags.com.br/referencia/agentes-de-ia/salvar-mensagens-no-historico-da-ia.md): `POST /contacts/{contact_id}/ai/save_messages` ## O objeto: Agente de IA | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do agente. | | `name` | string | O nome do agente, como aparece na lista do AI Hub. | | `created_by` | integer | O ID do administrador que criou. | | `created_at` | string (data e hora) | Quando o agente foi criado, em UTC. | ```json { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" } ``` --- # Listar agentes de IA > Lista os agentes de IA da conta (a aba Agentes de IA do AI Hub), com o ID e o nome de cada um. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/agents/ X-ACCESS-TOKEN: ``` Lista os agentes de IA da conta (a aba **Agentes de IA** do AI Hub), com o ID e o nome de cada um. O endereço termina com barra: `/agents/`. Veja [Conheça o AI Hub](https://help.nextags.com.br/tutoriais/ia/ia-hub/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/agents/" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os agentes, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Agente de IA | A lista de agentes (até 100). | | `data[].id` | integer | O ID do agente. | | `data[].name` | string | O nome do agente, como aparece na lista do AI Hub. | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].created_at` | string (data e hora) | Quando o agente foi criado, em UTC. | ```json { "data": [ { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" }, { "id": 5002, "name": "Suporte pós-venda", "created_by": 10001, "created_at": "2026-10-02 17:45:00" } ] } ``` ### 400 Requisição inválida Parâmetros inválidos. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar agente de IA > Devolve um agente de IA pelo ID: o nome, quem criou e quando. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/consultar-agente-de-ia/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/agents/{agent_id} X-ACCESS-TOKEN: ``` Devolve um agente de IA pelo ID: o nome, quem criou e quando. Veja [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `agent_id` | integer | sim | O ID do agente (veja [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/)). | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/agents/5001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O agente. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do agente. | | `name` | string | O nome do agente, como aparece na lista do AI Hub. | | `created_by` | integer | O ID do administrador que criou. | | `created_at` | string (data e hora) | Quando o agente foi criado, em UTC. | ```json { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Atualizar agente de IA > Muda a configuração de um agente: a Mensagem do sistema (Prompt), o Max tokens e o modelo de cada provedor. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/atualizar-agente-de-ia/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/agents/{agent_id} X-ACCESS-TOKEN: ``` Muda a configuração de um agente: a **Mensagem do sistema (Prompt)**, o **Max tokens** e o modelo de cada provedor. Os três campos são opcionais. Veja [Escrever a mensagem do sistema](https://help.nextags.com.br/tutoriais/ia/escrever-o-prompt/) e [Modelo, temperatura e limite de tokens](https://help.nextags.com.br/tutoriais/ia/modelo-e-parametros/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `agent_id` | integer | sim | O ID do agente (veja [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/)). | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `prompt` | string | não | A **Mensagem do sistema (Prompt)**: as instruções que o agente segue em todas as respostas. O texto novo substitui o atual. | | `max_output_tokens` | integer | não | O **Max tokens**: o tamanho máximo de cada resposta, em tokens. Na tela, de 1 a 32768; o agente novo vem com 2048. | | `model` | object | não | O modelo de cada provedor, os campos **Modelo (OpenAI)**, **Modelo (Gemini)**, **Modelo (Claude)**, **Modelo (xAI)** e **Modelo (DeepSeek)** dos ajustes do agente. Use o nome do modelo como o provedor chama; os exemplos são os modelos com que um agente novo começa. Mande os cinco, mesmo os de provedores que a conta não usa. | | `model.openAI` | string | sim | O modelo da OpenAI, como `gpt-6-luna`. | | `model.gemini` | string | sim | O modelo do Google Gemini, com o prefixo `models/`, como `models/gemini-3.5-flash-lite`. | | `model.claude` | string | sim | O modelo do Claude, como `claude-haiku-4-5-20251001`. | | `model.xAI` | string | sim | O modelo do xAI, como `grok-4.3`. | | `model.deepseek` | string | sim | O modelo do DeepSeek, como `deepseek-v4-flash`. | ```json { "prompt": "Você é a Bia, atendente da Loja Exemplo. Responda em português, em até 3 frases. Quando o cliente pedir troca, passe para a equipe.", "max_output_tokens": 2048, "model": { "openAI": "gpt-6-luna", "gemini": "models/gemini-3.5-flash-lite", "claude": "claude-haiku-4-5-20251001", "xAI": "grok-4.3", "deepseek": "deepseek-v4-flash" } } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/agents/5001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Você é a Bia, atendente da Loja Exemplo. Responda em português, em até 3 frases. Quando o cliente pedir troca, passe para a equipe.", "max_output_tokens": 2048, "model": { "openAI": "gpt-6-luna", "gemini": "models/gemini-3.5-flash-lite", "claude": "claude-haiku-4-5-20251001", "xAI": "grok-4.3", "deepseek": "deepseek-v4-flash" } }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O agente, depois da mudança. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do agente. | | `name` | string | O nome do agente, como aparece na lista do AI Hub. | | `created_by` | integer | O ID do administrador que criou. | | `created_at` | string (data e hora) | Quando o agente foi criado, em UTC. | ```json { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" } ``` ### 400 Requisição inválida A mudança não foi aceita: confira os campos do corpo. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar funções dos agentes > Lista as Funções de IA da conta (AI Hub › Ferramentas de IA): as tarefas que o agente executa durante a conversa, como coletar dados e acionar um fluxo. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/listar-funcoes-dos-agentes/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/agents/functions X-ACCESS-TOKEN: ``` Lista as **Funções de IA** da conta (AI Hub › **Ferramentas de IA**): as tarefas que o agente executa durante a conversa, como coletar dados e acionar um fluxo. Cada função é ligada ao agente na lista **Ferramentas de IA** do editor dele. Veja [Funções de IA: coletar dados e acionar fluxos](https://help.nextags.com.br/tutoriais/ia/funcoes-do-agente/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/agents/functions" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso As funções, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de object | A lista de funções. | | `data[].id` | integer | O ID da função. | | `data[].name` | string | O **Nome** da função, como `agendar_horario`. | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].created_at` | string (data e hora) | A data de criação, em UTC. | ```json { "data": [ { "id": 5101, "name": "agendar_horario", "created_by": 10001, "created_at": "2026-09-15 13:40:00" } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar servidores MCP > Lista os Servidores MCP da conta (AI Hub › Ferramentas de IA): os sistemas externos que o agente consulta pelo protocolo MCP, como o estoque de uma loja. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/listar-servidores-mcp/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/agents/mcp X-ACCESS-TOKEN: ``` Lista os **Servidores MCP** da conta (AI Hub › **Ferramentas de IA**): os sistemas externos que o agente consulta pelo protocolo MCP, como o estoque de uma loja. A aba aparece com a OpenAI, o xAI, o Claude ou o Gemini conectados. Veja [Servidores MCP no agente](https://help.nextags.com.br/tutoriais/ia/mcp-no-agente/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/agents/mcp" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os servidores, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de object | A lista de servidores MCP. | | `data[].id` | integer | O ID do servidor. | | `data[].name` | string | O **Nome** do servidor, como `estoque_loja`. | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].created_at` | string (data e hora) | A data de criação, em UTC. | ```json { "data": [ { "id": 5201, "name": "estoque_loja", "created_by": 10001, "created_at": "2026-09-20 11:00:00" } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Listar arquivos dos agentes > Lista os Arquivos da conta (AI Hub › Ferramentas de IA): a base de conhecimento que o agente consulta para responder. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/listar-arquivos-dos-agentes/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/agents/files X-ACCESS-TOKEN: ``` Lista os **Arquivos** da conta (AI Hub › **Ferramentas de IA**): a base de conhecimento que o agente consulta para responder. A aba **Arquivos** só aparece com a OpenAI conectada. Veja [Arquivos: a base de conhecimento do agente](https://help.nextags.com.br/tutoriais/ia/base-de-conhecimento/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/agents/files" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os arquivos, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de object | A lista de arquivos. | | `data[].id` | integer | O ID do arquivo. | | `data[].name` | string | O nome do arquivo. | | `data[].size` | number | O tamanho do arquivo. | | `data[].url` | string | O endereço do arquivo. | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].created_at` | string (data e hora) | A data de criação, em UTC. | ```json { "data": [ { "id": 5301, "name": "politica-de-trocas.pdf", "size": 248000, "url": "https://exemplo.com.br/arquivos/politica-de-trocas.pdf", "created_by": 10001, "created_at": "2026-09-16 10:00:00" } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Salvar mensagens no histórico da IA > Põe mensagens no histórico de conversa que a IA guarda do contato, sem enviar nada a ele. Endereço: https://docs.nextags.com.br/referencia/agentes-de-ia/salvar-mensagens-no-historico-da-ia/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/ai/save_messages X-ACCESS-TOKEN: ``` Põe mensagens no histórico de conversa que a IA guarda do contato, sem enviar nada a ele. Use para dar contexto à IA sobre uma conversa que aconteceu fora da NexTags, como um atendimento por telefone, por e-mail ou na loja: nas próximas respostas, ela já sabe o que foi dito. Nos fluxos, a ação **Excluir histórico de mensagens** apaga o histórico da IA do contato; veja [Chamar a IA no fluxo](https://help.nextags.com.br/tutoriais/fluxos/ia-no-fluxo/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `messages` | array de object | não | As mensagens, na ordem em que aconteceram. | | `messages[].text` | string | sim | O texto da mensagem. | | `messages[].type` | string | não | O tipo: `text` (texto), `image` (imagem), `file` (arquivo) ou `audio` (áudio). Valores: `text`, `image`, `file`, `audio`. | | `messages[].role` | string | sim | Quem falou: `user` (o contato), `assistant` (a IA ou a sua equipe, respondendo) ou `developer` (uma instrução para a IA, que não é fala de ninguém). Valores: `assistant`, `user`, `developer`. | ```json { "messages": [ { "role": "user", "type": "text", "text": "Liguei ontem para trocar o tamanho do tênis do pedido PED-1001." }, { "role": "assistant", "type": "text", "text": "Combinado, Ana! A troca para o 38 foi aberta e o novo par sai amanhã." } ] } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "type": "text", "text": "Liguei ontem para trocar o tamanho do tênis do pedido PED-1001." }, { "role": "assistant", "type": "text", "text": "Combinado, Ana! A troca para o 38 foi aberta e o novo par sai amanhã." } ] }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso As mensagens entraram no histórico da IA do contato. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # E-commerce > Produtos, carrinho e pedidos de cada contato. Endereço: https://docs.nextags.com.br/referencia/ecommerce/ Tipo: Referência A loja dentro da conversa: os produtos do E-commerce (**Ferramentas** › **Ecommerce**), o carrinho de cada contato e os pedidos. Cuidado com os centavos: os valores do carrinho e do pedido (`total`, `subtotal`, `coupon_discount`) e o `amount_received` vão em centavos (`8082` = R$ 80,82), mas o `price` do produto e o de cada item do carrinho não (`49.9` = R$ 49,90). Veja o guia [Carrinho, pedidos e produtos](https://docs.nextags.com.br/guias/carrinho-e-pedidos/) e [Carrinho e pedidos na conversa](https://help.nextags.com.br/tutoriais/ecommerce/carrinho-e-pedidos/). ## Endpoints - [Consultar produto](https://docs.nextags.com.br/referencia/ecommerce/consultar-produto.md): `GET /products/{product_id}` - [Atualizar produto](https://docs.nextags.com.br/referencia/ecommerce/atualizar-produto.md): `POST /products/{product_id}` - [Enviar produtos ao contato](https://docs.nextags.com.br/referencia/ecommerce/enviar-produtos-ao-contato.md): `POST /contacts/{contact_id}/send/products` - [Consultar carrinho](https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho.md): `GET /contacts/{contact_id}/cart` - [Esvaziar carrinho](https://docs.nextags.com.br/referencia/ecommerce/esvaziar-carrinho.md): `DELETE /contacts/{contact_id}/cart` - [Adicionar produto ao carrinho](https://docs.nextags.com.br/referencia/ecommerce/adicionar-produto-ao-carrinho.md): `POST /contacts/{contact_id}/cart/{product_id}` - [Remover produto do carrinho](https://docs.nextags.com.br/referencia/ecommerce/remover-produto-do-carrinho.md): `DELETE /contacts/{contact_id}/cart/{product_id}` - [Consultar pedido](https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido.md): `GET /contacts/{contact_id}/order/{order_id}` - [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido.md): `POST /contacts/{contact_id}/order/{order_id}` - [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago.md): `POST /contacts/{contact_id}/pay/{order_id}` ## O objeto: Carrinho | Campo | Tipo | Descrição | |---|---|---| | `order_id` | string | O ID do pedido (texto). | | `page_id` | integer | O ID da conta. | | `user_id` | integer | O ID do contato. | | `currency` | string | A moeda da loja, como `BRL`. | | `total` | integer | O total, em centavos. | | `subtotal` | integer | A soma dos itens, em centavos. | | `total_items` | integer | Quantos itens o carrinho tem. | | `coupon_discount` | integer | O desconto do cupom, em centavos. | | `coupon` | string | O código do cupom aplicado (o **Código de desconto** da aba **Cupons**). | | `line_items` | array de objeto Item do carrinho | Os itens do carrinho. | | `line_items[].id` | integer | O ID do produto. | | `line_items[].name` | string | O nome do produto. | | `line_items[].img` | string | O endereço da imagem do produto. | | `line_items[].price` | number | O preço de uma unidade, na moeda da loja. Não é em centavos: `49.9` = R$ 49,90. | | `line_items[].amount` | integer | A quantidade. | | `line_items[].descr_min` | string | A descrição curta do produto. | | `line_items[].manufacturer` | integer | O ID do vendedor do produto (aba **Vendedores**). | | `line_items[].variant` | string | A variante escolhida, como o tamanho ou a cor. | | `line_items[].user_msg` | string | O pedido especial que o contato anotou no item, quando o produto permite anexar notas. | | `contact` | objeto Contato | O contato dono do carrinho. | | `contact.id` | integer | O ID do contato: o `contact_id` das outras chamadas. | | `contact.page_id` | integer | O ID da conta. | | `contact.first_name` | string | O nome. | | `contact.last_name` | string | O sobrenome. | | `contact.channel` | integer | O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok. | | `contact.profile_pic` | string | O endereço da foto de perfil. | | `contact.locale` | string | O idioma do contato, como `pt_BR`. | | `contact.gender` | integer | O gênero: 0 feminino, 1 masculino, 2 desconhecido. | | `contact.timezone` | integer | O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília). | | `contact.last_sent` | integer | Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos. | | `contact.last_delivered` | integer | Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos. | | `contact.last_seen` | integer | Quando o contato foi visto pela última vez (**Visto pela última vez**, no app), em Unix timestamp em milissegundos. | | `contact.last_interaction` | integer | Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos. | | `contact.subscribed_date` | string | Quando o contato entrou na conta, em UTC, no formato `2026-10-12 14:40:00`. | | `contact.subscribed` | integer | 1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja [Contatos que pediram para sair das transmissões](https://help.nextags.com.br/tutoriais/contatos/cancelar-inscricao/). | | `contact.tags` | array de objeto Etiqueta | As etiquetas do contato. | | `contact.tags[].id` | integer | O ID da etiqueta. | | `contact.tags[].name` | string | O nome da etiqueta. | | `contact.custom_fields` | array de objeto Campo personalizado | Os campos personalizados do contato, com o valor de cada um. | | `contact.custom_fields[].id` | integer | O ID do campo. | | `contact.custom_fields[].name` | string | O nome do campo. | | `contact.custom_fields[].type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `contact.custom_fields[].value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "order_id": "PED-1001", "page_id": 123456, "user_id": 123456789, "currency": "BRL", "total": 8082, "subtotal": 8980, "total_items": 2, "coupon_discount": 898, "coupon": "BEMVINDO10", "line_items": [ { "id": 6001, "name": "Camiseta Básica Preta", "img": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "price": 49.9, "amount": 1, "descr_min": "Camiseta 100% algodão, gola redonda.", "manufacturer": 0, "variant": "M", "user_msg": "" }, { "id": 6002, "name": "Boné Aba Curva", "img": "https://exemplo.com.br/produtos/bone.jpg", "price": 39.9, "amount": 1, "descr_min": "Boné ajustável de algodão.", "manufacturer": 0, "variant": "", "user_msg": "Embrulhar para presente." } ], "contact": { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792933200000, "last_delivered": 1792933202000, "last_seen": 1792933500000, "last_interaction": 1792933560000, "subscribed_date": "2026-03-10 14:22:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } } ``` --- # Consultar produto > Devolve um produto do E-commerce: o nome, os preços, o estoque, a categoria, a descrição curta e a imagem. Endereço: https://docs.nextags.com.br/referencia/ecommerce/consultar-produto/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/products/{product_id} X-ACCESS-TOKEN: ``` Devolve um produto do E-commerce: o nome, os preços, o estoque, a categoria, a descrição curta e a imagem. Os preços vêm na moeda da loja, não em centavos. Veja [Cadastrar produtos](https://help.nextags.com.br/tutoriais/ecommerce/cadastrar-produtos/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `product_id` | integer | sim | O ID do produto. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/products/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O produto. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do produto. | | `name` | string | O nome do produto. | | `price` | number | O preço, como na coluna **Preço** da lista (`49.9` = R$ 49,90). | | `sale_price` | number | O preço promocional. | | `category_id` | integer | O ID da categoria (aba **Categorias**). | | `category_name` | string | O nome da categoria. | | `stock` | integer | O estoque, como na coluna **Inventário** da lista. | | `short_description` | string | A descrição curta. | | `image` | string | O endereço da imagem. | | `created_at` | string | Quando o produto foi criado, em UTC. | ```json { "id": 6001, "name": "Camiseta Básica Preta", "price": 49.9, "sale_price": 39.9, "category_id": 6101, "category_name": "Camisetas", "stock": 120, "short_description": "Camiseta 100% algodão, gola redonda.", "image": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "created_at": "2026-07-10 18:00:00" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Atualizar produto > Muda o preço, o estoque e o Ativo de um produto, para a loja acompanhar o seu sistema de estoque. Endereço: https://docs.nextags.com.br/referencia/ecommerce/atualizar-produto/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/products/{product_id} X-ACCESS-TOKEN: ``` Muda o preço, o estoque e o **Ativo** de um produto, para a loja acompanhar o seu sistema de estoque. Os três campos são opcionais. Veja [Cadastrar produtos](https://help.nextags.com.br/tutoriais/ecommerce/cadastrar-produtos/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `product_id` | integer | sim | O ID do produto. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `price` | number | não | O preço novo, na moeda da loja. Não é em centavos: `44.9` = R$ 44,90. | | `active` | boolean | não | O **Ativo** da lista de produtos: `true` deixa o produto à venda; `false` tira da venda. | | `stock` | integer | não | O estoque novo (a coluna **Inventário** da lista de produtos). | ```json { "price": 44.9, "stock": 85, "active": true } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/products/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "price": 44.9, "stock": 85, "active": true }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O produto foi atualizado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | | `updated` | boolean | Se algum dado do produto mudou. | ```json { "success": true, "updated": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Enviar produtos ao contato > Manda ao contato uma mensagem com um ou mais produtos do E-commerce, como o Enviar Produtos da Caixa de Entrada. Endereço: https://docs.nextags.com.br/referencia/ecommerce/enviar-produtos-ao-contato/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/send/products X-ACCESS-TOKEN: ``` Manda ao contato uma mensagem com um ou mais produtos do E-commerce, como o **Enviar Produtos** da Caixa de Entrada. Veja [Enviar produtos na conversa](https://help.nextags.com.br/tutoriais/ecommerce/enviar-produtos-na-conversa/). > No WhatsApp, no Instagram e no Messenger, a mensagem só chega dentro da [janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `product_id` | integer ou string ou array | sim | O produto ou os produtos: um ID (`6001`), uma lista de IDs (`[6001, 6002]`) ou IDs separados por vírgula (`"6001,6002"`). | ```json { "product_id": [ 6001, 6002 ] } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/products" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "product_id": [ 6001, 6002 ] }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O envio foi aceito. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar carrinho > Devolve o carrinho do contato: os itens, a quantidade de cada um, o cupom e os totais. Endereço: https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/contacts/{contact_id}/cart X-ACCESS-TOKEN: ``` Devolve o carrinho do contato: os itens, a quantidade de cada um, o cupom e os totais. Os totais vêm em centavos; o `price` de cada item, não. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/cart" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O carrinho. | Campo | Tipo | Descrição | |---|---|---| | `order_id` | string | O ID do pedido (texto). | | `page_id` | integer | O ID da conta. | | `user_id` | integer | O ID do contato. | | `currency` | string | A moeda da loja, como `BRL`. | | `total` | integer | O total, em centavos. | | `subtotal` | integer | A soma dos itens, em centavos. | | `total_items` | integer | Quantos itens o carrinho tem. | | `coupon_discount` | integer | O desconto do cupom, em centavos. | | `coupon` | string | O código do cupom aplicado (o **Código de desconto** da aba **Cupons**). | | `line_items` | array de objeto Item do carrinho | Os itens do carrinho. | | `line_items[].id` | integer | O ID do produto. | | `line_items[].name` | string | O nome do produto. | | `line_items[].img` | string | O endereço da imagem do produto. | | `line_items[].price` | number | O preço de uma unidade, na moeda da loja. Não é em centavos: `49.9` = R$ 49,90. | | `line_items[].amount` | integer | A quantidade. | | `line_items[].descr_min` | string | A descrição curta do produto. | | `line_items[].manufacturer` | integer | O ID do vendedor do produto (aba **Vendedores**). | | `line_items[].variant` | string | A variante escolhida, como o tamanho ou a cor. | | `line_items[].user_msg` | string | O pedido especial que o contato anotou no item, quando o produto permite anexar notas. | | `contact` | objeto Contato | O contato dono do carrinho. | | `contact.id` | integer | O ID do contato: o `contact_id` das outras chamadas. | | `contact.page_id` | integer | O ID da conta. | | `contact.first_name` | string | O nome. | | `contact.last_name` | string | O sobrenome. | | `contact.channel` | integer | O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok. | | `contact.profile_pic` | string | O endereço da foto de perfil. | | `contact.locale` | string | O idioma do contato, como `pt_BR`. | | `contact.gender` | integer | O gênero: 0 feminino, 1 masculino, 2 desconhecido. | | `contact.timezone` | integer | O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília). | | `contact.last_sent` | integer | Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos. | | `contact.last_delivered` | integer | Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos. | | `contact.last_seen` | integer | Quando o contato foi visto pela última vez (**Visto pela última vez**, no app), em Unix timestamp em milissegundos. | | `contact.last_interaction` | integer | Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos. | | `contact.subscribed_date` | string | Quando o contato entrou na conta, em UTC, no formato `2026-10-12 14:40:00`. | | `contact.subscribed` | integer | 1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja [Contatos que pediram para sair das transmissões](https://help.nextags.com.br/tutoriais/contatos/cancelar-inscricao/). | | `contact.tags` | array de objeto Etiqueta | As etiquetas do contato. | | `contact.tags[].id` | integer | O ID da etiqueta. | | `contact.tags[].name` | string | O nome da etiqueta. | | `contact.custom_fields` | array de objeto Campo personalizado | Os campos personalizados do contato, com o valor de cada um. | | `contact.custom_fields[].id` | integer | O ID do campo. | | `contact.custom_fields[].name` | string | O nome do campo. | | `contact.custom_fields[].type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `contact.custom_fields[].value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "order_id": "PED-1001", "page_id": 123456, "user_id": 123456789, "currency": "BRL", "total": 8082, "subtotal": 8980, "total_items": 2, "coupon_discount": 898, "coupon": "BEMVINDO10", "line_items": [ { "id": 6001, "name": "Camiseta Básica Preta", "img": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "price": 49.9, "amount": 1, "descr_min": "Camiseta 100% algodão, gola redonda.", "manufacturer": 0, "variant": "M", "user_msg": "" }, { "id": 6002, "name": "Boné Aba Curva", "img": "https://exemplo.com.br/produtos/bone.jpg", "price": 39.9, "amount": 1, "descr_min": "Boné ajustável de algodão.", "manufacturer": 0, "variant": "", "user_msg": "Embrulhar para presente." } ], "contact": { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792933200000, "last_delivered": 1792933202000, "last_seen": 1792933500000, "last_interaction": 1792933560000, "subscribed_date": "2026-03-10 14:22:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Esvaziar carrinho > Tira todos os itens do carrinho do contato, como a operação Limpar Carrinho de Compras da ação Ecommerce dos fluxos. Endereço: https://docs.nextags.com.br/referencia/ecommerce/esvaziar-carrinho/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/contacts/{contact_id}/cart X-ACCESS-TOKEN: ``` Tira todos os itens do carrinho do contato, como a operação **Limpar Carrinho de Compras** da ação **Ecommerce** dos fluxos. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O carrinho ficou vazio. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Adicionar produto ao carrinho > Põe um produto no carrinho do contato, com a quantidade. Endereço: https://docs.nextags.com.br/referencia/ecommerce/adicionar-produto-ao-carrinho/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/cart/{product_id} X-ACCESS-TOKEN: ``` Põe um produto no carrinho do contato, com a quantidade. O corpo vai em formulário (`application/x-www-form-urlencoded`), não em JSON. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `product_id` | integer | sim | O ID do produto. | ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `quantity` | integer | sim | Quantas unidades do produto. | ```json { "quantity": 2 } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'quantity=2' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O produto entrou no carrinho. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Remover produto do carrinho > Tira um produto do carrinho do contato. Endereço: https://docs.nextags.com.br/referencia/ecommerce/remover-produto-do-carrinho/ Tipo: Endpoint ```http DELETE https://app.nextagsai.com.br/api/contacts/{contact_id}/cart/{product_id} X-ACCESS-TOKEN: ``` Tira um produto do carrinho do contato. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `product_id` | integer | sim | O ID do produto. | ## Exemplo ```bash curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O produto saiu do carrinho. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar pedido > Devolve um pedido do contato, no mesmo formato do carrinho: os itens, o cupom e os totais em centavos (menos o price de cada item). Endereço: https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/contacts/{contact_id}/order/{order_id} X-ACCESS-TOKEN: ``` Devolve um pedido do contato, no mesmo formato do carrinho: os itens, o cupom e os totais em centavos (menos o `price` de cada item). Veja [Pedidos, cupons e vendedores](https://help.nextags.com.br/tutoriais/ecommerce/pedidos-cupons-e-vendedores/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `order_id` | string | sim | O ID do pedido (texto). Ele vem em `order_id`, no carrinho e no pedido. | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O pedido. | Campo | Tipo | Descrição | |---|---|---| | `order_id` | string | O ID do pedido (texto). | | `page_id` | integer | O ID da conta. | | `user_id` | integer | O ID do contato. | | `currency` | string | A moeda da loja, como `BRL`. | | `total` | integer | O total, em centavos. | | `subtotal` | integer | A soma dos itens, em centavos. | | `total_items` | integer | Quantos itens o carrinho tem. | | `coupon_discount` | integer | O desconto do cupom, em centavos. | | `coupon` | string | O código do cupom aplicado (o **Código de desconto** da aba **Cupons**). | | `line_items` | array de objeto Item do carrinho | Os itens do carrinho. | | `line_items[].id` | integer | O ID do produto. | | `line_items[].name` | string | O nome do produto. | | `line_items[].img` | string | O endereço da imagem do produto. | | `line_items[].price` | number | O preço de uma unidade, na moeda da loja. Não é em centavos: `49.9` = R$ 49,90. | | `line_items[].amount` | integer | A quantidade. | | `line_items[].descr_min` | string | A descrição curta do produto. | | `line_items[].manufacturer` | integer | O ID do vendedor do produto (aba **Vendedores**). | | `line_items[].variant` | string | A variante escolhida, como o tamanho ou a cor. | | `line_items[].user_msg` | string | O pedido especial que o contato anotou no item, quando o produto permite anexar notas. | | `contact` | objeto Contato | O contato dono do carrinho. | | `contact.id` | integer | O ID do contato: o `contact_id` das outras chamadas. | | `contact.page_id` | integer | O ID da conta. | | `contact.first_name` | string | O nome. | | `contact.last_name` | string | O sobrenome. | | `contact.channel` | integer | O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok. | | `contact.profile_pic` | string | O endereço da foto de perfil. | | `contact.locale` | string | O idioma do contato, como `pt_BR`. | | `contact.gender` | integer | O gênero: 0 feminino, 1 masculino, 2 desconhecido. | | `contact.timezone` | integer | O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília). | | `contact.last_sent` | integer | Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos. | | `contact.last_delivered` | integer | Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos. | | `contact.last_seen` | integer | Quando o contato foi visto pela última vez (**Visto pela última vez**, no app), em Unix timestamp em milissegundos. | | `contact.last_interaction` | integer | Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos. | | `contact.subscribed_date` | string | Quando o contato entrou na conta, em UTC, no formato `2026-10-12 14:40:00`. | | `contact.subscribed` | integer | 1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja [Contatos que pediram para sair das transmissões](https://help.nextags.com.br/tutoriais/contatos/cancelar-inscricao/). | | `contact.tags` | array de objeto Etiqueta | As etiquetas do contato. | | `contact.tags[].id` | integer | O ID da etiqueta. | | `contact.tags[].name` | string | O nome da etiqueta. | | `contact.custom_fields` | array de objeto Campo personalizado | Os campos personalizados do contato, com o valor de cada um. | | `contact.custom_fields[].id` | integer | O ID do campo. | | `contact.custom_fields[].name` | string | O nome do campo. | | `contact.custom_fields[].type` | integer | O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla. Valores: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`. | | `contact.custom_fields[].value` | string ou number | O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0). | ```json { "order_id": "PED-1001", "page_id": 123456, "user_id": 123456789, "currency": "BRL", "total": 8082, "subtotal": 8980, "total_items": 2, "coupon_discount": 898, "coupon": "BEMVINDO10", "line_items": [ { "id": 6001, "name": "Camiseta Básica Preta", "img": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "price": 49.9, "amount": 1, "descr_min": "Camiseta 100% algodão, gola redonda.", "manufacturer": 0, "variant": "M", "user_msg": "" }, { "id": 6002, "name": "Boné Aba Curva", "img": "https://exemplo.com.br/produtos/bone.jpg", "price": 39.9, "amount": 1, "descr_min": "Boné ajustável de algodão.", "manufacturer": 0, "variant": "", "user_msg": "Embrulhar para presente." } ], "contact": { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792933200000, "last_delivered": 1792933202000, "last_seen": 1792933500000, "last_interaction": 1792933560000, "subscribed_date": "2026-03-10 14:22:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Alterar pedido > Muda a situação de um pedido e os dados de entrega. Endereço: https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/order/{order_id} X-ACCESS-TOKEN: ``` Muda a situação de um pedido e os dados de entrega. A situação vai em `status`, pelo código: `6` **Aceito** (em processamento), `7` **Entregando** (enviado), `10` **Concluído** e `13` **Cancelado**. O **Não processado** (código 4) não pode ser escolhido aqui. Veja [Pedidos, cupons e vendedores](https://help.nextags.com.br/tutoriais/ecommerce/pedidos-cupons-e-vendedores/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `order_id` | string | sim | O ID do pedido (texto). Ele vem em `order_id`, no carrinho e no pedido. | ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `status` | integer | não | A situação nova: `6` Aceito, `7` Entregando, `10` Concluído ou `13` Cancelado. Valores: `6`, `7`, `10`, `13`. | | `name` | string | não | O nome de quem recebe a entrega. | | `phone` | string | não | O telefone para a entrega. | | `email` | string | não | O e-mail para a entrega. | | `country` | string | não | O país da entrega. | | `state` | string | não | O estado. | | `city` | string | não | A cidade. | | `zip_code` | string | não | O CEP. | | `address` | string | não | O endereço de entrega. | | `street_1` | string | não | A primeira linha do endereço: rua e número. | | `street_2` | string | não | A segunda linha do endereço, como o complemento. | | `note` | string | não | Uma observação sobre o pedido. | ```json { "status": 7, "name": "Ana Souza", "phone": "5511988776655", "city": "São Paulo", "state": "SP", "zip_code": "01310-100", "street_1": "Av. Paulista, 1578", "street_2": "Apto 45", "note": "Entregar na portaria." } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": 7, "name": "Ana Souza", "phone": "5511988776655", "city": "São Paulo", "state": "SP", "zip_code": "01310-100", "street_1": "Av. Paulista, 1578", "street_2": "Apto 45", "note": "Entregar na portaria." }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O pedido foi alterado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 400 Requisição inválida O `status` não é 6, 7, 10 nem 13. ### 402 Não concluído O pedido já está nessa situação. ### 404 Não encontrado O pedido não existe para este contato. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Marcar pedido como pago > Marca um pedido como pago, quando o contato pagou fora da NexTags (Pix, link de pagamento, na loja). Endereço: https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/contacts/{contact_id}/pay/{order_id} X-ACCESS-TOKEN: ``` Marca um pedido como pago, quando o contato pagou fora da NexTags (Pix, link de pagamento, na loja). O valor recebido precisa cobrir o total do pedido. O corpo vai em formulário (`application/x-www-form-urlencoded`). Veja [Receber pagamentos no e-commerce](https://help.nextags.com.br/tutoriais/ecommerce/pagamentos/). > O `amount_received` vai em centavos: R$ 80,82 = `8082`. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `contact_id` | integer | sim | O ID do contato. | | `order_id` | string | sim | O ID do pedido (texto). Ele vem em `order_id`, no carrinho e no pedido. | ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `amount_received` | integer | sim | O valor que o contato pagou, em centavos (`8082` = R$ 80,82). | ```json { "amount_received": 8082 } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'amount_received=8082' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O pedido foi marcado como pago. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 400 Requisição inválida O `amount_received` é menor que o total do pedido. ### 402 Não concluído O checkout falhou, e o contato recebeu uma mensagem explicando por quê. ### 404 Não encontrado O pedido não existe para este contato. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Disparos > Consulte, reenvie e cancele disparos (broadcasts). Endereço: https://docs.nextags.com.br/referencia/disparos/ Tipo: Referência Os Broadcasts da conta (menu **Broadcasts**): os envios em massa, cada um com o seu estado. Pela API, você acompanha, reenvia e cancela Broadcasts; criar um Broadcast é só na tela, em **Broadcasts** › **Enviar** ([Criar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/criar-disparo/)). Veja o guia [Acompanhar, reenviar e cancelar disparos](https://docs.nextags.com.br/guias/disparos-pela-api/). ## Endpoints - [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos.md): `GET /broadcasts` - [Consultar disparo](https://docs.nextags.com.br/referencia/disparos/consultar-disparo.md): `GET /broadcasts/{broadcast_id}` - [Reenviar disparo](https://docs.nextags.com.br/referencia/disparos/reenviar-disparo.md): `POST /broadcasts/{broadcast_id}/resend` - [Cancelar disparo](https://docs.nextags.com.br/referencia/disparos/cancelar-disparo.md): `POST /broadcasts/{broadcast_id}/cancel` ## O objeto: Broadcast | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do Broadcast. | | `name` | string | O nome do Broadcast, como na coluna **Nome** da lista. | | `status` | string | O estado: `DRAFT` (rascunho; *Draft* na lista), `NOT_SENT` (ainda não saiu, como um Broadcast **Pendente** ou **Agendado**), `SENTING` (**Enviando**; o nome é escrito assim mesmo), `SENT` (**Enviado**) ou `CANCELLED` (**Cancelado**). Valores: `DRAFT`, `NOT_SENT`, `SENTING`, `SENT`, `CANCELLED`. | | `sent_at` | string (data e hora) | Quando o envio saiu, em UTC. | | `created_by` | integer | O ID do administrador que criou. | | `created_at` | string (data e hora) | Quando o Broadcast foi criado, em UTC. | ```json { "id": 7001, "name": "Black Friday - clientes VIP", "status": "SENT", "sent_at": "2026-10-20 15:00:00", "created_by": 10001, "created_at": "2026-10-20 14:45:00" } ``` --- # Listar disparos > Lista os Broadcasts da conta, com o nome, o estado e as datas de cada um. Endereço: https://docs.nextags.com.br/referencia/disparos/listar-disparos/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/broadcasts X-ACCESS-TOKEN: ``` Lista os Broadcasts da conta, com o nome, o estado e as datas de cada um. Não há chamada para criar um Broadcast: ele é criado na tela, em **Broadcasts** › **Enviar** ([Criar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/criar-disparo/)). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/broadcasts" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os Broadcasts, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Broadcast | A lista de Broadcasts (até 100). | | `data[].id` | integer | O ID do Broadcast. | | `data[].name` | string | O nome do Broadcast, como na coluna **Nome** da lista. | | `data[].status` | string | O estado: `DRAFT` (rascunho; *Draft* na lista), `NOT_SENT` (ainda não saiu, como um Broadcast **Pendente** ou **Agendado**), `SENTING` (**Enviando**; o nome é escrito assim mesmo), `SENT` (**Enviado**) ou `CANCELLED` (**Cancelado**). Valores: `DRAFT`, `NOT_SENT`, `SENTING`, `SENT`, `CANCELLED`. | | `data[].sent_at` | string (data e hora) | Quando o envio saiu, em UTC. | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].created_at` | string (data e hora) | Quando o Broadcast foi criado, em UTC. | ```json { "data": [ { "id": 7001, "name": "Black Friday - clientes VIP", "status": "SENT", "sent_at": "2026-10-20 15:00:00", "created_by": 10001, "created_at": "2026-10-20 14:45:00" }, { "id": 7002, "name": "Lançamento da coleção de verão", "status": "SENT", "sent_at": "2026-10-05 13:00:00", "created_by": 10001, "created_at": "2026-10-05 12:40:00" } ] } ``` ### 400 Requisição inválida Parâmetros inválidos. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar disparo > Devolve um Broadcast pelo ID, com o estado: use para acompanhar um envio até SENT. Endereço: https://docs.nextags.com.br/referencia/disparos/consultar-disparo/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/broadcasts/{broadcast_id} X-ACCESS-TOKEN: ``` Devolve um Broadcast pelo ID, com o estado: use para acompanhar um envio até `SENT`. Os números de entregues, vistos, cliques e falhas não vêm aqui: ficam na lista **Broadcasts** ([Resultados: entregues, abertos, clicados e falhas](https://help.nextags.com.br/tutoriais/disparos/resultados-e-custos/)). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `broadcast_id` | integer | sim | O ID do Broadcast (veja [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/)). | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/broadcasts/7001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O Broadcast. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do Broadcast. | | `name` | string | O nome do Broadcast, como na coluna **Nome** da lista. | | `status` | string | O estado: `DRAFT` (rascunho; *Draft* na lista), `NOT_SENT` (ainda não saiu, como um Broadcast **Pendente** ou **Agendado**), `SENTING` (**Enviando**; o nome é escrito assim mesmo), `SENT` (**Enviado**) ou `CANCELLED` (**Cancelado**). Valores: `DRAFT`, `NOT_SENT`, `SENTING`, `SENT`, `CANCELLED`. | | `sent_at` | string (data e hora) | Quando o envio saiu, em UTC. | | `created_by` | integer | O ID do administrador que criou. | | `created_at` | string (data e hora) | Quando o Broadcast foi criado, em UTC. | ```json { "id": 7001, "name": "Black Friday - clientes VIP", "status": "SENT", "sent_at": "2026-10-20 15:00:00", "created_by": 10001, "created_at": "2026-10-20 14:45:00" } ``` ### 404 Não encontrado O Broadcast não existe nesta conta. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Reenviar disparo > Manda o Broadcast de novo, como o Reenviar do menu da lista, que aparece em qualquer estado. Endereço: https://docs.nextags.com.br/referencia/disparos/reenviar-disparo/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/broadcasts/{broadcast_id}/resend X-ACCESS-TOKEN: ``` Manda o Broadcast de novo, como o **Reenviar** do menu da lista, que aparece em qualquer estado. Antes de reenviar, pense em quem já recebeu: mensagem repetida aumenta os bloqueios e as denúncias. Veja [Reenviar, cancelar e exportar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/reenviar-e-cancelar/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `broadcast_id` | integer | sim | O ID do Broadcast (veja [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/)). | ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/broadcasts/7001/resend" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O reenvio foi aceito. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Cancelar disparo > Para um Broadcast que ainda não saiu, como o Cancelar do menu da lista. Endereço: https://docs.nextags.com.br/referencia/disparos/cancelar-disparo/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/broadcasts/{broadcast_id}/cancel X-ACCESS-TOKEN: ``` Para um Broadcast que ainda não saiu, como o **Cancelar** do menu da lista. Na tela, o **Cancelar** só aparece enquanto o Broadcast está **Agendado**, **Pendente** ou no começo do envio; depois disso, não dá mais para parar. Cancelado, o estado vira `CANCELLED`. Veja [Reenviar, cancelar e exportar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/reenviar-e-cancelar/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `broadcast_id` | integer | sim | O ID do Broadcast (veja [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/)). | ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/broadcasts/7001/cancel" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O Broadcast foi cancelado. | Campo | Tipo | Descrição | |---|---|---| | `success` | boolean | `true` quando deu certo. | ```json { "success": true } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Agenda > Calendários usados nos agendamentos. Endereço: https://docs.nextags.com.br/referencia/agenda/ Tipo: Referência Os calendários do **Gestor de Agendamentos** (**Ferramentas** › **Gestor de Agendamentos**): o que o contato reserva pelo link do calendário, pelo fluxo ou pela IA. A API só lê os calendários; criar e editar um calendário e ver os agendamentos é na tela. Veja [Criar um calendário](https://help.nextags.com.br/tutoriais/agenda/criar-calendario/). ## Endpoints - [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios.md): `GET /calendars` - [Consultar calendário](https://docs.nextags.com.br/referencia/agenda/consultar-calendario.md): `GET /calendars/{calendar_id}` ## O objeto: Calendário | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do calendário. | | `name` | string | O nome do calendário. | | `duration` | integer | A **Duração do evento**: quanto dura cada agendamento, em minutos (na tela, de 5 minutos a 23 horas). | | `created_by` | integer | O ID do administrador que criou. | | `created_at` | string (data e hora) | Quando o calendário foi criado, em UTC. | ```json { "id": 8001, "name": "Avaliação gratuita", "duration": 30, "created_by": 10001, "created_at": "2026-08-01 12:00:00" } ``` --- # Listar calendários > Lista os calendários da conta, com o ID, o nome e a duração de cada um. Endereço: https://docs.nextags.com.br/referencia/agenda/listar-calendarios/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/calendars X-ACCESS-TOKEN: ``` Lista os calendários da conta, com o ID, o nome e a duração de cada um. A API não lista os agendamentos: eles ficam na aba **Agendamentos** ([Ver e cancelar agendamentos](https://help.nextags.com.br/tutoriais/agenda/ver-agendamentos/)). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/calendars" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os calendários, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | array de objeto Calendário | A lista de calendários (até 100). | | `data[].id` | integer | O ID do calendário. | | `data[].name` | string | O nome do calendário. | | `data[].duration` | integer | A **Duração do evento**: quanto dura cada agendamento, em minutos (na tela, de 5 minutos a 23 horas). | | `data[].created_by` | integer | O ID do administrador que criou. | | `data[].created_at` | string (data e hora) | Quando o calendário foi criado, em UTC. | ```json { "data": [ { "id": 8001, "name": "Avaliação gratuita", "duration": 30, "created_by": 10001, "created_at": "2026-08-01 12:00:00" }, { "id": 8002, "name": "Reunião de implantação", "duration": 60, "created_by": 10001, "created_at": "2026-08-12 15:30:00" } ] } ``` ### 400 Requisição inválida Parâmetros inválidos. ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Consultar calendário > Devolve um calendário pelo ID: o nome, a duração de cada agendamento, quem criou e quando. Endereço: https://docs.nextags.com.br/referencia/agenda/consultar-calendario/ Tipo: Endpoint ```http GET https://app.nextagsai.com.br/api/calendars/{calendar_id} X-ACCESS-TOKEN: ``` Devolve um calendário pelo ID: o nome, a duração de cada agendamento, quem criou e quando. Para usar o calendário numa conversa, veja [Agendar pela conversa](https://help.nextags.com.br/tutoriais/agenda/agendar-pelo-fluxo/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Parâmetros de caminho | Nome | Tipo | Obrigatório | Descrição | |---|---|---|---| | `calendar_id` | integer | sim | O ID do calendário (veja [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios/)). | ## Exemplo ```bash curl "https://app.nextagsai.com.br/api/calendars/8001" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O calendário. | Campo | Tipo | Descrição | |---|---|---| | `id` | integer | O ID do calendário. | | `name` | string | O nome do calendário. | | `duration` | integer | A **Duração do evento**: quanto dura cada agendamento, em minutos (na tela, de 5 minutos a 23 horas). | | `created_by` | integer | O ID do administrador que criou. | | `created_at` | string (data e hora) | Quando o calendário foi criado, em UTC. | ```json { "id": 8001, "name": "Avaliação gratuita", "duration": 30, "created_by": 10001, "created_at": "2026-08-01 12:00:00" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Ferramentas > Utilitários para usar nas requisições externas dos fluxos: texto, números, URLs, QR Code, hash e distância. Endereço: https://docs.nextags.com.br/referencia/ferramentas/ Tipo: Referência Utilitários para transformar um valor no meio de um fluxo: formatar números, trocar, recortar e contar textos, codificar URLs, gerar QR Code e hash e medir a distância entre dois pontos. Chame pela [requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) do fluxo: **Request Type** POST, o endereço da ferramenta em **Request URL** (como `https://app.nextagsai.com.br/api/tools/text_to_upper`), o cabeçalho `X-ACCESS-TOKEN` com a chave de API (guarde a chave num [campo do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/)), o **Corpo** em **Form-encoded** e, no **Mapeamento de resposta**, o JSONPath do resultado (`$.data`, na maioria) ligado ao campo que vai guardar o valor. Todas pedem a chave e recebem o corpo em formulário (`application/x-www-form-urlencoded`), menos o eco, que recebe JSON. ## Endpoints - [Formatar número](https://docs.nextags.com.br/referencia/ferramentas/formatar-numero.md): `POST /tools/format_number` - [Dividir um texto em partes](https://docs.nextags.com.br/referencia/ferramentas/dividir-um-texto-em-partes.md): `POST /tools/split` - [Codificar texto para URL](https://docs.nextags.com.br/referencia/ferramentas/codificar-texto-para-url.md): `POST /tools/urlencode` - [Decodificar texto de URL](https://docs.nextags.com.br/referencia/ferramentas/decodificar-texto-de-url.md): `POST /tools/urldecode` - [Codificar para URL (RFC 3986)](https://docs.nextags.com.br/referencia/ferramentas/codificar-para-url-rfc-3986.md): `POST /tools/rawurlencode` - [Decodificar de URL (RFC 3986)](https://docs.nextags.com.br/referencia/ferramentas/decodificar-de-url-rfc-3986.md): `POST /tools/rawurldecode` - [Gerar QR Code](https://docs.nextags.com.br/referencia/ferramentas/gerar-qr-code.md): `POST /tools/qrcode` - [Converter texto para minúsculas](https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-minusculas.md): `POST /tools/text_to_lower` - [Converter texto para maiúsculas](https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-maiusculas.md): `POST /tools/text_to_upper` - [Contar os caracteres de um texto](https://docs.nextags.com.br/referencia/ferramentas/contar-os-caracteres-de-um-texto.md): `POST /tools/text_length` - [Recortar parte de um texto](https://docs.nextags.com.br/referencia/ferramentas/recortar-parte-de-um-texto.md): `POST /tools/substring` - [Substituir um texto](https://docs.nextags.com.br/referencia/ferramentas/substituir-um-texto.md): `POST /tools/text_replace` - [Substituir vários textos](https://docs.nextags.com.br/referencia/ferramentas/substituir-varios-textos.md): `POST /tools/text_replaces` - [Ler os parâmetros de uma URL](https://docs.nextags.com.br/referencia/ferramentas/ler-os-parametros-de-uma-url.md): `POST /tools/get_url_parameters` - [Devolver o JSON enviado (eco)](https://docs.nextags.com.br/referencia/ferramentas/devolver-o-json-enviado-eco.md): `POST /tools/echo` - [Gerar um hash](https://docs.nextags.com.br/referencia/ferramentas/gerar-um-hash.md): `POST /tools/hash` - [Calcular a distância entre duas coordenadas](https://docs.nextags.com.br/referencia/ferramentas/calcular-a-distancia-entre-duas-coordenadas.md): `POST /tools/location_distance` --- # Formatar número > Formata um número com as casas decimais e os separadores que você escolher: 1995.5 vira 1.995,50. Endereço: https://docs.nextags.com.br/referencia/ferramentas/formatar-numero/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/format_number X-ACCESS-TOKEN: ``` Formata um número com as casas decimais e os separadores que você escolher: `1995.5` vira `1.995,50`. Use para mostrar um valor em reais numa mensagem. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `number` | number | sim | O número, com ponto decimal (`1995.5`). | | `decimals` | integer | não | Quantas casas decimais, como `2`. | | `decimal_separator` | string | não | O separador decimal, como `,`. | | `thousands_separator` | string | não | O separador de milhar, como `.`. | ```json { "number": 1995.5, "decimals": 2, "decimal_separator": ",", "thousands_separator": "." } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/format_number" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'number=1995.5' \ --data-urlencode 'decimals=2' \ --data-urlencode 'decimal_separator=,' \ --data-urlencode 'thousands_separator=.' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O número formatado, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string ou number | O número formatado. Com separadores, vem como texto. | ```json { "data": "1.995,50" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Dividir um texto em partes > Divide um texto em partes a cada separador e devolve a lista e o total: Camiseta,Boné,Meia com o separador , vira três partes. Endereço: https://docs.nextags.com.br/referencia/ferramentas/dividir-um-texto-em-partes/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/split X-ACCESS-TOKEN: ``` Divide um texto em partes a cada separador e devolve a lista e o total: `Camiseta,Boné,Meia` com o separador `,` vira três partes. No **Mapeamento de resposta**, `$.data[0]` é a primeira parte. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | | `delimiter` | string | sim | O separador, como `,` ou `;`. | ```json { "text": "Camiseta,Boné,Meia", "delimiter": "," } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/split" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=Camiseta,Boné,Meia' \ --data-urlencode 'delimiter=,' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso As partes, em `data`, e o total. | Campo | Tipo | Descrição | |---|---|---| | `total` | integer | Quantas partes. | | `data` | array de string | As partes, na ordem do texto. | ```json { "total": 3, "data": [ "Camiseta", "Boné", "Meia" ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Codificar texto para URL > Codifica um texto para usar numa URL, no formato de formulário: o espaço vira +, e os acentos e os outros caracteres especiais viram %XX. Endereço: https://docs.nextags.com.br/referencia/ferramentas/codificar-texto-para-url/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/urlencode X-ACCESS-TOKEN: ``` Codifica um texto para usar numa URL, no formato de formulário: o espaço vira `+`, e os acentos e os outros caracteres especiais viram `%XX`. Use no valor de um parâmetro, depois do `?`. Para `%20` no lugar do `+`, use [Codificar para URL (RFC 3986)](https://docs.nextags.com.br/referencia/ferramentas/codificar-para-url-rfc-3986/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | ```json { "text": "Olá, quero o pedido PED-1001" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/urlencode" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=Olá, quero o pedido PED-1001' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto codificado, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto codificado. | ```json { "data": "Ol%C3%A1%2C+quero+o+pedido+PED-1001" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Decodificar texto de URL > Desfaz a codificação de URL: troca as sequências %XX pelos caracteres e o + por espaço. Endereço: https://docs.nextags.com.br/referencia/ferramentas/decodificar-texto-de-url/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/urldecode X-ACCESS-TOKEN: ``` Desfaz a codificação de URL: troca as sequências `%XX` pelos caracteres e o `+` por espaço. Use para ler um valor que chegou codificado, como um parâmetro de link. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto codificado. | ```json { "text": "Ol%C3%A1%2C+quero+o+pedido+PED-1001" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/urldecode" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=Ol%C3%A1%2C+quero+o+pedido+PED-1001' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto decodificado, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto decodificado. | ```json { "data": "Olá, quero o pedido PED-1001" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Codificar para URL (RFC 3986) > Codifica um texto para URL pela RFC 3986: o espaço vira %20, e não +. Endereço: https://docs.nextags.com.br/referencia/ferramentas/codificar-para-url-rfc-3986/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/rawurlencode X-ACCESS-TOKEN: ``` Codifica um texto para URL pela RFC 3986: o espaço vira `%20`, e não `+`. Use quando o outro sistema não aceita o `+`, como num trecho do caminho da URL. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | ```json { "text": "Olá, quero o pedido PED-1001" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/rawurlencode" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=Olá, quero o pedido PED-1001' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto codificado, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto codificado. | ```json { "data": "Ol%C3%A1%2C%20quero%20o%20pedido%20PED-1001" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Decodificar de URL (RFC 3986) > Desfaz a codificação da RFC 3986: troca as sequências %XX pelos caracteres. Endereço: https://docs.nextags.com.br/referencia/ferramentas/decodificar-de-url-rfc-3986/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/rawurldecode X-ACCESS-TOKEN: ``` Desfaz a codificação da RFC 3986: troca as sequências `%XX` pelos caracteres. O `+` continua `+`; para virar espaço, use [Decodificar texto de URL](https://docs.nextags.com.br/referencia/ferramentas/decodificar-texto-de-url/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto codificado. | ```json { "text": "S%C3%A3o%20Paulo%20-%20SP" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/rawurldecode" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=S%C3%A3o%20Paulo%20-%20SP' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto decodificado, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto decodificado. | ```json { "data": "São Paulo - SP" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Gerar QR Code > Gera um QR Code com o texto ou o link que você mandar e devolve o endereço da imagem, para enviar como imagem numa mensagem. Endereço: https://docs.nextags.com.br/referencia/ferramentas/gerar-qr-code/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/qrcode X-ACCESS-TOKEN: ``` Gera um QR Code com o texto ou o link que você mandar e devolve o endereço da imagem, para enviar como imagem numa mensagem. Para o QR Code de um fluxo, a tela tem o [Gerador de Código QR](https://help.nextags.com.br/tutoriais/ferramentas/qr-code/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto ou o link que vai no QR Code. | ```json { "text": "https://wa.me/5511988776655" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/qrcode" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=https://wa.me/5511988776655' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O endereço da imagem, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O endereço da imagem do QR Code. | ```json { "data": "https://exemplo.com.br/qrcode.png" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Converter texto para minúsculas > Passa o texto para letras minúsculas. Endereço: https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-minusculas/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/text_to_lower X-ACCESS-TOKEN: ``` Passa o texto para letras minúsculas. Use para padronizar um e-mail antes de comparar, salvar ou gerar um hash. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | ```json { "text": "ANA@EXEMPLO.COM.BR" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/text_to_lower" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=ANA@EXEMPLO.COM.BR' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto em minúsculas, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto em minúsculas. | ```json { "data": "ana@exemplo.com.br" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Converter texto para maiúsculas > Passa o texto para letras maiúsculas. Endereço: https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-maiusculas/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/text_to_upper X-ACCESS-TOKEN: ``` Passa o texto para letras maiúsculas. Use para padronizar códigos, como o de um cupom ou de um pedido. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | ```json { "text": "bemvindo10" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/text_to_upper" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=bemvindo10' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto em maiúsculas, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto em maiúsculas. | ```json { "data": "BEMVINDO10" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Contar os caracteres de um texto > Conta os caracteres de um texto. Endereço: https://docs.nextags.com.br/referencia/ferramentas/contar-os-caracteres-de-um-texto/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/text_length X-ACCESS-TOKEN: ``` Conta os caracteres de um texto. Use para conferir um dado antes de seguir, como o celular com DDI e DDD, que tem 13 dígitos no Brasil. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | ```json { "text": "5511988776655" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/text_length" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=5511988776655' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O tamanho, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | integer | Quantos caracteres o texto tem. | ```json { "data": 13 } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Recortar parte de um texto > Recorta um pedaço do texto: a partir da posição offset (o primeiro caractere é a posição 0), com length caracteres; sem length, vai até o fim. Endereço: https://docs.nextags.com.br/referencia/ferramentas/recortar-parte-de-um-texto/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/substring X-ACCESS-TOKEN: ``` Recorta um pedaço do texto: a partir da posição `offset` (o primeiro caractere é a posição 0), com `length` caracteres; sem `length`, vai até o fim. No celular `5511988776655`, o DDD está na posição 2, com 2 caracteres. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | | `offset` | integer | sim | A posição onde o recorte começa, contando do 0. | | `length` | integer | não | Quantos caracteres recortar. Sem ele, vai até o fim do texto. | ```json { "text": "5511988776655", "offset": 2, "length": 2 } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/substring" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=5511988776655' \ --data-urlencode 'offset=2' \ --data-urlencode 'length=2' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O pedaço recortado, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O pedaço recortado. | ```json { "data": "11" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Substituir um texto > Troca, no texto, todas as vezes que um trecho aparece por outro: com . Endereço: https://docs.nextags.com.br/referencia/ferramentas/substituir-um-texto/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/text_replace X-ACCESS-TOKEN: ``` Troca, no texto, todas as vezes que um trecho aparece por outro: com `.` trocado por `,`, o preço `49.90` vira `49,90`. Para várias trocas de uma vez, use [Substituir vários textos](https://docs.nextags.com.br/referencia/ferramentas/substituir-varios-textos/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | | `search` | string | sim | O trecho a procurar. | | `replace` | string | sim | O que entra no lugar. | ```json { "text": "49.90", "search": ".", "replace": "," } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/text_replace" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=49.90' \ --data-urlencode 'search=.' \ --data-urlencode 'replace=,' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto com as trocas, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto com as trocas. | ```json { "data": "49,90" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Substituir vários textos > Faz várias trocas de uma vez: cada item de search é trocado pelo item na mesma posição de replace. Endereço: https://docs.nextags.com.br/referencia/ferramentas/substituir-varios-textos/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/text_replaces X-ACCESS-TOKEN: ``` Faz várias trocas de uma vez: cada item de `search` é trocado pelo item na mesma posição de `replace`. No formulário, cada item da lista vai num par próprio, com o nome seguido de colchetes: `search[]=...&search[]=...` (veja os exemplos de código). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `text` | string | sim | O texto. | | `search` | array de string | sim | Os trechos a procurar, na ordem. | | `replace` | array de string | sim | O que entra no lugar de cada trecho, na mesma ordem de `search`. | ```json { "text": "Olá, {nome}! Seu pedido {pedido} saiu para entrega.", "search": [ "{nome}", "{pedido}" ], "replace": [ "Ana", "PED-1001" ] } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/text_replaces" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'text=Olá, {nome}! Seu pedido {pedido} saiu para entrega.' \ --data-urlencode 'search[]={nome}' \ --data-urlencode 'search[]={pedido}' \ --data-urlencode 'replace[]=Ana' \ --data-urlencode 'replace[]=PED-1001' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O texto com as trocas, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O texto com as trocas. | ```json { "data": "Olá, Ana! Seu pedido PED-1001 saiu para entrega." } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Ler os parâmetros de uma URL > Lê os parâmetros de uma URL (o que vem depois do ?) e devolve cada um com o seu valor. Endereço: https://docs.nextags.com.br/referencia/ferramentas/ler-os-parametros-de-uma-url/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/get_url_parameters X-ACCESS-TOKEN: ``` Lê os parâmetros de uma URL (o que vem depois do `?`) e devolve cada um com o seu valor. Use para pegar a origem de quem chegou por um link com UTM, como `utm_source` e `utm_campaign`. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `url` | string | sim | A URL completa, com os parâmetros. | ```json { "url": "https://loja.exemplo.com.br/?utm_source=instagram&utm_campaign=black-friday&ref=ana" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/get_url_parameters" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'url=https://loja.exemplo.com.br/?utm_source=instagram&utm_campaign=black-friday&ref=ana' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso Os parâmetros, em `data`: um campo para cada parâmetro da URL, com o nome e o valor. | Campo | Tipo | Descrição | |---|---|---| | `data` | object | Os parâmetros da URL. Cada parâmetro vira um campo deste objeto, com o mesmo nome. | ```json { "data": { "utm_source": "instagram", "utm_campaign": "black-friday", "ref": "ana" } } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Devolver o JSON enviado (eco) > Devolve, igual, o JSON que você mandar. Endereço: https://docs.nextags.com.br/referencia/ferramentas/devolver-o-json-enviado-eco/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/echo X-ACCESS-TOKEN: ``` Devolve, igual, o JSON que você mandar. Serve para gerar mensagens dinâmicas na [requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) do fluxo sem ter um servidor seu: monte no corpo o JSON de [mensagens e ações](https://docs.nextags.com.br/comecar/mensagens-e-acoes/), com as variáveis do contato, e a resposta traz esse JSON de volta. Veja [Requisição externa: o fluxo chama o seu sistema](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (JSON) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `messages` | array de objeto Mensagem | não | Por exemplo, as mensagens do conteúdo dinâmico. O eco aceita qualquer JSON e devolve igual: estes campos são só o uso mais comum. | | `actions` | array de objeto Ação | não | Por exemplo, as ações do conteúdo dinâmico. | | `actions[].action` | string | sim | Valores: `add_tag`, `remove_tag`, `set_field_value`, `unset_field_value`, `send_flow`, `transfer_conversation_to`, `assign_conversation`, `unassign_conversation`. | | `actions[].tag_name` | string | não | O nome da etiqueta (add_tag, remove_tag). | | `actions[].field_name` | string | não | O nome do campo (set_field_value, unset_field_value). | | `actions[].value` | string | não | O valor do campo (set_field_value) ou human/bot (transfer_conversation_to). | | `actions[].flow_id` | integer ou string | não | O ID do fluxo (send_flow). | | `actions[].admin_id` | integer ou string | não | O ID do administrador (assign_conversation). | ```json { "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" } ] } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/echo" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" } ] }' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O mesmo JSON que veio no corpo. | Campo | Tipo | Descrição | |---|---|---| | `messages` | array de objeto Mensagem | Por exemplo, as mensagens do conteúdo dinâmico. O eco aceita qualquer JSON e devolve igual: estes campos são só o uso mais comum. | | `actions` | array de objeto Ação | Por exemplo, as ações do conteúdo dinâmico. | | `actions[].action` | string | Valores: `add_tag`, `remove_tag`, `set_field_value`, `unset_field_value`, `send_flow`, `transfer_conversation_to`, `assign_conversation`, `unassign_conversation`. | | `actions[].tag_name` | string | O nome da etiqueta (add_tag, remove_tag). | | `actions[].field_name` | string | O nome do campo (set_field_value, unset_field_value). | | `actions[].value` | string | O valor do campo (set_field_value) ou human/bot (transfer_conversation_to). | | `actions[].flow_id` | integer ou string | O ID do fluxo (send_flow). | | `actions[].admin_id` | integer ou string | O ID do administrador (assign_conversation). | ```json { "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" } ] } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Gerar um hash > Gera o hash de um texto com o algoritmo escolhido; sem algo, usa o SHA-256. Endereço: https://docs.nextags.com.br/referencia/ferramentas/gerar-um-hash/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/hash X-ACCESS-TOKEN: ``` Gera o hash de um texto com o algoritmo escolhido; sem `algo`, usa o SHA-256. Use, por exemplo, para mandar o e-mail do contato com hash SHA-256, como a API de Conversões da Meta pede (antes, passe o e-mail para minúsculas com [Converter texto para minúsculas](https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-minusculas/)). Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `data` | string | sim | O texto. | | `algo` | string | não | O algoritmo, como `sha256`, `sha1` ou `md5`. Sem ele, `sha256`. Padrão: `sha256`. | ```json { "data": "ana@exemplo.com.br", "algo": "sha256" } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/hash" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'data=ana@exemplo.com.br' \ --data-urlencode 'algo=sha256' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso O hash, em `data`. | Campo | Tipo | Descrição | |---|---|---| | `data` | string | O hash, em hexadecimal. | ```json { "data": "9908ab973926622870fbcc257bf5c75e507d89d24698137563dab84b1e2cb423" } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Calcular a distância entre duas coordenadas > Calcula a distância entre dois pontos de latitude e longitude, em metros e em milhas. Endereço: https://docs.nextags.com.br/referencia/ferramentas/calcular-a-distancia-entre-duas-coordenadas/ Tipo: Endpoint ```http POST https://app.nextagsai.com.br/api/tools/location_distance X-ACCESS-TOKEN: ``` Calcula a distância entre dois pontos de latitude e longitude, em metros e em milhas. Use para saber se o contato está na área de entrega ou para calcular o frete a partir da localização que ele mandou ([Pedir e enviar localização](https://help.nextags.com.br/tutoriais/fluxos/localizacao/)). Com uma chave da API do Google Maps em `googleMapsApiKey`, o cálculo é feito pelo Google Maps. Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). ## Corpo da requisição (formulário, application/x-www-form-urlencoded) | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `source_latitude` | number | sim | A latitude do ponto de partida, com ponto decimal (`-23.5614`). | | `source_longitude` | number | sim | A longitude do ponto de partida (`-46.6559`). | | `destination_latitude` | number | sim | A latitude do destino. | | `destination_longitude` | number | sim | A longitude do destino. | | `googleMapsApiKey` | string | não | Opcional: uma chave da API do Google Maps. Com ela, a distância é calculada pelo Google Maps. | ```json { "source_latitude": -23.5614, "source_longitude": -46.6559, "destination_latitude": -23.5505, "destination_longitude": -46.6333 } ``` ## Exemplo ```bash curl -X POST "https://app.nextagsai.com.br/api/tools/location_distance" \ -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \ --data-urlencode 'source_latitude=-23.5614' \ --data-urlencode 'source_longitude=-46.6559' \ --data-urlencode 'destination_latitude=-23.5505' \ --data-urlencode 'destination_longitude=-46.6333' ``` Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json). ## Respostas ### 200 Sucesso A distância, em metros e em milhas. | Campo | Tipo | Descrição | |---|---|---| | `meters` | number | A distância em metros. | | `miles` | number | A distância em milhas. | ```json { "meters": 2603, "miles": 1.617424 } ``` ### 401 Chave inválida A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/). ```json { "error": { "code": 401, "message": "No valid API key provided." } } ``` --- # Novidades da API > Mudanças na API e nos webhooks, com data e o que fazer. Endereço: https://docs.nextags.com.br/novidades/ Tipo: Seção _Conteúdo em produção: o texto completo desta página ainda está sendo escrito._