Usar assistentes de tarefas virtuais com a plataforma de API de chat

Esta página explica como incorporar assistentes de tarefas virtuais em sessões de chat usando um app personalizado criado com a plataforma da API Chat. Depois que um atendente humano transfere uma sessão de chat para um assistente de tarefas virtuais, ele pode comunicar uma mensagem ao usuário final sem que o atendente humano a veja. Isso permite automatizar processos como a coleta de informações sensíveis ou a realização de pesquisas de dados, protegendo a privacidade do usuário final.

Fluxo de trabalho de um assistente de tarefas virtuais que participa de uma sessão de chat

Confira o fluxo de trabalho de um assistente de tarefas virtuais que participa de uma sessão de chat usando um app personalizado:

1. Um atendente humano transfere uma sessão de chat em um app de chat personalizado para um assistente de tarefas virtuais.

2. O app de chat envia a mensagem do usuário final usando uma solicitação POST para o endpoint a seguir. Autentique usando a autenticação básica.

   https://YOUR_CCAAS_HOST/apps/api/v1/chats/CHAT_ID/message
   

   Substitua:

   • YOUR_CCAAS_HOST: o host da Contact Center AI Platform (CCAI Platform)

   • CHAT_ID: o ID do chat

   Corpo da solicitação

   Confira um exemplo de corpo da solicitação:

   {
     "from_user_id": 12345,
     "message": {
       "type": "text",
       "content": {
         "text": "Example response from an end-user."
       }
     }
   }
   

3. Se o sistema detectar um assistente de tarefas virtuais ativo, ele vai encaminhar a mensagem diretamente para o assistente. A mensagem é designada como um tipo server_message, que a oculta do atendente humano para proteger a privacidade do usuário final. Se o sistema não detectar um assistente de tarefas virtuais ativo, ele vai encaminhar a mensagem para um atendente humano disponível.

4. Quando um assistente de tarefas virtuais envia uma resposta, o endpoint do webhook recebe um evento message_received. Esse payload do webhook contém a mensagem do assistente de tarefas virtuais na propriedade server_message. Assim, não é necessário fazer outra chamada de API para receber a mensagem. Para mais informações, consulte o Guia da API da plataforma de chat.

   Exemplo de payload do webhook

   Confira um exemplo de payload do webhook:

   {
     "event_type": "message_received",
     "timestamp": "2025-09-25T14:30:00Z",
     "chat_id": 37,
     "body": {
       "sender": {
         "id": 71,
         "type": "task_virtual_agent",
         "status": "connected"
       },
       "message": {
         "type": "server_message",
         "message_id": 1,
         "visibility": "task_virtual_agent"
       },
       "server_message": {
         "content": {
           "type": "text",
           "content": "Thank you. Please enter the 6-digit code sent to your device."
         }
       }
     }
   }
   

5. Quando o assistente de tarefas virtuais conclui a tarefa, ele transfere a sessão de chat de volta para o atendente humano.