Propriedades de clientes no Help Scout: configuração, limites e API
Kira
Katelin Teen
Última edição 6 de novembro de 2026

Uma propriedade de cliente do Help Scout é um campo de dados personalizado no perfil do contato. Você pode criar até 50 contact properties e 50 company properties, em cinco tipos, e elas aparecem na barra lateral da conversa de cada caixa. Preencha-as manualmente, com Zapier, a API da caixa ou o Beacon identify, e use-as para direcionar workflows e respostas salvas em Plus ou Pro. Use propriedades para fatos sobre a pessoa e campos personalizados para fatos sobre uma conversa. O CLI do eesel permite que um agente de código conecte o eesel ao Help Scout e teste respostas antes, mesmo que um administrador do Help Scout ainda precise aprovar a conexão.
O que são propriedades de clientes no Help Scout?
São os campos de "quem é essa pessoa". O artigo de propriedades do Help Scout agora intitula o recurso Contact and Company Properties, e diz que você escolhe quais detalhes acompanhar, adiciona-os manualmente ou programaticamente, e sua equipe os vê em cada conversa. A URL e a API ainda dizem "customer", por isso os dois nomes circulam.

Conteúdo típico, pelos próprios exemplos do Help Scout: um ID de usuário, fuso horário, ID de plano, status de cobrança, nome da conta ou a data em que alguém se tornou contato. O valor prático é que um agente que abre uma conversa não precisa mais abrir a ferramenta de cobrança para saber se o remetente está num teste gratuito ou num plano anual. Se você ainda está decidindo a ferramenta, minhas páginas análise do Help Scout e alternativas ao Help Scout cobrem o panorama mais amplo.
Como criar uma propriedade, e quais são os limites?
Vá em Settings, depois Properties, depois escolha Contact ou Company. Somente Account Owners e Administrators podem criá-las ou editá-las, embora todos possam vê-las. As regras que decidem se sua configuração se sustenta:
- Cinquenta de cada. Até
50contact properties e50company properties, globais em todas as caixas. - Cinco tipos. Texto (até 255 caracteres), número, URL (exibida como link clicável), data e lista suspensa (até 100 opções).
- Nome com até 100 caracteres. O nome é o rótulo que os agentes veem.
- O ID diferencia maiúsculas e minúsculas. É gerado a partir do nome, você pode substituí-lo, e permite apenas hífens e underscores.
- Tipo e ID são fixos. Você pode editar o nome exibido depois, mas não o tipo nem o ID.
- A exclusão é imediata. O Help Scout diz que não há como restaurar uma propriedade excluída, e uma nova propriedade com o mesmo ID não traz os dados de volta.
O ID fixo é o que mais importa. Se o Zapier ou o código do seu app enviam planName e alguém cria a propriedade como PlanName, o valor some silenciosamente. Copie o ID da página de settings (clicar nele copia para a área de transferência) e passe essa string exata para seus desenvolvedores. Os campos de ticket personalizados do Zendesk têm um bloqueio semelhante no tipo de campo, assim como os campos de ticket do Freshdesk.
Quais planos do Help Scout incluem propriedades de clientes?
A documentação dá duas respostas levemente diferentes, então aqui estão as duas. A caixa de planos do artigo de propriedades diz todos os planos pagos. A referência da API JavaScript do Beacon diz que propriedades de clientes estão disponíveis em Standard, Plus e Pro, com gestão de companies em Plus e Pro. O plano Free não é citado em nenhuma das duas, então eu verificaria antes de construir sobre ele.
| Plano | Preço na página de preços | Propriedades | Uso em workflows, respostas salvas, visualizações |
|---|---|---|---|
| Free | 5 usuários, 1 caixa, 1 site de Docs | Não listado | Não listado |
| Standard | $25 por usuário por mês | Sim | Não, segundo a documentação |
| Plus | $45 por usuário por mês | Sim | Sim |
| Pro | $75 por usuário por mês | Sim | Sim |
A página de preços descreve o recurso como coletar e exibir até 50 dados adicionais do cliente, e coloca workflows avançados em Plus. Os preços são tarifas por usuário com um alternador mensal e anual. Meu artigo sobre preços do Help Scout calcula o custo de uma equipe inteira. A divisão para lembrar: equipes no Standard podem armazenar e ver propriedades, mas agir sobre elas automaticamente é um recurso do Plus.
Como as propriedades são preenchidas?
Quatro caminhos, e o primeiro é por onde todo mundo começa. O artigo de propriedades percorre cada um.

- Manualmente. Clique numa propriedade no cartão da barra lateral para editá-la no local, ou abra Customers, depois Contacts, depois a aba Properties no perfil.
- Zapier. A ação Create Customer lista suas contact properties sob os campos de perfil padrão. A ação Update Customer Properties precisa do Contact ID, então adicione um passo Find Customer primeiro se o seu gatilho não fornecer um. Minhas notas sobre IA do Zapier cobrem o lado da automação.
- Beacon identify. Passe o ID exato da propriedade como chave em
Beacon('identify', ...). Os valores sincronizam do seu sistema de cobrança ou app cada vez que o visitante carrega o Beacon. - A API da caixa. Para importações em massa ou uma sincronização contínua, o endpoint Update Customer Properties recebe um
PATCHem/v2/customers/{id}/properties.
Beacon('identify', {
name: 'Steve Aoki',
email: 'steve@aoki.com',
signature: 'YOUR_SERVER_GENERATED_SIGNATURE_HERE',
Subscription: 'Free Plan',
'Favorite-Movie': '' // uma string vazia remove este valor
})
Segundo a referência da API JavaScript do Beacon, as chaves precisam corresponder exatamente a IDs de propriedades existentes, incluindo maiúsculas e minúsculas, os tipos de valor precisam corresponder, e propriedades ausentes numa chamada não são tocadas. As company properties são mais restritas: a documentação diz que você pode atualizá-las pela API pública, enquanto Zapier e Beacon identify ainda não as suportam. Combine identify com Secure Mode se quiser perfis assinados, como coberto no meu artigo sobre campos de formulário do Beacon do Help Scout e no guia de integrações do Help Scout.
O que a API aceita para cada tipo?
A API é mais estrita que a interface, e é aí que as importações em massa costumam falhar. Tudo isto vem da referência do endpoint de atualização:
| Tipo de propriedade | Formato da API | Exemplo |
|---|---|---|
| Número | Inteiro | 5 |
| Texto | String, máximo 255 caracteres | "green" |
| URL | URL válida | "google.com" |
| Data | YYYY-MM-DD | "2019-01-02" |
| Lista suspensa | id ou label da opção | "Tesla" |
As operações são apenas replace e remove, o caminho é o slug da propriedade com uma barra inicial, e um sucesso retorna 204 No Content. A propriedade precisa ser criada antes, no app web ou pelo endpoint Create Property Definitions, e GET /v2/customer-properties lista as definições com os IDs das suas opções de lista suspensa. Ao ler um cliente, cada propriedade volta com seu value, um rótulo text para listas suspensas e um objeto source que identifica qual subsistema a atualizou por último.
Como as propriedades são diferentes dos campos personalizados de conversa?
As propriedades vivem na pessoa, então a seguem em cada conversa. Os campos personalizados vivem numa conversa e, como cobri no meu artigo sobre campos de formulário do Beacon, estão atados a uma caixa, com até 10 por caixa em Plus e Pro. O conselho do Help Scout é direto: use propriedades para detalhes específicos de um contato, e campos personalizados para detalhes situacionais, como o tipo de pergunta.

Minha regra geral: se a resposta ainda seria verdadeira no mês seguinte numa conversa diferente, é uma propriedade. Se descreve a pergunta de hoje, é um campo. Uma conversa movida entre caixas mantém as propriedades do cliente porque são globais, mais uma razão para colocar ali os dados de plano e conta. Outras ferramentas dividem da mesma forma, como em segmentos de usuário do Zendesk e tags de CRM.
Onde os agentes veem propriedades, e podem pesquisá-las?
Na barra lateral da conversa, embutidas nos cartões de Customer e Company. Cada pessoa pode mostrar ou ocultar propriedades pelo menu de três pontos do cartão, então a visão organizada de um colega não muda a de outro. Clicar no avatar abre um painel combinado com os detalhes do perfil e as propriedades, e clicar numa propriedade a edita no local. A página de perfil tem uma aba Properties dedicada.

As propriedades também aparecem na busca global sob o título Customer Properties. Em Plus e Pro, as condições de workflow do Help Scout incluem uma condição Customer Property, então um workflow pode buscar conversas que incluam ou excluam um valor, e o mesmo artigo diz que propriedades podem ser usadas em respostas salvas e visualizações de caixa. Isso transforma um nome de plano salvo em roteamento, e meus guias de atribuição automática de tickets, roteamento inteligente e triagem de tickets cobrem o que fazer depois. As respostas salvas do Help Scout são o outro lugar onde um nome de plano salvo compensa.
Quais propriedades vale a pena criar primeiro?
Comece pelas três que mudam como você responde, não pelas que simplesmente estão disponíveis.
- Plano ou nível. Uma lista suspensa (
planName) permite que um workflow marque níveis mais altos e os atribua à sua fila mais sênior, e é a propriedade individual mais útil para as melhores práticas de SLA. - ID de conta ou usuário. Uma propriedade de texto permite que um agente a cole diretamente na sua ferramenta de admin. Use uma propriedade de URL em vez disso se puder vincular ao perfil de cobrança, já que URLs são exibidas como links clicáveis.
- Data de renovação ou início. Uma propriedade de data responde "há quanto tempo são clientes" sem precisar buscar.
Evite qualquer coisa que você só preencheria para um punhado de pessoas. Uma propriedade vazia em 90 por cento dos perfis é desordem na barra lateral, e você tem um limite rígido de 50. Mantenha as opções da lista suspensa curtas, porque a API aceita o rótulo da opção, e renomear pode quebrar uma sincronização que envia o texto antigo.
Onde um agente de IA entra com propriedades de clientes?
O eesel é um colega de IA para helpdesk que trabalha dentro da caixa do Help Scout. Sua documentação de configuração do Help Scout lista uma ação Find customer que encontra clientes por email ou nome e, em chats de equipe, também lê detalhes de contato, as notas da sua equipe e seus valores de propriedade, como o plano. Uma ação List properties lista as propriedades de cliente e organização que sua conta guarda. A documentação também diz que ações marcadas como somente chats de equipe só funcionam quando um colega pergunta ao agente, no chat do dashboard ou numa execução agendada, e não estão disponíveis enquanto ele responde a um cliente.
Então aqui está o resumo honesto. Um colega pode perguntar ao eesel "em que plano está esse cliente?" e obter uma resposta do perfil. Enquanto o eesel redige uma resposta para um cliente, a leitura documentada de propriedades não faz parte desse fluxo, e eu não encontrei nenhuma ação documentada que escreva propriedades. O padrão que eu usaria é deixar um workflow do Help Scout transformar a propriedade numa tag em Plus ou Pro, e então deixar o agente agir sobre a tag, como descrevo em triagem de tickets com IA. Meus artigos sobre agente de IA do Help Scout e IA para Help Scout detalham a configuração.
Meu exemplo real mais próximo está em outro helpdesk. A MentorShow, uma plataforma francesa de aprendizado online, roda o eesel sobre o HubSpot Service Hub. Suas instruções dizem ao agente para ler o thread e o registro do HubSpot do membro, incluindo status de assinatura, próxima data de renovação e tickets anteriores, porque um problema de login de alguém sem assinatura ativa não é um problema de login. Entre 8 de agosto e 8 de setembro de 2026, o eesel leu cerca de 1.200 conversas e tickets do HubSpot e escreveu 432 rascunhos para a equipe, cada um deixado como nota interna para uma pessoa enviar. É esse o trabalho que uma propriedade de plano faz no Help Scout: dar a quem responde o contexto da conta antes que a primeira palavra seja escrita. Veja também a integração com HubSpot.
Para um agente de código, o CLI do eesel pode executar npx @eesel/cli integrations connect helpscout_v2 para mostrar as opções de conexão, e eesel chat permite fazer perguntas de teste antes. Conectar a caixa ainda precisa que um administrador ou proprietário de conta do Help Scout aprove isso no navegador.
Quais erros evitar com propriedades?
- Um ID que não corresponde.
planNamenão éPlanName. Copie o ID da página de settings. - Excluir uma propriedade para organizar. Os dados desaparecem de cada contato e não podem ser restaurados.
- Armazenar um fato de conversa como propriedade. "Tipo de solicitação" se sobrescreve a cada nova conversa. Use um campo personalizado.
- Tipos de valor errados. Uma data precisa ser
YYYY-MM-DDpela API, e um número precisa ser um inteiro. - Construir roteamento sobre o Standard. A condição de workflow precisa de Plus ou Pro.
- Esperar company properties em qualquer caminho. Zapier e Beacon identify ainda não as suportam.
Teste um contato de ponta a ponta antes de uma importação em massa. Defina o valor, encontre-o na barra lateral, dispare o workflow e verifique o resultado. Se mais tarde adicionar um agente, comece com Leave draft reply e mantenha Send reply desativado até que as respostas se mostrem confiáveis, algo que explico em workflows de aprovação de suporte ao cliente e transferência de agente de IA. Para configurações relacionadas do Help Scout, veja conversas adiadas, detecção de colisão e desvio de tickets com IA. Resolução no primeiro contato explica por que o contexto no perfil compensa.
Teste o eesel com sua caixa do Help Scout
Se suas propriedades já dizem quem está em qual plano, o eesel para Help Scout é a próxima camada que eu adicionaria. Ele trabalha dentro da caixa, lê seu site de Docs e conversas passadas, e deixa um colega perguntar sobre o plano de um cliente a partir do perfil. Você pode testar o eesel com 100 créditos gratuitos por 7 dias, depois os planos pagos começam em $299 por mês para 500 créditos, onde um ticket ou chat é um crédito (preços do eesel). Comparando opções? Veja meu panorama melhor IA para Help Scout, ou Help Scout vs Front.
Perguntas frequentes
O que são propriedades de clientes no Help Scout?
Quantas propriedades de clientes é possível criar no Help Scout?
50 contact properties e 50 company properties por conta, válidas em todas as caixas. Cada uma tem um dos cinco tipos: texto, número, URL, data ou lista suspensa. Veja preços do Help Scout para o custo de cada plano.Quais planos do Help Scout incluem propriedades de clientes?
Como atualizar propriedades de clientes do Help Scout com a API?
PATCH para /v2/customers/{id}/properties com operações replace ou remove, usando o slug da propriedade como caminho. A propriedade precisa existir antes. Meu guia da API do Help Scout cobre a API mais amplamente.Qual é a diferença entre propriedades de clientes e campos personalizados no Help Scout?
O Beacon identify pode preencher propriedades de clientes do Help Scout?
Beacon('identify', ...) e o valor sincroniza com o contato cada vez que ele carrega o Beacon. Definir um valor como string vazia o remove. Veja meu artigo sobre campos de formulário do Beacon.