Use virtual task assistants with the chat API platform

This page explains how to incorporate virtual task assistants into chat sessions using a custom app built using the chat API platform. After a human agent transfers a chat session to a virtual task assistant, the virtual task assistant can communicate a message to the end-user without the human agent seeing it. This lets you automate processes like collecting sensitive information or performing data lookups while protecting the end-user's privacy.

Workflow for a virtual task assistant participating in a chat session

Here's the workflow for a virtual task assistant participating in a chat session using a custom app:

1. A human agent transfers a chat session in a custom chat app to a virtual task assistant.

2. The chat app sends the end-user's message using a POST request to the following endpoint. Authenticate using basic authentication.

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

   Replace the following:

   • YOUR_CCAAS_HOST: your Contact Center AI Platform (CCAI Platform) host

   • CHAT_ID: the chat ID

   Example request

   The following is an example of a request body:

   {
     "from_user_id": 12345,
     "message": {
       "type": "text",
       "content": "This is my response to the Task VA."
     }
   }
   

3. If the system detects an active virtual task assistant, it routes the message directly to the virtual task assistant. The message is designated as a server_message type and carries a visibility value of task_virtual_agent. The CCAI Platform agent adapter uses this value to hide the message from the human agent. A custom agent interface must check the visibility value and apply the same filtering itself. If the system doesn't detect an active virtual task assistant, it routes the message to the session's current handler, which can be a human agent or a support virtual agent.

4. When a virtual task assistant sends a response, your webhook endpoint receives a message_received event. This webhook payload contains the message from the virtual task assistant in the server_message property, so you don't need to make another API call to get the message. For more information, see Chat platform API Guide.

   Example webhook payload

   The following is an example webhook payload:

   {
     "event_type": "message_received",
     "timestamp": "2025-09-25 14:30:00 UTC",
     "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. When the virtual task assistant completes its task, it transfers the chat session back to the human agent.