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.

Guia10 min

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.
O ID do contato. Veja Encontrar um contato pelo e-mail ou telefone.
O campo personalizado criado na conta (neste guia, cidade, do tipo Texto). Veja Criar campos personalizados.
Para o último passo: um campo do bot e o ID dele (neste guia, 3101). Veja Campos do bot.

Passo a passo

Passo 1: Ache a etiqueta pelo nome

Use 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

curl "https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip');
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);

{"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.

Passo 2: Crie a etiqueta, se ela não existir

Use Criar etiqueta. Esta chamada recebe formulário, com o nome em name:

Criar etiqueta

curl -X POST "https://app.nextagsai.com.br/api/accounts/tags" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'name=cliente-vip'

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/tags');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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:

{"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, com o ID do contato e o da etiqueta no caminho. A chamada não tem corpo.

Adicionar etiqueta ao contato

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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, no mesmo endereço, com DELETE:

Remover etiqueta do contato

curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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: use com cuidado.

Passo 5: Ache o campo pelo nome

Use Buscar campo pelo nome. A resposta traz o ID e o tipo do campo:

Buscar campo pelo nome

curl "https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade');
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);

{"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.

Passo 6: Preencha o campo do contato

Use Preencher campo do contato. Esta chamada recebe formulário, com o valor em value:

Preencher campo do contato

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'

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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, no mesmo endereço, com DELETE:

Limpar campo do contato

curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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, também com formulário e o valor em value:

Preencher campo do bot

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'

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/bot_fields/3101');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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 (GET no mesmo endereço); para limpar, Limpar campo do bot (DELETE).

Pronto: como conferir

Consulte o campo do contato:

Consultar campo do contato

curl "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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);

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
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001');
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);

{"id": 3001, "name": "cidade", "type": 0, "value": "São Paulo"}

Para todas as etiquetas do contato, use Listar etiquetas do contato; para todos os campos, 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.

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. Veja Mensagens e ações em JSON.

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.

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 ou 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.

Faça com a IA

Copie o pedido e cole no ChatGPT ou no Claude.

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.

Obrigado! Sua resposta ajuda a melhorar a central.