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

   Request body

   The following is an example of a request body:

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

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, which hides it from the human agent to protect end-user privacy. If the system doesn't detect an active virtual task assistant, it routes the message to an available human 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-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. When the virtual task assistant completes its task, it transfers the chat session back to the human agent.