Propriedades de contato

As propriedades de contato permitem anexar dados estruturados às conversas para além dos campos incorporados (e-mail, nome, userId). Ao contrário dos metadata de formato livre, as propriedades têm um esquema definido com tipos, rótulos e validação — à semelhança dos campos personalizados do HubSpot ou do Salesforce.

As propriedades são definidas por agente em Configurações do agente → Propriedades de contato. Cada propriedade tem:

Passe os valores das propriedades no campo properties de Respondo.identify(). As chaves devem corresponder às configurações de propriedades das Configurações do agente.

Respondo.identify({
  email: 'user@example.com',
  name: 'Jane Smith',
  userId: 'usr_456',
  properties: {
    account_type: 'enterprise',   // enum
    region: 'eu-west',            // string
    monthly_spend: '15000',       // number (passado como string)
    is_partner: 'true',           // boolean (passado como string)
    contract_end: '2026-12-31',   // date
    dashboard_url: 'https://app.example.com/org/123'  // url
  }
});

O Snippet de integração aparece automaticamente em Configurações do agente → Propriedades de contato assim que você define pelo menos uma propriedade, com todas as chaves das suas propriedades já preenchidas. Clique em Copiar para pegá-lo e cole-o no seu app. O snippet gerado também inclui um placeholder de userHash para a verificação de identidade (HMAC-SHA256).

Os valores das propriedades são armazenados no campo JSONB metadata da conversa, com o prefixo cp_. Por exemplo, uma propriedade com a chave account_type é armazenada como cp_account_type.

As propriedades são atualizadas a cada mensagem — se o widget enviar novos valores, eles substituem os existentes. Isso significa que os valores das propriedades refletem sempre os dados mais recentes do seu app.

Filtre conversas por valores de propriedades usando a barra de filtros da Caixa de entrada ou uma Vista salva. Adicione uma condição Propriedade, escolha a propriedade pelo nome — o seletor lista todas as definições dos seus agentes e também aceita uma chave bruta sem definição — e depois escolha um valor. O campo de valor sugere valores observados e quaisquer valores de enum à medida que você digita.

Pela API, os endpoints de listagem de conversas aceitam um parâmetro de consulta cp.<key>=<value> (um alias exato de attr.<key>). Não existe sintaxe de consulta em texto livre:

GET /api/v1/conversations?cp.account_type=enterprise

Os valores das propriedades são definidos pelo seu app — via integração do widget ou pela API — e são somente leitura no painel de detalhes da conversa. O painel leva ao perfil do contato, onde os atendentes podem ver e editar os atributos do contato (Contatos → contato → Atributos).