Pular para o conteúdo

Atributos personalizados

Atributos personalizados (custom attributes) são campos extras que você cria para guardar informações específicas do seu negócio — CPF, código de cliente, plano contratado, data de cadastro, NPS anterior, valor de LTV. Tudo que os campos padrão não cobrem. Esta página explica como criar, organizar e usar atributos para personalizar o atendimento e segmentar a base.

São campos extras que você define uma vez em Configurações e que aparecem em:

  • Tela do contato (sidebar direita da conversa, aba Contato)
  • Tela da conversa (sidebar direita, aba Conversa)
  • Formulário de criação de contato
  • Filtros de busca avançada
  • Variáveis em templates de resposta rápida
  • Critérios em workflows
  • Critérios em segmentos para disparos

Cada atributo pertence a um dos dois escopos:

EscopoVale paraExemplos
ContatoDados da pessoa (vale em qualquer conversa)CPF, código de cliente, data de cadastro, plano
ConversaDados específicos daquele atendimentoNúmero do pedido, motivo do contato, urgência, departamento

Mesmo dado pode existir em ambos os escopos se fizer sentido (raro). Geralmente, dados perenes vão em contato; dados episódicos vão em conversa.

São oito:

TipoExemplo de usoObservações
TextoCPF, código de cliente, observaçãoSem validação, a menos que você ligue o regex
NúmeroIdade, quantidade de pedidosAceita decimais
MoedaValor de contrato, ticket médioExibido como dinheiro
PorcentagemDesconto combinado, taxaExibido com %
LinkURL do pedido, perfil em rede socialVira link clicável no painel
DataData de cadastro, próximo vencimentoFormato AAAA-MM-DD
ListaPlano, segmento, prioridadeVocê define as opções
CheckboxCliente VIP, aceita ligaçãoSim ou não

Qualquer atributo pode ganhar validação por expressão regular: você liga a opção, informa o padrão e uma dica que aparece para quem preenche errado.

É o que impede CPF com letra, placa fora do formato e código de cliente com espaço sobrando. Vale muito a pena em campo que alimenta integração.

SeloQuer dizer
Pré-chatO atributo é pedido no formulário antes da conversa começar, no widget do site
ResoluçãoO atributo é obrigatório na hora de resolver a conversa

O segundo vem de Config. → Atendimento → Resolução de conversas. Veja resolução de conversas.

Atributos personalizados: o formulário de novo campo personalizado, com o seletor de tipo aberto

  1. Acesse Config. → Atendimento → Atributos.
  2. Clique em Adicionar atributo personalizado.
  3. Preencha:
    • Nome de exibição (ex: “CPF do cliente”)
    • Descrição (opcional, ajuda outros admins entenderem)
    • Tipo de dado (texto, número, lista etc.)
    • Aplica-se a (Contato ou Conversa)
    • Chave interna (gerada automaticamente, ex: cpf_do_cliente — usada em API e variáveis)
  4. Se for tipo Lista, adicione as opções (uma por linha).
  5. Salve.

A partir deste momento, o atributo aparece em todos os contatos/conversas.

  • Use nomes claros (“CPF do cliente”, não “CPF”)
  • Evite abreviações (“Valor do plano mensal”, não “Vlr Plno”)
  • Para listas, padronize as opções (“Pequeno / Médio / Grande”, não “P / M / G” — fica confuso no relatório)
  • Pense no agente que vai ler em tempo real durante atendimento

Atributos personalizados: os campos personalizados na ficha do contato, preenchidos

  1. Abra um contato ou conversa.
  2. No painel direito, role até a seção Atributos personalizados.
  3. Clique no atributo desejado.
  4. Digite/selecione o valor.
  5. Salva automaticamente ao sair do campo.

Pela importação. O nome da coluna na planilha não importa: na etapa de Mapeamento você associa cada coluna a um campo, e os atributos personalizados aparecem num grupo próprio na lista.

Planilha assim funciona:

Nome E-mail CPF Plano
Maria Silva [email protected] 123.456.789-00 premium

O que precisa existir antes é o atributo. Só aparecem no mapeamento os que já foram criados na conta.

Workflow pode preencher atributos automaticamente:

GATILHO: Mensagem recebida
CONDIÇÃO: contém "comprei o plano X"
AÇÃO: Atualizar campo → plano = "X"

A ação se chama Atualizar campo no editor do workflow, e vale tanto para campo do contato quanto do negócio.

Terminal window
curl -X PATCH "https://app.smart2.com.br/api/v1/accounts/1/contacts/123" \
-H "api_access_token: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"custom_attributes": {
"cpf": "123.456.789-00",
"plano": "premium"
}
}'

Detalhes em API — Contatos.

No widget instalado no seu site:

window.$chatwoot.setCustomAttributes({
cpf: '123.456.789-00',
plano: 'premium',
ultimo_pedido_valor: 350.00
});

Útil para passar dados do cliente logado direto da sua aplicação para o app.smart.

Variáveis com sintaxe {{contact.custom_attribute.NOME}} ou {{conversation.custom_attribute.NOME}}:

Olá {{contact.first_name}},
Confirmo que seu plano {{contact.custom_attribute.plano}} foi renovado.
Próximo vencimento: {{contact.custom_attribute.proximo_vencimento}}.
Equipe Suaempresa

Atributos viram critérios poderosos em workflows:

GATILHO: Mensagem recebida
CONDIÇÃO: contact.custom_attribute.plano = "premium"
E mensagem contém "cancelar"
AÇÃO: Atribuir time → Retenção VIP
Adicionar label → risco-cancelamento
Adicionar nota privada → "cliente premium falou em cancelar"

Veja Workflows.

Todo atributo que você cria vira critério disponível no montador de segmento, do mesmo jeito que os campos de fábrica. Um segmento de plano premium, por exemplo, se escreve assim:

custom_attribute.plano = "premium"

E o segmento resultante serve de público para disparo, para fluxo de marketing e para filtro de lista.

➡️ Como montar, combinar com E/OU e testar antes de aplicar: Segmentos.

Atributos personalizados: o painel do contato dentro da conversa, com os campos personalizados

O agente vê todos os atributos preenchidos no painel direito da conversa, na aba Contato:

ATRIBUTOS PERSONALIZADOS
CPF 123.456.789-00
Código de cliente ERP-2451
Plano Premium
Data de cadastro 2023-08-15
Cliente VIP ✓ Sim
URL do pedido [abrir]

Permite contextualizar atendimento sem precisar consultar outro sistema.

Atributos personalizados: a lista de campos personalizados, com as ações de editar e excluir

  1. Config. → Atendimento → Atributos.
  2. Encontre o atributo na lista.
  3. Editar — muda o nome de exibição, a descrição e as opções da lista. A chave não muda, e é ela que aparece em variável, filtro e API.
  4. Excluir — tira o atributo da lista e leva junto os valores preenchidos nos contatos e nas conversas.
  • Atributos de contato: cpf, total_de_pedidos, valor_lifetime, ultima_compra_data
  • Atributos de conversa: numero_do_pedido, motivo (devolução / troca / dúvida / suporte)
  • Atributos de contato: cpf, data_nascimento, convenio, procedimento_proximo
  • Atributos de conversa: agendamento_data, profissional_solicitado
  • Atributos de contato: cnpj_empresa, cargo, plano, mrr
  • Atributos de conversa: tipo_de_demanda (técnica / comercial / financeira), prioridade_acordada
  • Atributos de contato: cpf, interesse (compra / aluguel), regiao_preferida, orcamento_max
  • Atributos de conversa: imovel_de_interesse_id, visita_agendada

Existe limite de atributos? Sim, máximo de 50 atributos personalizados por escopo (contato + conversa). Mais que isso vira difícil de gerenciar.

Posso renomear um atributo sem perder os dados? Sim. Editar o nome de exibição não mexe nos valores nem na chave interna. Apenas o que aparece para usuários muda.

Posso ter atributo obrigatório? Não nativamente. Para forçar preenchimento, use workflow que valida e alerta agente quando atributo está vazio, ou crie um formulário pré-chat no Web Widget.

Atributos aparecem na busca? Sim. Você pode buscar por valor de atributo na busca global (Ctrl + K) ou em filtros avançados.

Cliente vê os atributos? Não. Atributos são privados para sua equipe. Cliente vê apenas as mensagens enviadas.

Posso vincular atributo a integração externa (sync com CRM)? Sim, via API. Configure webhook para evento contact.updated para sincronizar mudanças com seu CRM externo.

Atributo do tipo Lista permite múltiplos valores selecionados? Não. Lista é dropdown de uma única seleção. Para múltiplas tags, use Etiquetas (labels) — que aceitam várias por contato.