/
Módulo de Tarefas: Visão Geral e Configuração

Módulo de Tarefas: Visão Geral e Configuração

1. Visão Geral

O Módulo de Tarefas é um componente central da plataforma, projetado para facilitar a comunicação e a interação proativa entre atendentes (ou o sistema) e beneficiários/usuários. Ele permite a criação, configuração, envio e acompanhamento de tarefas específicas, garantindo que os usuários realizem ações importantes ou que os atendentes sejam notificados para interação.

2. Objetivo

Esta documentação técnica visa descrever o funcionamento, configuração e uso do Módulo de Tarefas, abordando as perspectivas de configuração, envio e visualização de tarefas através do painel do atendente e, de forma complementar, via API. O objetivo é fornecer um guia claro e objetivo para desenvolvedores e stakeholders técnicos.

3. Conceitos Chave

  • Tarefa: Uma ação ou solicitação específica configurada no sistema, destinada a um beneficiário ou a um atendente.

  • Macro: Variáveis dinâmicas utilizadas na descrição da tarefa que são preenchidas automaticamente no momento do envio, personalizando a mensagem.

  • Beneficiário: O usuário final que recebe e deve cumprir a tarefa (ou para quem a tarefa é enviada).

  • Atendente: O usuário do sistema que cria, envia e gerencia tarefas para beneficiários, ou para quem uma tarefa pode ser destinada.

  • Gestor: Um perfil de usuário com permissões elevadas para visualizar todas as tarefas da plataforma, independentemente de quem as enviou ou como foram originadas (via painel ou API).

  • Funcionalidade: Um agrupamento lógico de fluxos e configurações dentro da plataforma, associado à tarefa para seu cumprimento.

  • Template: Modelos de mensagens pré-definidos para diferentes canais (WhatsApp, Push, Email) que podem ser enviados juntamente com a tarefa.

4. Configuração Inicial do Módulo de Tarefas

4.1. Criação de uma Nova Tarefa

  1. Acesso: Navegue até Atendimento > Tarefas do Chat.

  2. Criação: Selecione a opção para "Criar Tarefa".

  3. Definição dos Dados Principais:

    • Identificação: Um identificador único e interno para a tarefa.

    • Descrição: Descrição interna da tarefa (não visível ao usuário final).

    • Descrição para o Usuário: O texto que será exibido ao beneficiário. Este campo suporta o uso de Macros.

    Exemplo de uso de Macros na Descrição para o Usuário:

    Olá, {{tarefa.contato.nome}}, o atendente {{tarefa.atendente.nome}} precisa falar com você para atualizar alguns dados.

    • {{tarefa.contato.nome}}: Macro para o nome do contato/beneficiário que receberá a tarefa.

    • {{tarefa.atendente.nome}}: Macro para o nome do atendente que está enviando a tarefa.

4.2. Associação e Configurações Adicionais

Após criar a tarefa, configure os seguintes parâmetros:

  • Tipo de Ocorrência: Deve ser do tipo Chatbot.

  • Funcionalidade:

    • Associe a uma funcionalidade existente (ex: Chatbot).

    • Recomendação Técnica: Para tarefas enviadas via aplicativo ou mobile, é altamente recomendado criar uma funcionalidade à parte, dedicada exclusivamente ao cumprimento dessas tarefas. Isso evita misturar o fluxo de tarefa com o fluxo de conversa padrão do bot com o atendente.

  • Ambiente: Selecione o ambiente de execução da tarefa (Sandbox ou Produção).

  • Fluxo: Um fluxo pré-definido no sistema que o beneficiário seguirá ao interagir com a tarefa.

    • Exemplo de Fluxo Simples:

      • Boas-vindas para a tarefa

      • Nó de Identidade ou Nó de Elegibilidade (necessário para ativar a tarefa)

      • Encaminhamento para Atendente (ex: "falar com um atendente")

  • Templates de Mensagem:

    • Template de WhatsApp: Mensagem a ser enviada via WhatsApp para o beneficiário.

    • Template de Push: Mensagem a ser enviada via notificação push no aplicativo.

    • Template de Email: Mensagem a ser enviada via e-mail.

    • Mensagem de Inspiração / Observações / Indicações de Uso:

      • Pendência: A finalidade e o formato exato desses campos precisam ser validados. Assumimos que são campos de texto livre para anotações internas.

4.3. Habilitação de Tarefas para Atendentes

Para que um atendente possa enviar tarefas:

  1. Acesse o perfil do atendente.

  2. Ative a flag Tarefas Ativadas.

  3. Selecione as tarefas específicas que o atendente está autorizado a enviar.

5. Fluxos de Uso

5.1. Visualização de Tarefas no Painel do Atendente

  1. Acesso: No painel do atendente, uma nova aba chamada Tarefas Enviadas estará disponível se o perfil do atendente tiver a opção de envio de tarefa habilitada.

  2. Exibição: Esta aba mostrará as tarefas enviadas pelo próprio atendente.

    • Por padrão, exibe tarefas pendentes.

    • É possível filtrar para ver Tarefas Finalizadas.

  3. Perfil de Gestor: Atendentes com perfil de Gestor podem visualizar todas as tarefas enviadas na plataforma, incluindo:

    • Tarefas enviadas por qualquer atendente.

    • Tarefas enviadas via API.

5.2. Envio de uma Nova Tarefa por um Atendente

  1. Início: No painel do atendente, selecione Novo Atendimento > Criar Tarefa.

  2. Pré-requisito: A tarefa a ser enviada deve ter um template de mensagem configurado para o canal desejado.

  3. Identificação do Beneficiário:

    • Não Recomendado (Identificação Manual): Evite identificar o usuário manualmente, pois o uso de chaves únicas e diferentes pode levar à criação de múltiplos contatos para o mesmo beneficiário na plataforma (e.g., Mobile Saúde).

    • Recomendado (Busca de Beneficiário): Utilize a funcionalidade de Busca de Beneficiário.

      • O atendente pesquisa o beneficiário por parâmetros específicos.

      • API de Busca de Beneficiário: Esta funcionalidade se integra a uma API externa. É necessário implementar e configurar esta API para que a busca funcione corretamente.

      • A API retorna o grupo familiar do beneficiário, permitindo que o atendente selecione o beneficiário correto para o envio da tarefa.

  4. Seleção da Tarefa: No campo Template de Tarefa, selecione uma das tarefas previamente configuradas e habilitadas para o atendente.

  5. Revisão e Personalização (Macros):

    • Ao selecionar a tarefa, o sistema exibirá os dados da mensagem com as macros preenchidas.

    • Exemplo: Se a descrição da tarefa usa {{tarefa.atendente.nome}} e {{tarefa.contato.nome}}, o sistema preencherá com os nomes do beneficiário e do atendente remetente, respectivamente.

      • Original: Olá, {{tarefa.contato.nome}}, o atendente {{tarefa.atendente.nome}} precisa falar com você para atualizar alguns dados.

      • Preenchido (Exemplo): Olá, Alex, o atendente Ranny precisa falar com você para atualizar alguns dados.

  6. Configurações de Envio:

    • Canais de Envio: Selecione os canais habilitados (WhatsApp, Aplicativo, Email). A opção de e-mail só estará disponível se um template de e-mail tiver sido configurado para a tarefa.

    • Validade da Resposta:

      • Campo opcional.

      • Recomendação: Definir um prazo curto, idealmente no máximo um dia.

      • Regra de Negócio (Suposição): As tarefas operam em um sistema sequencial (como uma fila FIFO ou LIFO para cumprimento). Uma nova tarefa para o mesmo beneficiário pode ficar pendente até que a anterior seja cumprida. Um prazo de validade curto evita o acúmulo excessivo de tarefas pendentes.

    • Forçar Push / Forçar Email:

      • Permite enviar a notificação mesmo que o beneficiário esteja em meio a outra conversa ou interação (ex: um chat ativo).

      • Impacto: O envio forçado irá "sobrepor" ou "destacar-se" da atividade atual do beneficiário.

      • Recomendação: Utilizar com extrema cautela, apenas para comunicações de alta prioridade, devido ao seu potencial de interromper a experiência do usuário.

    • Agendamento:

      • As tarefas podem ser enviadas imediatamente ou agendadas para uma data e hora específicas.

  7. Disparo da Tarefa: Após configurar, dispare a tarefa. Ela será enviada ao beneficiário e, uma vez cumprida, pode encaminhá-lo para o painel do atendente (dependendo do fluxo configurado).

6. Integração via API

6.1. Envio de Tarefas via API

  • Capacidade: É possível enviar tarefas programaticamente através de uma API dedicada.

  • Configuração: A configuração para envio de tarefas via API difere da configuração manual via painel.

  • Visualização: Tarefas enviadas via API são visíveis no painel do atendente para usuários com perfil de Gestor.

  • Pendência: Consultar a "documentação de envios de tarefa via API" específica para detalhes sobre endpoints, payloads e autenticação. Esta documentação está fora do escopo do presente documento.

6.2. API de Busca de Beneficiário

  • Propósito: Essencial para a funcionalidade de "Busca de Beneficiário" no painel do atendente.

  • Integração: Desenvolvedores devem implementar e integrar esta API para permitir que o painel do atendente pesquise e retorne dados de beneficiários.

  • Pendência: Consultar a "API de busca beneficiário" específica para detalhes sobre endpoints, parâmetros de busca, estrutura de resposta e autenticação. Esta documentação está fora do escopo do presente documento.

7. Regras de Negócio e Recomendações

  • Permissões:

    • Atendentes visualizam apenas as tarefas que eles próprios enviaram.

    • Gestores visualizam todas as tarefas (enviadas por atendentes e via API).

  • Criação de Contatos: Evitar identificação manual de usuários para não duplicar contatos na plataforma. Priorizar a busca de beneficiário via API.

  • Funcionalidades Dedicadas: Para tarefas mobile/app, criar funcionalidades separadas para evitar conflitos com fluxos de bot.

  • Validade da Tarefa: Manter a validade de resposta da tarefa curta (ex: 1 dia) para evitar acúmulo e garantir cumprimento oportuno.

  • Envio Forçado (Push/Email): Usar com moderação, apenas para situações críticas, devido ao seu potencial de interromper a experiência do usuário.

  • Fluxo de Ativação: Tarefas precisam passar por um Nó de Identidade ou Nó de Elegibilidade para serem ativadas no fluxo.

8. Observações Técnicas

  • Sistema de Tarefas: O módulo de tarefas opera com um sistema de processamento sequencial para o mesmo beneficiário, onde uma tarefa precisa ser cumprida antes que a próxima seja processada.

  • Macro Engine: O sistema utiliza um motor de macros para personalizar mensagens dinamicamente. As macros seguem o formato {{nome_da_macro}}.

9. Limitações Conhecidas

  • Duplicação de Contatos: A identificação manual de usuários pode levar à criação de contatos duplicados na plataforma.

  • Interrupção de Usuário: O envio forçado de push/email pode interromper a interação atual do beneficiário com a plataforma.

  • Dependência de APIs Externas: A funcionalidade completa do módulo (ex: busca de beneficiário, envio via API) depende da implementação e integração de APIs externas específicas.

10. Vídeo explicativo

2026-04-08_14-18-41.mp4

 

Mobile Saúde - Mosia Omnichannel