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.
O que são atributos personalizados
Seção intitulada “O que são atributos personalizados”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
Escopo: contato vs conversa
Seção intitulada “Escopo: contato vs conversa”Cada atributo pertence a um dos dois escopos:
| Escopo | Vale para | Exemplos |
|---|---|---|
| Contato | Dados da pessoa (vale em qualquer conversa) | CPF, código de cliente, data de cadastro, plano |
| Conversa | Dados específicos daquele atendimento | Nú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.
Tipos de dado disponíveis
Seção intitulada “Tipos de dado disponíveis”São oito:
| Tipo | Exemplo de uso | Observações |
|---|---|---|
| Texto | CPF, código de cliente, observação | Sem validação, a menos que você ligue o regex |
| Número | Idade, quantidade de pedidos | Aceita decimais |
| Moeda | Valor de contrato, ticket médio | Exibido como dinheiro |
| Porcentagem | Desconto combinado, taxa | Exibido com % |
| Link | URL do pedido, perfil em rede social | Vira link clicável no painel |
| Data | Data de cadastro, próximo vencimento | Formato AAAA-MM-DD |
| Lista | Plano, segmento, prioridade | Você define as opções |
| Checkbox | Cliente VIP, aceita ligação | Sim ou não |
Validação por regex
Seção intitulada “Validação por regex”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.
Dois selos que aparecem na lista
Seção intitulada “Dois selos que aparecem na lista”| Selo | Quer dizer |
|---|---|
| Pré-chat | O atributo é pedido no formulário antes da conversa começar, no widget do site |
| Resolução | O atributo é obrigatório na hora de resolver a conversa |
O segundo vem de Config. → Atendimento → Resolução de conversas. Veja resolução de conversas.
Criar um atributo
Seção intitulada “Criar um atributo”Passo a passo
Seção intitulada “Passo a passo”
- Acesse Config. → Atendimento → Atributos.
- Clique em Adicionar atributo personalizado.
- 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)
- Se for tipo Lista, adicione as opções (uma por linha).
- Salve.
A partir deste momento, o atributo aparece em todos os contatos/conversas.
Boas práticas de nomenclatura
Seção intitulada “Boas práticas de nomenclatura”- 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
Preencher atributo
Seção intitulada “Preencher atributo”Manualmente
Seção intitulada “Manualmente”
- Abra um contato ou conversa.
- No painel direito, role até a seção Atributos personalizados.
- Clique no atributo desejado.
- Digite/selecione o valor.
- Salva automaticamente ao sair do campo.
Em massa
Seção intitulada “Em massa”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 PlanoMaria Silva [email protected] 123.456.789-00 premiumO que precisa existir antes é o atributo. Só aparecem no mapeamento os que já foram criados na conta.
Via workflow
Seção intitulada “Via workflow”Workflow pode preencher atributos automaticamente:
GATILHO: Mensagem recebidaCONDIÇÃ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.
Via API
Seção intitulada “Via API”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.
Via Web Widget
Seção intitulada “Via Web Widget”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.
Usar atributo em template
Seção intitulada “Usar atributo em template”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 SuaempresaUsar atributo em workflow
Seção intitulada “Usar atributo em workflow”Atributos viram critérios poderosos em workflows:
GATILHO: Mensagem recebidaCONDIÇÃ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.
Usar atributo em segmento
Seção intitulada “Usar atributo em segmento”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 do contato durante a conversa
Seção intitulada “Atributos do contato durante a conversa”
O agente vê todos os atributos preenchidos no painel direito da conversa, na aba Contato:
ATRIBUTOS PERSONALIZADOS
CPF 123.456.789-00Código de cliente ERP-2451Plano PremiumData de cadastro 2023-08-15Cliente VIP ✓ SimURL do pedido [abrir]Permite contextualizar atendimento sem precisar consultar outro sistema.
Editar ou excluir atributo
Seção intitulada “Editar ou excluir atributo”
- Config. → Atendimento → Atributos.
- Encontre o atributo na lista.
- 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.
- Excluir — tira o atributo da lista e leva junto os valores preenchidos nos contatos e nas conversas.
Casos de uso típicos
Seção intitulada “Casos de uso típicos”Para e-commerce
Seção intitulada “Para e-commerce”- 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)
Para serviços (clínica, salão)
Seção intitulada “Para serviços (clínica, salão)”- Atributos de contato:
cpf,data_nascimento,convenio,procedimento_proximo - Atributos de conversa:
agendamento_data,profissional_solicitado
Para B2B (SaaS, serviços corporativos)
Seção intitulada “Para B2B (SaaS, serviços corporativos)”- Atributos de contato:
cnpj_empresa,cargo,plano,mrr - Atributos de conversa:
tipo_de_demanda(técnica / comercial / financeira),prioridade_acordada
Para imobiliária
Seção intitulada “Para imobiliária”- Atributos de contato:
cpf,interesse(compra / aluguel),regiao_preferida,orcamento_max - Atributos de conversa:
imovel_de_interesse_id,visita_agendada
Dúvidas comuns
Seção intitulada “Dúvidas comuns”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.