Integrations

The following endpoints provide integration support for your Rocket.Chat workspaces:

The integration object

Integration endpoints return an integration object. A trimmed example from Get Integration:

{
  "integration": {
    "_id": "659ea5e42dd9f928ada3e451",
    "type": "webhook-outgoing",
    "name": "test.cat",
    "enabled": true,
    "event": "sendMessage",
    "channel": ["#general"],
    "urls": ["https://text2gif.guggy.com/guggify"],
    "username": "test.cat",
    "scriptEnabled": true,
    "_createdAt": "2024-01-10T14:12:52.201Z"
  },
  "success": true
}

Fields you use most often:

• _id: The integration ID. Pass it as integrationId when updating, removing, or reading history.

• type: webhook-incoming (external systems post into Rocket.Chat) or webhook-outgoing (Rocket.Chat calls external URLs).

• event: The trigger for outgoing integrations, such as sendMessage.

• channel and urls: Where the integration listens and where it delivers.

Integration API

• Create and manage incoming and outgoing integrations through the integration endpoints.

• See Integrations for further details.

Notify an external system when something happens

1. Create an outgoing integration with the trigger event, channel, and target URLs.

2. Check the integration history to confirm deliveries.

3. Replay a delivery from history if the target system missed it.

Maintain existing integrations

1. List the workspace's integrations.

2. Update an integration to change its channels, script, or state, or remove it.

OAuth Apps API

• You can create and manage OAuth apps to authenticate users using the endpoints.

• See OAuth for more details.

Set up an OAuth app

1. Create the OAuth app with its redirect URI.

2. Read the app to retrieve its client ID and secret.

3. Delete the app when it is retired.

Conventions

• Integration endpoints require the integration admin permissions, such as manage-incoming-integrations and manage-outgoing-integrations; limited *-own-* variants scope access to integrations you created.

• Integration scripts run in the isolated-vm script engine.

• List endpoints support the count, offset, and sort query parameters.