cursor docs

cursor.md

Objetivo

• Permitir que uma caixa API, obtenha as credenciais do WhatsApp, e possibilite o envio de templates a partir desses números na tela de conversa, garantindo uma experiência de envio eficiente.

1. User Stories

• Como um administrador do sistema, quero poder configurar o WhatsApp Cloud API, Para que possa gerenciar conversas de WhatsApp e Web no mesmo canal e usar templates do WhatsApp quando necessário.

2. Requisitos Funcionais e Regras de Negócio

2.1. Configurações da caixa API

2.1.1. RF001 - Ativação do Agent Bot

• Switch de Ativação
  • Adicionar toggle switch "Habilitar integração com o Agent Bot"
  • Estado inicial deve ser desabilitado
  • Quando ativado, exibir seção de configuração WhatsApp e configuração de reincidência.
  • Deve ser adicionada uma opção de reincidência, que ao ser habilitado, deve permitir que o usuário informe a duração máxima da conversa, de 1 a 48 horas após a última janela ser encerrada.
  • Adicionar flag messaging_window_enabled automática quando Agent Bot ativo.
  • Quando desativado, ocultar seção e limpar dados.

2.1.2. RF002 - Campos de Configuração WhatsApp

• Campos aparecem apenas quando a integração com o Agent Bot está ativa
• Seção com título "Credenciais do WhatsApp"
  • Campos obrigatórios:
    • WABA ID
    • Phone Number ID
    • Access Token

2.1.3. RF003 - Gestão de Templates

• Campos aparecem apenas quando a integração com o Agent Bot está ativa.
• Botão "Buscar Templates" habilitado após preenchimento dos campos
  • Quando acionado, deve buscar na API: https://graph.facebook.com/{{api-version}}/{{waba-id}}/message_templates os templates disponíveis.
  • Mensagem de erro em caso de falha
  • Deve ser exibida uma lista de templates disponíveis para ser selecionado um template como padrão
  • Ao selecionar o template, deve ser exibida uma modal com a pré-visualização do template selecionado e a opção de confirmação de seleção daquele template.
  • O sistema mantém os templates sincronizados através do método fetch_whatsapp_templates.

2.1.4. RF004 - Botão de salvamento

• Ao acionar o botão “Atualizar”, o sistema deve salvar as configurações anteriores como padrão da caixa API.
• Feedback de sucesso/erro

2.2. Gestão de Conversas e envio de Template

2.2.1. RF001 - Identificação de origem da conversa

• Sempre que o AgentBot receber uma mensagem para iniciar uma sessão, ele deve verificar se já existe uma conversa com janela de 24h horas ativa no toolzz chat para o mesmo contato validando o número de telefone.

  • Se sim, não deve iniciar uma nova sessão e sim manter essa interação com o mesmo conversation ID.
  • Se não, ele deve verificar se a configuração de reincidência está habilitada.
    • Se sim, o sistema deve verificar a última janela de 24 horas do contato e conferir se o timestamp de expiração dessa janela está dentro do limite estabelecido.
      • Se estiver dentro do prazo, o sistema deve manter a interação na conversa existente, utilizando o mesmo conversation ID. Caso a conversa esteja com status diferente de "aberta", ela deve ser reaberta em vez de criar uma nova.
      • Se não, o sistema deve abrir uma nova sessão.
    • Se não, o sistema deve abrir uma nova sessão.

• Implementar um método para identificar se a conversa foi iniciada por um bot da API, WhatsApp ou Web.

  • Adicionar um campo nos atributos adicionais da conversa para armazenar a origem.

  • Conversas devem ser marcadas como 'api', 'WhatsApp', ou 'web' no momento da criação.

  • O sistema deve permitir verificar se uma conversa é do WhatsApp.

    • Identificação da Origem:
      • WhatsApp: Conversas vindas diretamente do WhatsApp Cloud
      • Api_whatsapp: Conversas de API com Agent Bot ativo
      • Web: Conversas do bot web

  • O sistema deve exibir um indicador visual da origem da conversa na interface, semelhante ao funcionamento da origem de uma conversa Web:

    

• Nas conversas identificadas como oriundas do WhatsApp, deve habilitar a janela de 24 horas automaticamente, quando o Agent Bot estiver ativo.

• Mesmo com a janela habilitada na caixa, a janela de 24 horas deve ser aplicada em: conversas iniciadas pelo WhatsApp.

• Outras conversas na mesma caixa não devem ter restrição de tempo.

2.2.2. RF002 - Validação da janela de 24 horas

• Quando uma mensagem chega do cliente:
  • Uma nova conversa é criada ou uma existente é reutilizada
  • O sistema registra o timestamp da conversa
  • A janela de 24h começa a contar
  • A cada nova mensagem do usuário o customer service window é renovado
• Quando um agente tenta responder:
  • O sistema verifica se está dentro da janela de 24 horas.
  • Se estiver dentro da janela, permite mensagens normais
  • Se estiver fora da janela, só permite templates e exibe a seguinte notificação.

2.2.3. RF003 - Botão de Enviar Template

• Adicionar um botão "Enviar Template" na interface de conversa da caixa API.

• O botão deve estar disponível apenas para conversas iniciadas por um bot do WhatsApp.

• Uso de Templates:

• O envio de templates deve ser permitido apenas para conversas iniciadas por um bot do WhatsApp.

• O botão "Enviar Template" deve ser desativado para outras origens de conversa na caixa API.

• Habilitar botão apenas quando houver template padrão configurado

• Ao clicar em "Enviar Template" apenas o template definido como padrão deve ser exibido:

• Quando um agente for enviar um template a partir de uma conversa na caixa API de origem WhatsApp o sistema deve verificar se já existe uma conversa com janela de 24h aberta pelo WhatsApp para o mesmo contato validando o número de telefone.

  • Se sim, o sistema deve exibir um aviso contendo a frase “Este contato já possui uma conversa aberta” e as informações da conversa (ID da conversa, time e agente atribuído):
  • O ID da conversa sempre será exibido com o hiper link da conversa aberta.
  • Os campos Time e Agente atribuído só devem ser exibidos se houver tais informações.

• Botão Atribuir a mim:

  • O botão atribuir a mim só deve ser exibido caso:

    • A conversa não tenha um agente atribuído e esteja atribuída ao meu time.

    • A conversa não possui nem time, nem agente atribuídos.

  • O Aviso de acesso a conversa só deve ser exibido caso:

    • O agente atribuído existe e é diferente do agente logado

    • O time atribuído existe e o agente logado não faz parte desse time