Internal use only!
Events are a way to trigger actions in response to certain conditions or changes in the system. They are typically used to notify other parts of the system (as well as plugins) about important occurrences, such as changes in data, agent actions, or system events.
AGENT_CHAT_JOINED
This event is triggered when an agent is added to a chat. This event is dispatched only to the agent that just joined the chat.
This is a good place to set up the conversation on your platform of choice. For instance, if you are making use of OpenAI Assistant API (opens in a new tab), this is a good place to create a Thread (opens in a new tab).
{
"name": "AGENT_CHAT_JOINED",
"agent": {
"id": "6819a0e484df0fc342cea506",
"appIntegrationIds": [ "6825a9f67306f72d65708b74" ],
"name": "My First Public Agent",
"canSendWelcomeMessage": true,
"createdAt": "2025-05-06T05:40:52.630Z",
"description": null,
"goal": "You are a helpful public assistant. Always answer questions in a kind and helpful manner.",
"isPublic": true,
"isTemplate": false,
"orgId": "6816330b6f46b5afc080fbf7",
"tags": [],
"updatedAt": "2025-05-15T23:28:32.913Z",
"welcomeMessage": null
},
"chat": {
"systemMessages": [],
"id": "682f4b313981b5f54e96ea4b",
"key": null,
"createdAt": "2025-05-22T16:05:05.453Z",
"latestMessageId": null,
"orgId": null,
"state": null,
"title": null,
"updatedAt": "2025-05-22T16:05:05.453Z"
},
"pluginInstance": {
"id": "682f078808a267c1f115125e",
"agentId": "6819a0e484df0fc342cea506",
"appIntegrationId": null,
"createdAt": "2025-05-22T11:16:24.075Z",
"entityId": "6819a0e484df0fc342cea506",
"entityType": "AGENT",
"eventDispatchCondition": null,
"eventDispatchMode": "SYNC",
"events": [
"AGENT_CHAT_JOINED",
"AGENT_MESSAGE_RECEIVED",
"CHAT_PARTICIPANT_JOINED"
],
"inputs": null,
"name": "GPT-4o Message Processor",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "681f23cc38780a323859233f",
"repositoryId": null,
"scopes": [ "AGENT_CHAT_WRITE", "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-22T11:16:24.075Z"
}
}AGENT_MESSAGE_RECEIVED
This event is triggered when a message is sent to an agent. This event is dispatched only to the agent to which the message is sent.
This is a good place to create/send a message on your platform of choice. For instance, if you are making use of OpenAI Assistant API (opens in a new tab), this is a good place to create a Message (opens in a new tab).
{
"name": "AGENT_MESSAGE_RECEIVED",
"agent": {
"id": "6819a0e484df0fc342cea506",
"appIntegrationIds": [ "6825a9f67306f72d65708b74" ],
"name": "My First Public Agent",
"canSendWelcomeMessage": true,
"createdAt": "2025-05-06T05:40:52.630Z",
"description": null,
"goal": "You are a helpful public assistant. Always answer questions in a kind and helpful manner.",
"isPublic": true,
"isTemplate": false,
"orgId": "6816330b6f46b5afc080fbf7",
"tags": [],
"updatedAt": "2025-05-15T23:28:32.913Z",
"welcomeMessage": null
},
"message": {
"id": "6832e67138026c1ad01407fb",
"content": "Hello, how are you?",
"contentDelta": null,
"chatId": "6832e66e38026c1ad01407f8",
"chatKey": null,
"createdAt": "2025-05-25T09:44:17.432Z",
"instructions": [],
"isStreaming": false,
"notes": [],
"processed": false,
"respondedToId": null,
"responseUrl": null,
"senderId": null,
"state": {},
"streamId": null,
"streamResponse": false,
"type": "TEXT",
"updatedAt": "2025-05-25T09:44:17.432Z"
},
"pluginInstance": {
"id": "682f078808a267c1f115125e",
"agentId": "6819a0e484df0fc342cea506",
"appIntegrationId": null,
"createdAt": "2025-05-22T11:16:24.075Z",
"entityId": "6819a0e484df0fc342cea506",
"entityType": "AGENT",
"eventDispatchCondition": null,
"eventDispatchMode": "SYNC",
"events": [
"AGENT_CHAT_JOINED",
"AGENT_MESSAGE_RECEIVED",
"CHAT_PARTICIPANT_JOINED"
],
"inputs": null,
"name": "GPT-4o Message Processor",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "681f23cc38780a323859233f",
"repositoryId": null,
"scopes": [ "AGENT_CHAT_WRITE", "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-22T11:16:24.075Z"
}
}AGENT_MESSAGE_SENT
This event is triggered when a message is sent from an agent. This event is dispatched only to the agent from which the message is sent.
APP_INTEGRATION_CHAT_JOINED
This event is triggered when an app integration is added to a chat. This event is dispatched only to the app integration that just joined the chat.
This event is typically triggered when a chat is created via a plugin for a third-party app. As a result, there's usually no need for any further actions to be performed in response to the event.
{
"name": "APP_INTEGRATION_CHAT_JOINED",
"appIntegration": {
"id": "6825a9f67306f72d65708b74",
"agentIds": [ "6819a0e484df0fc342cea506" ],
"createdAt": "2025-05-15T08:46:46.803Z",
"description": "This app integration allows Slack users to communicate with ProteusAI agents",
"name": "Slack<>ProteusAI Integration",
"orgId": "6816330b6f46b5afc080fbf7",
"updatedAt": "2025-05-16T13:54:25.582Z"
},
"chat": {
"systemMessages": [],
"id": "682f4b313981b5f54e96ea4b",
"key": null,
"createdAt": "2025-05-22T16:05:05.453Z",
"latestMessageId": null,
"orgId": null,
"state": null,
"title": null,
"updatedAt": "2025-05-22T16:05:05.453Z"
},
"pluginInstance": {
"id": "682f0d52c6fd9a503bacc429",
"agentId": null,
"appIntegrationId": "6825a9f67306f72d65708b74",
"createdAt": "2025-05-22T11:41:06.761Z",
"entityId": "6825a9f67306f72d65708b74",
"entityType": "APP_INTEGRATION",
"eventDispatchCondition": null,
"eventDispatchMode": "ASYNC",
"events": [
"APP_INTEGRATION_CHAT_JOINED",
"APP_INTEGRATION_MESSAGE_RECEIVED",
"CHAT_PARTICIPANT_JOINED"
],
"inputs": null,
"name": "Slack App <> Slack<>ProteusAI Integration (#6825a9f67306f72d65708b74)",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "6825f0a6d6191933ffd08112",
"repositoryId": null,
"scopes": [ "APP_INTEGRATION_MESSAGE_WRITE" ],
"updatedAt": "2025-05-22T11:41:06.761Z"
}
}APP_INTEGRATION_MESSAGE_RECEIVED
This event is triggered when a message is sent to an app integration. This event is dispatched only to the app integration to which the message is sent.
This is a good place to create/send a message on/to your third-party app of choice. For instance, if you are building a Slack app (opens in a new tab), this is a good place to send the message to Slack (opens in a new tab).
{
"name": "APP_INTEGRATION_MESSAGE_RECEIVED",
"appIntegration": {
"id": "6825a9f67306f72d65708b74",
"agentIds": [ "6819a0e484df0fc342cea506" ],
"createdAt": "2025-05-15T08:46:46.803Z",
"description": "This app integration allows Slack users to communicate with ProteusAI agents",
"name": "Slack<>ProteusAI Integration",
"orgId": "6816330b6f46b5afc080fbf7",
"updatedAt": "2025-05-16T13:54:25.582Z"
},
"message": {
"id": "6833925110360b306da3bf11",
"content": "Hello! I'm just a computer program, so I don't have feelings, but I'm here and ready to assist you. How can I help you today?",
"contentDelta": null,
"chatId": "6833924710360b306da3bf0b",
"chatKey": null,
"createdAt": "2025-05-25T21:57:37.247Z",
"instructions": [],
"isStreaming": false,
"notes": [],
"processed": false,
"respondedToId": "6833924a10360b306da3bf0e",
"responseUrl": "https://myplugins.com/app-integration-apps/slack/webhook",
"senderId": null,
"state": {},
"streamId": null,
"streamResponse": false,
"type": "TEXT",
"updatedAt": "2025-05-25T21:57:37.247Z"
},
"pluginInstance": {
"id": "6833918910360b306da3bf09",
"agentId": null,
"appIntegrationId": "6825a9f67306f72d65708b74",
"createdAt": "2025-05-25T21:54:17.745Z",
"entityId": "6825a9f67306f72d65708b74",
"entityType": "APP_INTEGRATION",
"eventDispatchCondition": null,
"eventDispatchMode": "ASYNC",
"events": [
"APP_INTEGRATION_CHAT_JOINED",
"APP_INTEGRATION_MESSAGE_RECEIVED",
"CHAT_PARTICIPANT_JOINED"
],
"inputs": null,
"name": "Slack App <> Slack<>ProteusAI Integration (#6825a9f67306f72d65708b74)",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "6825f0a6d6191933ffd08112",
"repositoryId": null,
"scopes": [ "APP_INTEGRATION_MESSAGE_WRITE", "APP_INTEGRATION_CHAT_WRITE" ],
"updatedAt": "2025-05-25T21:54:17.745Z"
}
}APP_INTEGRATION_MESSAGE_SENT
This event is triggered when a message is sent from an app integration. This event is dispatched only to the app integration from which the message is sent.
CHAT_MESSAGE_ADDED
This event is triggered when a message is sent to a chat. This event is dispatched to all participants in the chat.
CHAT_MESSAGE_REMOVED
This event is triggered when a message is deleted from a chat. This event is dispatched to all participants in the chat.
CHAT_PARTICIPANT_JOINED
This event is triggered when a participant is added to a chat. This event is dispatched to all participants in the chat.
The participant field of the event payload holds the id and type (AGENT, APP_INTEGRATION, or USER) of the entity that joined the chat.
Below is the event payload for an agent being notified that an agent has joined the chat.
{
"name": "CHAT_PARTICIPANT_JOINED",
"chat": {
"systemMessages": [],
"id": "682f4b313981b5f54e96ea4b",
"key": null,
"createdAt": "2025-05-22T16:05:05.453Z",
"latestMessageId": null,
"orgId": null,
"state": null,
"title": null,
"updatedAt": "2025-05-22T16:05:05.453Z"
},
"participant": { "id": "6819a0e484df0fc342cea506", "type": "AGENT" },
"agent": {
"id": "6819a0e484df0fc342cea506",
"appIntegrationIds": [ "6825a9f67306f72d65708b74" ],
"name": "My First Public Agent",
"canSendWelcomeMessage": true,
"createdAt": "2025-05-06T05:40:52.630Z",
"description": null,
"goal": "You are a helpful public assistant. Always answer questions in a kind and helpful manner.",
"isPublic": true,
"isTemplate": false,
"orgId": "6816330b6f46b5afc080fbf7",
"tags": [],
"updatedAt": "2025-05-15T23:28:32.913Z",
"welcomeMessage": null
},
"pluginInstance": {
"id": "682f078808a267c1f115125e",
"agentId": "6819a0e484df0fc342cea506",
"appIntegrationId": null,
"createdAt": "2025-05-22T11:16:24.075Z",
"entityId": "6819a0e484df0fc342cea506",
"entityType": "AGENT",
"eventDispatchCondition": null,
"eventDispatchMode": "SYNC",
"events": [
"AGENT_CHAT_JOINED",
"AGENT_MESSAGE_RECEIVED",
"CHAT_PARTICIPANT_JOINED"
],
"inputs": null,
"name": "GPT-4o Message Processor",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "681f23cc38780a323859233f",
"repositoryId": null,
"scopes": [ "AGENT_CHAT_WRITE", "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-22T11:16:24.075Z"
}
}Below is the event payload for an agent being notified that an app integration has joined the chat.
{
"name": "CHAT_PARTICIPANT_JOINED",
"chat": {
"systemMessages": [],
"id": "682f4b313981b5f54e96ea4b",
"key": null,
"createdAt": "2025-05-22T16:05:05.453Z",
"latestMessageId": null,
"orgId": null,
"state": null,
"title": null,
"updatedAt": "2025-05-22T16:05:05.453Z"
},
"participant": { "id": "6825a9f67306f72d65708b74", "type": "APP_INTEGRATION" },
"appIntegration": {
"id": "6825a9f67306f72d65708b74",
"agentIds": [ "6819a0e484df0fc342cea506" ],
"createdAt": "2025-05-15T08:46:46.803Z",
"description": "This app integration allows Slack users to communicate with ProteusAI agents",
"name": "Slack<>ProteusAI Integration",
"orgId": "6816330b6f46b5afc080fbf7",
"updatedAt": "2025-05-16T13:54:25.582Z"
},
"pluginInstance": {
"id": "682f078808a267c1f115125e",
"agentId": "6819a0e484df0fc342cea506",
"appIntegrationId": null,
"createdAt": "2025-05-22T11:16:24.075Z",
"entityId": "6819a0e484df0fc342cea506",
"entityType": "AGENT",
"eventDispatchCondition": null,
"eventDispatchMode": "SYNC",
"events": [
"AGENT_CHAT_JOINED",
"AGENT_MESSAGE_RECEIVED",
"CHAT_PARTICIPANT_JOINED"
],
"inputs": null,
"name": "GPT-4o Message Processor",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "681f23cc38780a323859233f",
"repositoryId": null,
"scopes": [ "AGENT_CHAT_WRITE", "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-22T11:16:24.075Z"
}
}Below is the event payload for an agent being notified that a user has joined the chat.
{
"name": "CHAT_PARTICIPANT_JOINED",
"chat": {
"systemMessages": [],
"id": "682f4b313981b5f54e96ea4b",
"key": null,
"createdAt": "2025-05-22T16:05:05.453Z",
"latestMessageId": null,
"orgId": null,
"state": null,
"title": null,
"updatedAt": "2025-05-22T16:05:05.453Z"
},
"participant": { "id": "6466ae1b03fab9ddd1d67c40", "type": "USER" },
"user": {
"id": "6466ae1b03fab9ddd1d67c40",
"email": "chieze.franklin@gmail.com",
"emailVerified": "2024-02-17T22:28:16.190Z",
"image": "https://lh3.googleusercontent.com/a/AGNmyxbeJuwDtOyAqJtdckhRL9IGpXT35hy0ZrUgMvClRg=s96-c",
"name": "Franklin Chieze"
},
"pluginInstance": {
"id": "682f078808a267c1f115125e",
"agentId": "6819a0e484df0fc342cea506",
"appIntegrationId": null,
"createdAt": "2025-05-22T11:16:24.075Z",
"entityId": "6819a0e484df0fc342cea506",
"entityType": "AGENT",
"eventDispatchCondition": null,
"eventDispatchMode": "SYNC",
"events": [
"AGENT_CHAT_JOINED",
"AGENT_MESSAGE_RECEIVED",
"CHAT_PARTICIPANT_JOINED"
],
"inputs": null,
"name": "GPT-4o Message Processor",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "681f23cc38780a323859233f",
"repositoryId": null,
"scopes": [ "AGENT_CHAT_WRITE", "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-22T11:16:24.075Z"
}
}CHAT_REPOSITORY_ATTACHED
This event is triggered when a repository is attached to a chat. This event is dispatched to all participants in the chat.
CHAT_STATE_UPDATED
This event is triggered when the state of a chat is updated. This event is dispatched to all participants in the chat.
PLUGIN_INSTALLED
This event is triggered when a plugin is installed. It can be used to perform actions or notify other parts of the system about the installation of a plugin (or the creation of a plugin instance).
If the plugin was installed as the event handler for an agent, this is a good place to set up the AI model that powers the agent. For instance, if you are making use of OpenAI Assistant API (opens in a new tab), this is a good place to create an Assistant (opens in a new tab).
{
"name": "PLUGIN_INSTALLED",
"pluginInstance": {
"id": "6823341466b90fb047739892",
"agentId": "6819a0e484df0fc342cea506",
"createdAt": "2025-05-13T11:59:16.426Z",
"entityId": "6819a0e484df0fc342cea506",
"entityType": "AGENT",
"eventDispatchCondition": null,
"eventDispatchMode": "SYNC",
"events": [ "AGENT_MESSAGE_RECEIVED" ],
"inputs": { "apiKey": "sk-proj-your-api-key" },
"name": "GPT-4o Message Processor",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "681f23cc38780a323859233f",
"scopes": [ "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-13T11:59:16.426Z"
},
"token": {
"id": "6823341466b90fb047739893",
"createdAt": "2025-05-13T11:59:16.777Z",
"entityId": "6823341466b90fb047739892",
"entityType": "PLUGIN_INSTANCE",
"expires": null,
"name": "Token for plugin instance: GPT-4o Message Processor (#6823341466b90fb047739892)",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginInstanceId": "6823341466b90fb047739892",
"scopes": [ "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-13T11:59:16.777Z",
"userId": null,
"token": "inst-7e616ab3e94888b1c26c1c4c.62e2001f13175e86ee7e105542f8b34c.0ae65a21c440b266c3b9a1eec9c880c2.3046eafa6e7746b3a3f0fa00289610db91d4a75bf9b65baa"
},
"agent": {
"id": "6819a0e484df0fc342cea506",
"appIntegrationIds": [],
"name": "My First Public Agent",
"canSendWelcomeMessage": true,
"createdAt": "2025-05-06T05:40:52.630Z",
"description": null,
"goal": "You are a helpful public assistant. Always answer questions in a kind and helpful manner.",
"isPublic": true,
"isTemplate": false,
"orgId": "6816330b6f46b5afc080fbf7",
"tags": [],
"updatedAt": "2025-05-13T11:59:16.426Z",
"welcomeMessage": null
}
}PLUGIN_UNINSTALLED
This event is triggered when a plugin is uninstalled. It can be used to perform actions or notify other parts of the system about the uninstallation of a plugin (or the deletion of a plugin instance).
{
"name": "PLUGIN_UNINSTALLED",
"pluginInstance": {
"id": "6823341466b90fb047739892",
"agentId": "6819a0e484df0fc342cea506",
"createdAt": "2025-05-13T11:59:16.426Z",
"entityId": "6819a0e484df0fc342cea506",
"entityType": "AGENT",
"eventDispatchCondition": null,
"eventDispatchMode": "SYNC",
"events": [ "AGENT_MESSAGE_RECEIVED" ],
"inputs": { "apiKey": "sk-proj-your-api-key" },
"name": "GPT-4o Message Processor",
"orgId": "6816330b6f46b5afc080fbf7",
"pluginId": "681f23cc38780a323859233f",
"scopes": [ "AGENT_MESSAGE_WRITE" ],
"updatedAt": "2025-05-13T11:59:16.426Z"
}
}REPOSITORY_ATTACHED
This event is triggered when a repository is attached to a chat or an agent. If the repository is attached to a chat, this event is dispatched to all participants in the chat. If the repository is attached to an agent, this event is dispatched to the agent.
REPOSITORY_FILE_ADDED
This event is triggered when a file is added to a repository. If the repository is attached to a chat, this event is dispatched to all participants in the chat. If the repository is attached to an agent, this event is dispatched to the agent.
REPOSITORY_FILE_REMOVED
This event is triggered when a file is removed from a repository. If the repository is attached to a chat, this event is dispatched to all participants in the chat. If the repository is attached to an agent, this event is dispatched to the agent.
WEBHOOK_CHALLENGE
This event is triggered when a webhook is being verified. To be successfully verified, the webhook must respond with a JSON object containing the challenge string sent by the system.
{
"name": "WEBHOOK_CHALLENGE",
"challenge": "3v4suclng21"
}WEBHOOK_MESSAGE_RECEIVED
This event is triggered when a response is generated for a message which was specified a responseUrl. The event is dispatched to the webhook provided as the value of the responseUrl.
{
"name": "WEBHOOK_MESSAGE_RECEIVED",
"message": {
"id": "683372cb10360b306da3bf06",
"content": "Hello! I'm just a program, but I'm here and ready to help you. How can I assist you today?",
"contentDelta": null,
"chatId": "683372c110360b306da3bf00",
"chatKey": null,
"createdAt": "2025-05-25T19:43:07.467Z",
"instructions": [],
"isStreaming": false,
"notes": [],
"processed": false,
"respondedToId": "683372c410360b306da3bf03",
"responseUrl": "https://myplugins.com/apps/proteusai-to-slack/webhook",
"senderId": null,
"state": {},
"streamId": null,
"streamResponse": false,
"type": "TEXT",
"updatedAt": "2025-05-25T19:43:07.467Z"
}
}