Distribuição em Campanhas

Quando um atendimento é criado a partir de uma campanha, o fluxo de distribuição de operadores possui características específicas que diferem do fluxo de atendimentos iniciados por contato direto.

A distribuição passa por duas camadas:

1. Pré-atribuição pela campanha (campaign_pre_assigned): quando a campanha possui uma lista de operadores, um operador elegível é selecionado via round-robin no momento do envio. Esse fluxo é independente da flag global de distribuição automática.
2. Distribuição automática (processDistributeHostPeople): quando a campanha não possui lista de operadores (ou quando todos os operadores da lista estão inelegíveis), a distribuição automática do host assume a responsabilidade de atribuir o operador.

​

Configurações Relevantes

​

Fluxo de Distribuição

​

Elegibilidade de Operadores

Antes de pré-atribuir qualquer operador via lista da campanha, um filtro de elegibilidade é aplicado (filterEligibleOperators). Operadores inativos (active: false) são removidos da lista elegível.

• Se operadores elegíveis sobram → um é selecionado via round-robin e atribuído à notificação (host_people_id na notification).
• Se nenhum operador elegível sobra → as notificações são criadas com host_people_id = null e o fluxo de distribuição automática (processDistributeHostPeople) assume a responsabilidade pela atribuição.

​

Pré-atribuição via Campanha

Ativado quando a campanha possui lista de operadores e ao menos um operador elegível existe.

Comportamento:

• Seleção por round-robin entre operadores elegíveis.
• Atribuição ocorre no momento do envio da campanha, antes da conversa ser aberta pelo contato.
• Independente da flag global distributeConversations.
• Logs no Typesense registram:
  • distribution_origin: campaign_pre_assigned
  • distribution_result: pre_assigned
  • selection_source: campaign_round_robin
  • selection_reason: "operador pré-atribuído pela campanha via round-robin"

​

Distribuição Automática

Ativado quando:

• A campanha não possui lista de operadores, ou
• Todos os operadores da lista estão inativos (nenhum elegível).

Comportamento:

• Execução fire-and-forget (sem await), sem fila RabbitMQ.
• Se não há operadores ativos no host: registra distribution_result: 'no_operators_available' + Log.warning. Não gera critical log nem retry.
• Se a flag distributeConversations for false: registra distribution_result: 'not_assigned' sem critical log.

​

Quebra de Conversa (Split)

Quando o contato já possui uma conversa pré-existente, o envio de campanha aciona o processo de split antes de distribuir o operador.

Fluxo:

1. Busca a conversa mais recente do lead pelo hostId.
   Se houver conversa mais nova que a passada, usa ela como referência.

2. Guard: hostConfig.splitConversations
   └─ false → sem split, retorna a conversa original.

3. Avaliação de elegibilidade para split:
   ├─ Conversa fechada → split imediato
   └─ Conversa aberta → split somente se AMBAS as condições:
       a) Criada há mais de splitIntervalDays dias
       b) Última mensagem há mais de splitIntervalLastMessageMin minutos

4. Conversa arquivada + NÃO deve fazer split → desarquiva e retoma.
   Conversa arquivada + DEVE fazer split → mantém arquivada, cria nova.

5. Se split necessário:
   ├─ splitTryBestConversations=true → tenta reaproveitar conversa válida.
   ├─ Fecha todas as outras conversas abertas do lead.
   ├─ Migra followups ativos da conversa antiga para a nova.
   ├─ Limpa cache de latestConversation do lead.
   └─ Nova conversa criada com host_people_id = null.

6. Após split (ou sem split):
   ├─ Com operador pré-atribuído: aplica via addContextToConversation.
   └─ Sem operador pré-atribuído: distribuição automática assume.

​

Cenários Mapeados

​

Sem lista de operadores + distribuição automática ativada

​

Todos os operadores desativados

Resultado:

• Nenhum operador distribuído.
• processDistributeHostPeople é chamado, encontra apenas operadores inativos.
• Logs: distribution_result: 'no_operators_available', selection_source: automatic_distribution.

​

Todos os operadores ativados

Resultado:

• Operadores distribuídos automaticamente via processDistributeHostPeople.
• Round-robin entre todos os operadores ativos do host.

​

Com lista de operadores + distribuição automática ativada

​

Todos os operadores da lista desativados

Resultado:

• filterEligibleOperators remove todos (todos inativos).
• Notificações criadas com host_people_id = null.
• processDistributeHostPeople assume como fallback.
• Se operadores ativos existem fora da lista → distribuídos pelo fluxo automático.
• Se nenhum operador ativo no host → distribution_result: 'no_operators_available'.

​

Todos os operadores da lista ativados

Resultado:

• Todos os operadores elegíveis pré-atribuídos via round-robin.
• 1 operador por conversa, distribuição balanceada.
• campaign_without_operator: 0
• Logs: distribution_origin: campaign_pre_assigned, distribution_result: pre_assigned, selection_source: campaign_round_robin.

​

Interação com configurações globais de distribuição

​

distributeConversations=false + campanha COM lista + operadores ativos

Resultado:

• Fluxo campaign_pre_assigned funciona normalmente — independente da flag global.
• 1 operador por conversa via round-robin.
• Logs: distribution_origin: campaign_pre_assigned, distribution_result: pre_assigned.

​

distributeConversations=false + campanha SEM lista + operadores ativos

Resultado:

• Sem pré-atribuição (campanha não possui lista).
• processDistributeHostPeople é chamado, mas barrado pela flag.
• Nenhum operador distribuído.
• Logs: distribution_result: 'not_assigned', distribute_conversations_enabled: false.

​

Cenários Ainda Não Mapeados

Os cenários abaixo foram identificados como relevantes, mas ainda não foram testados ou validados.

​

Estado misto de operadores

​

Mudança de estado durante ciclo de vida da campanha

​

Contato com conversa pré-existente

​

Opção “Eu mesmo” (Myself)

​

Flag pauseConversation

​

Campanhas concorrentes

​

Sincronização ticket-conversa

​

Comportamentos de Log

​

Campos relevantes no Typesense (tolky_features_logs)

​

Contexto de campanha nos logs

Logs gerados pelo fluxo processDistributeHostPeople (distribuição automática) não carregam campaign_id nem from_campaign: true, mesmo que o atendimento tenha sido originado por uma campanha.

Logs com contexto de campanha (from_campaign: true) só aparecem quando o fluxo campaign_pre_assigned é ativado (campanha com lista de operadores elegíveis).