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.
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, Campos do bot e 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 aceita só os tipos
0a4. Os tipos5,6e7sã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
1794279600para 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, com name, type e description | A mesma chamada, com "isBotField": true e o value | Não se cria |
| Achar o ID | Listar campos personalizados ou Buscar campo pelo nome | Obter ID na tela (Identificadores) | Não tem ID: usa o nome |
| Ler | Listar campos do contato ou Consultar campo do contato | Consultar campo do bot | Consultar contato, como first_name e last_name |
| Gravar pelo ID | Preencher campo do contato, formulário com value | 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 ou a ação unset_field_value | Limpar campo do bot | Não se aplica |
As ações set_field_value e unset_field_value vão em Criar contato e em Enviar conteúdo. O formato está em Mensagens e ações em JSON.
Criar um campo personalizado:
{"name": "cidade", "type": 0, "description": "Cidade do contato"}A resposta traz o ID:
{"id": 3001, "name": "cidade"}Criar um campo do bot, já com o valor:
{
"name": "link_da_promocao",
"type": 0,
"isBotField": true,
"value": "https://seusistema.exemplo.com.br/promocao"
}Gravar um campo pelo nome, numa ação:
{"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 e preencha em custom_fields ao criar ou atualizar a oportunidade, com {"id": …, "value": …} ou {"name": …, "value": …}. Veja Criar e mover 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.
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.
Relacionados
Este conteúdo ajudou?
Obrigado! Sua resposta ajuda a melhorar a central.