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

Esta página explica como incorporar assistentes virtuais de tarefas em sessões de chat usando um app personalizado criado com a plataforma da API Chat. Depois que um agente humano transfere uma sessão de chat para um assistente virtual de tarefas, o assistente virtual de tarefas pode comunicar uma mensagem ao usuário final sem que o agente 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 virtual de tarefas que participa de uma sessão de chat

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

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

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 a seguir 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 virtual de tarefas ativo, ele vai encaminhar a mensagem diretamente para o assistente virtual de tarefas. A mensagem é designada como um tipo server_message, que a oculta do agente humano para proteger a privacidade do usuário final. Se o sistema não detectar um assistente virtual de tarefas ativo, ele vai encaminhar a mensagem para um agente humano disponível.

4. Quando um assistente virtual de tarefas envia uma resposta, o endpoint do webhook recebe um evento message_received. Esse payload do webhook contém a mensagem do assistente virtual de tarefas na propriedade server_message. Portanto, 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 a seguir 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 virtual de tarefas conclui a tarefa, ele transfere a sessão de chat de volta para o agente humano.