Chats – ProteusAI Reference

🚫

Internal use only!

⚠️

Although the Management API exposes endpoints for chats, it is recommended you use the equivalent endpoints on the Messaging API as the Messaging API is optimized for messaging and has a real-time connection with the ProteusAI SDK.

A chat is a conversation between an initiator and one or more participants. The initiator is the entity that created the chat, and the participants are the entities that are part of the chat (including the initiator). The initiator can be a user, agent, or app integration. The participant can be any entity that is a member of the same organization as the initiator, or a public agent.

A chat holds messages, attachments, and system messages.

Create Chat

POST /api/chats

For this exercise, a user will create a chat containing an agent and an app integration.

The agent has an event handler attached to it that listens for the events that are dispatched when a participant is added to a chat.

curl https://management-api.useproteus.ai/api/agents/6819a0e484df0fc342cea506/event-handlers \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "GPT-4o Message Processor",
            "pluginId": "681f23cc38780a323859233f",
            "events": ["AGENT_CHAT_JOINED", "AGENT_MESSAGE_RECEIVED", "CHAT_PARTICIPANT_JOINED"],
            "scopes": ["AGENT_CHAT_WRITE", "AGENT_MESSAGE_WRITE"],
            "eventDispatchMode": "SYNC"
        }'

Similarly, we add an app plugin to our app integration. This plugin has the same events as the plugin in the above snippet but this time, we omit the one scope, APP_INTEGRATION_CHAT_WRITE.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/apps \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "pluginId": "6825f0a6d6191933ffd08112",
            "events": ["APP_INTEGRATION_CHAT_JOINED", "APP_INTEGRATION_MESSAGE_RECEIVED", "CHAT_PARTICIPANT_JOINED"],
            "scopes": ["APP_INTEGRATION_MESSAGE_WRITE"]
        }'

Now, we create a new chat with the agent and app integration.

curl https://management-api.useproteus.ai/api/chats \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "participants": [
                { "id": "6819a0e484df0fc342cea506", "type": "AGENT" },
                { "id": "6825a9f67306f72d65708b74", "type": "APP_INTEGRATION" }
            ]
        }'

Notice that the created chat has 3 participants. This is because, in addition to the 2 explicitly listed in the request body, the user whose user token is used to make this request is also added to the chat as a participant.

Do not be alarmed if the response does not have the expected number of participants. The list of participants is often times added to the chat after the request has returned and after the relevant events have been dispatched.

What happens when a chat is being created?
Here's a simplified version of the flow for creating a chat.

Identify the initiator of the create chat operation.
- Get the bearer token from the request authorization header.
  - If there's none, set the initiator to a special "anonymous" user.
  - If there's a bearer token:
    - If the token is for a user, set the user as the initiator.
    - If the token is for a plugin instance:
      - If the plugin instance is attached to an agent:
        
        Ensure the plugin instance has the scope AGENT_CHAT_WRITE.
        
        Set the agent as the initiator.
      - If the plugin instance is attached to an app integration:
        
        Ensure the plugin instance has the scope APP_INTEGRATION_CHAT_WRITE.
        
        Set the app integration as the initiator.
Identify the other participants of the chat.
For each participant:
- Ensure the participant is in the same organization as the initiator, except if the participant is a public agent.
  - This check is currently not possible (and, therefore, not performed) if both the participant and the initiator are users.

⚠️

At this time, support for anonymous users has not yet been implemented.

Adding a participant to a chat dispatches a couple of events to the webhooks of the plugins attached to the agent and app integration.

First, if the entity being added to the chat is an agent, the AGENT_CHAT_JOINED event is dispatched to the webhooks of the plugins attached to the agent. Likewise, if the entity being added to the chat is an app integration, the APP_INTEGRATION_CHAT_JOINED event is dispatched to the webhook of the plugin attached to the app integration.

Then, the CHAT_PARTICIPANT_JOINED event is dispatched to the webhooks of the plugins attached to all the agents and app integrations in the chat.

A chat can also be created by a plugin instance if it has either the AGENT_CHAT_WRITE scope or the APP_INTEGRATION_CHAT_WRITE scope.

From the snippets above, we see that the plugin instance attached to the agent has the AGENT_CHAT_WRITE scope. This means a chat can be created by the plugin instance in the name of the agent.

curl https://management-api.useproteus.ai/api/chats \
    -X POST \
    -H "Authorization: Bearer inst-b023b74eba3bd58661c1af02.70d142dc5c37fba261633aad1f8aa19d.3d085c4440436c96da3dd56253b34e73.2b50192e204ade7f34528c37fc8a0f6390e8f016cdf892ed" \
    -d '{
            "participants": [
                { "id": "6819a0e484df0fc342cea506", "type": "AGENT" },
                { "id": "6825a9f67306f72d65708b74", "type": "APP_INTEGRATION" }
            ]
        }'

On the other we see that the plugin instance attached to the app integration does not have the APP_INTEGRATION_CHAT_WRITE scope. This means a chat cannot be created by the plugin instance in the name of the app integration.

curl https://management-api.useproteus.ai/api/chats \
    -X POST \
    -H "Authorization: Bearer inst-6b98ba56281fcd753c5862ee.59e9573b035f57a097b2e1aba6f9e1f2.7947a0c8982bce94ebe136bcdff61c85.8f48642ffc825e55049a7a3c5bb7abfa504f4241529feb9e" \
    -d '{
            "participants": [
                { "id": "6819a0e484df0fc342cea506", "type": "AGENT" },
                { "id": "6825a9f67306f72d65708b74", "type": "APP_INTEGRATION" }
            ]
        }'

Repositories Messages