Escolha quem participa de um experimento

Por padrão, um experimento A/B inclui todo mundo: cada nova conversa entra sozinha e recebe o controle ou a variante de forma aleatória. A etapa opcional Público do assistente de configuração muda isso. Você pode testar a variante no seu próprio celular antes de qualquer outra pessoa, rodar o experimento só para uma cidade ou uma lista de clientes, ou manter todas as conversas do mesmo cliente na mesma versão.

A maioria dos experimentos não precisa de nada disso. Pule a etapa e todo mundo participa.

Como funcionam as regras de público

A etapa Público tem três configurações. O Docana verifica cada uma nesta ordem para toda nova conversa:

• Agrupar por campo do contexto decide o que é atribuído. Desligado, cada conversa é atribuída individualmente. Ligado, todas as conversas que compartilham um valor, como o mesmo ID de cliente, caem na mesma versão e são medidas como um único grupo.
• Elegibilidade do público decide quem entra. As conversas que correspondem entram no experimento. As demais recebem a versão publicada e ficam fora dos resultados.
• Regras de direcionamento mandam as conversas que correspondem direto para o controle ou para a variante. As regras são verificadas em ordem e a primeira correspondência vence. Conversas direcionadas pulam a divisão aleatória, então nunca entram na comparação. É isso que as torna seguras para testes.

A elegibilidade e as regras de direcionamento exigem o agrupamento ligado. Uma regra de direcionamento fixa um grupo inteiro em um braço, então o Docana precisa saber o que é um grupo.

As regras ficam congeladas quando o experimento começa. Para mudá-las, pare o experimento e inicie um novo. A página de resultado do experimento mostra as regras exatas em Configurações.

Quais campos você pode usar

Uma regra compara um campo com uma lista de valores. As correspondências são exatas e diferenciam maiúsculas de minúsculas, então Recife não corresponde a recife. Os campos que uma conversa tem dependem de como as mensagens dela chegam ao Docana:

Campo	De onde vem	Disponível para
ID do usuário	O usuário do Docana que enviou a mensagem	Todas as conversas
Telefone do WhatsApp	O número de quem enviou, verificado pela Meta ou pela Twilio	Números de WhatsApp conectados diretamente ao Docana
ID de usuário do WhatsApp	O ID que o WhatsApp envia quando um contato esconde o número atrás de um nome de usuário	Números de WhatsApp conectados diretamente ao Docana
Campo do contexto	Qualquer valor no objeto context que seu servidor envia, como customer.plan ou company.city	Execuções que seu servidor inicia pela API de agentes com uma API key, ou mensagens de WhatsApp que ele encaminha pelo proxy do WhatsApp

O Docana só confia em valores que uma pessoa não consegue forjar. Um navegador, o widget de chat ou uma mensagem de WhatsApp não podem escolher o próprio contexto, então regras de contexto nunca correspondem a eles. Seu servidor pode: pela API de agentes com uma API key, ou pelo proxy do WhatsApp, que só um administrador da aplicação pode chamar.

Integrações pelo proxy do WhatsApp

Se um CRM encaminha mensagens de WhatsApp para o Docana pelo endpoint do proxy do WhatsApp (/api/plugins/whatsapp/proxy/agent/...), o context que ele envia pode corresponder a regras de contexto, seja chamando o proxy com uma API key ou com um token.

O Docana não verifica o número de quem enviou no proxy, então regras de Telefone do WhatsApp não correspondem a essas conversas. Envie o número no contexto, por exemplo como user.phone, e use-o como campo do contexto.

O agrupamento é diferente das regras. Ele lê o campo do contexto mesmo quando o valor não é confiável, porque um valor forjado só muda em qual grupo a conversa cai. Ele não consegue escolher a versão.

Tutorial: teste a variante no seu próprio celular

Antes que clientes reais vejam uma variante, mande só as suas próprias conversas para ela. Elas pulam a divisão aleatória, então seus testes nunca afetam os resultados.

Você precisa de um agente em funcionamento com uma variante candidata, e de conversas que levem seu número de telefone no contexto, por exemplo como user.phone.

1. Na aba Experimentos do agente, escolha Iniciar experimento, selecione a variante e defina uma fatia baixa do tráfego, como 1%.

2. Na etapa Público, escolha Personalizar e ligue Agrupar por campo do contexto. Informe o campo que identifica um cliente ou um atendimento, como customer e depois id.

   

   Todas as conversas com o mesmo customer.id caem na mesma versão e contam como um grupo só.

3. Ligue Regras de direcionamento. Na primeira linha, escolha Campo do contexto, informe user.phone em Caminho do campo, cole seu número em Valores exatamente como seu sistema o envia e deixe Enviar para em Variante.

   

   Uma regra: conversas em que user.phone é o seu número sempre recebem a variante.

4. Em Testar um usuário, cole em Contexto (JSON) o contexto que seu servidor envia para você, como {"user": {"phone": "+5581999990000"}}. O Docana deve responder Direcionado para Variante pela regra 1. Depois termine o assistente e inicie.

   

   Confira a regra antes de iniciar: o contexto colado vai para a variante pela regra 1.

Para testar com mais pessoas, adicione os números delas na mesma linha. Para manter alguém na versão publicada durante o teste, adicione uma segunda regra que mande o número dessa pessoa para Controle.

Se o seu número de WhatsApp está conectado diretamente ao Docana, use o campo Telefone do WhatsApp em vez de um campo do contexto. Escreva os números no formato E.164, com + e o código do país.

Tutorial: rode o experimento só para uma cidade

Teste uma mudança em uma região antes de liberar para todo mundo. Os clientes daquela cidade entram no experimento e recebem o controle ou a variante de forma aleatória. Todos os outros continuam na versão publicada.

1. Inicie um experimento e defina a fatia do tráfego que você quer dentro daquela cidade, como 50%.
2. Na etapa Público, escolha Personalizar, ligue Agrupar por campo do contexto e informe o campo que identifica um cliente.
3. Ligue Elegibilidade do público. Na linha Permitir, escolha Campo do contexto, informe company e depois city, e digite Recife em Valores.
4. Em Testar um usuário, cole um contexto com "city": "Recife" e outro com uma cidade diferente, e confira que só o primeiro entra.

Os valores precisam ser exatamente iguais. Se o seu sistema envia tanto Recife quanto RECIFE, adicione os dois.

O mesmo padrão funciona para qualquer lista que você já mantém no seu sistema. Cole uma lista de CNPJs em uma linha company.cnpj para rodar o experimento só para essas empresas. Cole IDs de clientes em uma linha customer.id para um grupo beta escolhido a dedo.

Tutorial: meça por atendimento, não por conversa

Algumas métricas só fazem sentido por cliente ou por atendimento. A taxa de transferência é uma delas: se um único atendimento passa por várias conversas, você quer o atendimento inteiro em uma versão só e contado uma vez.

1. Na etapa Público, escolha Personalizar e ligue Agrupar por campo do contexto.
2. Informe o campo que identifica um atendimento ou um cliente, como chatAttendanceId ou customer e depois id. Escolha o tipo do campo, normalmente Texto.
3. Deixe a elegibilidade e o direcionamento desligados se todo mundo deve participar, e termine o assistente.

A partir daí, a primeira conversa de um atendimento escolhe a versão e todas as conversas seguintes daquele atendimento a seguem. A página de resultado conta grupos em vez de conversas. Execuções sem valor nesse campo recebem uma resposta normal, mas ficam fora do experimento.

Combine regras

Você pode combinar tudo o que foi descrito acima. Alguns exemplos:

• Só o seu time, com o seu celular sempre na variante. A elegibilidade permite os IDs de usuário do seu time. Uma regra de direcionamento manda o seu número para Variante. Seus colegas recebem uma versão aleatória.
• Duas cidades. Uma linha de elegibilidade lista as duas cidades: Recife e Olinda. As linhas de uma lista correspondem a qualquer valor.
• Clientes premium em Recife. Mude a elegibilidade para Regras avançadas e coloque as duas condições em um mesmo grupo de condições: company.city é Recife E customer.plan é premium. Um segundo grupo de condições acrescenta um OU.

Testar um usuário faz a mesma verificação que o Docana faz quando uma conversa chega, então use antes de iniciar.

Veja quem recebeu qual versão

• A página de resultado do experimento mostra o agrupamento e as regras congelados em Configurações.
• A aba Logs do agente mostra a origem de cada execução: A · Controle, B · Candidata, Teste direcionado · Variante para conversas direcionadas, ou Fora de experimento.

API

A API REST aceita as mesmas configurações do assistente em startAgentExperiment. Adicione groupingConfiguration e audiencePolicy ao corpo da requisição:

{
  "groupingConfiguration": {
    "version": 1,
    "path": ["customer", "id"],
    "scalarType": "string",
    "missingKeyPolicy": "exclude",
    "reducer": "latest"
  },
  "audiencePolicy": {
    "version": 1,
    "eligible": [
      [
        {
          "source": "context",
          "path": ["company", "city"],
          "values": ["Recife"]
        }
      ]
    ],
    "forcedRules": [
      {
        "id": "my-phone",
        "when": [
          [
            {
              "source": "context",
              "path": ["user", "phone"],
              "values": ["+5581999990000"]
            }
          ]
        ],
        "arm": "VARIANT"
      }
    ]
  }
}

eligible é uma lista de grupos de condições: uma conversa entra quando corresponde a todas as condições de qualquer um dos grupos. forcedRules são verificadas em ordem. Condições de identidade usam "source": "identity" com "field": "userId", "whatsappPhone" ou "whatsappSenderId".

O comando docana agents experiments start ainda não aceita esses campos. Envie-os pelo acesso direto à API:

docana api POST /api/v1/agents/your_agent_id/experiments/ -d @start-body.json

Próximos passos

• Testes A/B: o resto da configuração, os limites de segurança e como ler o resultado
• Execute agentes pelo código: envie context com uma API key para que as regras de contexto possam corresponder