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://docs.cloud.google.com/contact-center/ccai-platform/docs/apps-api#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](https://docs.cloud.google.com/contact-center/ccai-platform/docs/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.