App Integration – ProteusAI Reference

🚫

Internal use only!

An app integration is an integration or connection between a third-party app and ProteusAI. Specifically, an app integration connects a third-party app to one or more agents on ProteusAI. With an app integration, a user would send a message (or perform an action) on a third-party app (like WhatsApp, Telegram, Slack, Twitter, etc.) and a ProteusAI agent would generate a response (or a reaction) and send it back to the third-party app. This way, the entire user experience happens on the third-party app, with the role of ProteusAI being inconspicuous during that experience.

A typical time to use an app integration is when you are unable or unwilling to modify the codebase of the app. Such an app would typically expose a way for you to be notified when messages are sent on the app. You can then forward the message to an agent on ProteusAI, get a response from the agent, and forward the response to the app.

Here's a typical way to integrate a third-party app with ProteusAI.

Register a webhook, say https://myserver.com/third-party-app, which will receive events via HTTP POST requests whenever a user sends a message on the third-party app.
Register a public APP plugin on ProteusAI to represent the third-party app. Every time this plugin is used to create an app integration, you will receive a token with which you can send messages to agents on ProteusAI in the name of the app.
The webhookUrl of the plugin will be an endpoint on your server, say https://myserver.com/proteus, to which ProteusAI will send responses (via HTTP POST requests) from agents.
You will then forward the agent responses to the third-party app, typically using the app's SDK or API.

Create App Integration

POST /api/app-integrations

curl https://management-api.useproteus.ai/api/app-integrations \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "Slack<>ProteusAI Integration",
            "description": "This app integration allows Slack users to communicate with ProteusAI agents",
            "orgId": "6816330b6f46b5afc080fbf7"
        }'

You can also create app integrations via the orgs API POST: /api/orgs/:orgId/app-integrations. You will not be able to supply an orgId field in the request body.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/app-integrations \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "WhatsApp<>ProteusAI Integration",
            "description": "This app integration allows WhatsApp users to communicate with ProteusAI agents"
        }'

Get App Integration

GET /api/app-integrations/:appIntegrationId

This endpoint returns an app integration.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74 \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

You have to be a member of an organization to view an app integration in that organization.

List Org App Integrations

GET /api/orgs/:orgId/app-integrations

This endpoint fetches the app integrations in an organization.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/app-integrations \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

If the current user is not a member of this organization, an error response is returned.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/app-integrations \
    -H "Authorization: Bearer user-73dd22b0c07a542d080d48a2.9e0ac60c1472a5f2949f8978e82d2582.dfbaf5a25782b0608e173d295e977259.2a52f18cf2ce3d84872ae7fc73c60822ad6fe0ad7dc21f58"

Get App Integrations by Plugin ID

GET /api/orgs/:orgId/app-integrations-by-plugin?pluginId={pluginId}

This endpoint returns all app integrations in an organization that are associated with a specific plugin.

curl "https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/app-integrations-by-plugin?pluginId=6825f0a6d6191933ffd08112" \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

You have to be a member of an organization to view app integrations in that organization.

Add App to App Integration

POST /api/app-integrations/:appIntegrationId/apps

An app integration is a connection between a third-party app and an agent. This endpoint adds a plugin instance representing the third-party app. The response of the API is the plugin instance.

Assuming we already have the below plugin representing the Slack app:

{
    "id": "6825f0a6d6191933ffd08112",
    "createdAt": "2025-05-15T13:48:22.967Z",
    "description": "This plugin helps an app integration connect with the Slack app",
    "events": [
        "APP_INTEGRATION_MESSAGE_RECEIVED"
    ],
    "image": null,
    "inputsSchema": {
        "type": "object",
        "properties": {
            "token": {
                "description": "Slack token",
                "type": "string"
            }
        },
        "required": [
            "token"
        ]
    },
    "installationUrl": null,
    "isPublic": false,
    "isTemplate": false,
    "name": "Slack App",
    "offboardingUrl": null,
    "onboardingUrl": null,
    "orgId": "6816330b6f46b5afc080fbf7",
    "privacyPolicyUrl": null,
    "scopes": [
        "APP_INTEGRATION_MESSAGE_WRITE"
    ],
    "supportEmail": null,
    "supportUrl": null,
    "tags": [
        "Slack"
    ],
    "termsOfServiceUrl": null,
    "type": "APP",
    "updatedAt": "2025-05-15T13:48:22.967Z",
    "uninstallationUrl": null,
    "webhookUrl": "https://myplugins.com/app-integration-apps/slack/webhook",
    "webhookUrlIsVerified": true,
    "websiteUrl": null
}

We can add this plugin to an app integration as shown below.

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_MESSAGE_RECEIVED" ],
            "scopes": [ "APP_INTEGRATION_MESSAGE_WRITE" ],
            "inputs": {
                "token": "xoxb-slack-token"
            }
        }'

This API call dispatches the PLUGIN_INSTALLED event to the webhook of the plugin as a HTTP POST request.

At this time, only one plugin can be added to an app integration; trying to add another plugin will uninstall the previous plugin (dispatching a PLUGIN_UNINSTALLED event) and install the new one (dispatching a PLUGIN_INSTALLED event). Trying to add the same plugin twice is a no-op.

List Apps in App Integration

GET /api/app-integrations/:appIntegrationId/apps

This endpoint lists the plugin instances acting as apps for an app integration. At the moment this list contains a maximum of an entry as you cannot add more than one plugin to an app integration.

You have to be a member of an organization to view an app integration in that organization.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/apps \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Remove App from App Integration

DELETE /api/app-integrations/:appIntegrationId/apps/:pluginInstanceId

This endpoint removes a plugin instance representing the third-party app from an app integration. The current user must be a member of the org with a role of OWNER.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/apps/6825fc77c10e22e54b35beb2 \
    -X DELETE \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

This API call dispatches the PLUGIN_UNINSTALLED event to the webhook of the plugin as a HTTP POST request.

Add Agent to App Integration

POST /api/app-integrations/:appIntegrationId/agents

An app integration is a connection between a third-party app and an agent. This endpoint adds an agent to an app integration. The response of the API is the agent added.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/agents \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "agentId": "6819a0e484df0fc342cea506"
        }'

Multiple agents can be added to an app integration, provided you are not trying to add an agent twice; calling this API again will add a new agent to the app integration. Trying to add the same agent twice is a no-op.

List Agents in App Integration

GET /api/app-integrations/:appIntegrationId/agents

This endpoint lists the agents in an app integration.

You have to be a member of an organization to view an app integration in that organization.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/agents \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Remove Agent from App Integration

DELETE /api/app-integrations/:appIntegrationId/agents/:agentId

This endpoint removes an agent from an app integration. The current user must be a member of the org with a role of OWNER.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/agents/681998f5474dbe26fe2e7f5f \
    -X DELETE \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Get App Integration Actions

GET /api/app-integrations/:appIntegrationId/actions

This endpoint returns all actions exposed by the app integration's associated plugin. Actions define the capabilities that the app integration can perform, such as sending messages, creating tasks, or other app-specific operations.

You have to be a member of an organization to view an app integration's actions.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/actions \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Get App Integration External Events

GET /api/app-integrations/:appIntegrationId/external-events

This endpoint returns all external events exposed by the app integration's associated plugin. External events are events that originate from the third-party app (such as new messages, user actions, or status changes) that can trigger workflows or actions in ProteusAI.

You have to be a member of an organization to view an app integration's external events.

curl https://management-api.useproteus.ai/api/app-integrations/6825a9f67306f72d65708b74/external-events \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Agent Event Handlers Repositories