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