Create Integration

Post

/api/v1/integrations.create

Use this endpoint to create an incoming or outgoing integration. For details, you can refer to the Integrations user guide.

Permissions required to create incoming integrations:

manage-incoming-integrations
manage-own-incoming-integrations

Permissions required to create outgoing integrations:

manage-outgoing-integrations
manage-own-outgoing-integrations

Changelog

Version	Description
8.4.0	Added `skipTranspile` field to opt-out of Babel transpilation
1.1.0	Separate permissions in incoming and outgoing.
0.49.0	Added

Header parameters

X-Auth-Token

stringRequired

The authorization token of the user.

Example9HqLlyZOugD_0YdwAJF8V47U3QHXSq

X-User-Id

stringRequired

The user ID of the user.

ExampleaobEdbYhXfu5hkeqG

Body parameters

Incoming integration example

{
  "type": "webhook-incoming",
  "username": "test.cat",
  "channel": "#general",
  "scriptEnabled": true,
  "name": "test.cat",
  "enabled": true
}

Outgoing integration example

{
  "type": "webhook-outgoing",
  "username": "test.cat",
  "channel": "#general",
  "scriptEnabled": true,
  "name": "test.cat",
  "enabled": true,
  "event": "sendMessage",
  "urls": [
    "https://text2gif.guggy.com/guggify"
  ]
}

object

type

string Required

The type of integration to create. The possible values are:

webhook-incoming
webhook-outgoing

username

string Required

The username to post this the messages as.

channel

string Required

The channel, group, or @username. The value can also be all_public_channels, all_private_groups, or all_direct_messages. Comma separated for more than one.

Example#general

scriptEnabled

boolean Required

Whether the script should be enabled.

script

string

The script that is triggered when this integration is triggered.

name

string Required

The name of the integration.

enabled

boolean Required

Whether this integration should be enabled or not.

alias

string

The alias which should be applied to messages when this integration is processed.

avatar

string

The logo to apply to the messages that this integration sends. For example, http://res.guggy.com/logo_128.png

emoji

string

The emoji which should be displayed as the avatar for messages from this integration.

Example:ghost:

event

string Required

Required for outgoing integrations.

The type of event can be any of the following:

sendMessage
fileUploaded
roomArchived
roomCreated
roomJoined
roomLeft
userCreated

urls

Array of string Required

Required for outgoing integrations.

The urls to call whenever this integration is triggered.

string

triggerWords

string

This is an outgoing integration parameter. Specific words, separated by commas, that should trigger this integration.

token

string

This is an outgoing integration parameter. If your integration requires a special token from the server (API key), use this parameter.

skipTranspile

boolean

From 8.4.0, the optional skipTranspile field is available to opt out of Babel transpilation for the integration script. From 9.0.0, Babel will no longer be used for webhook integration script compilation. This is a breaking change for scripts that rely on sloppy-mode behavior. Admins must review the existing integrations.

This parameter lets you test each integration so you can fix any scripts that break and reliably upgrade to 9.0.0 with scriptTranspile: false set on every integration.

When skipTranspile is true, the script is stored as-is without Babel processing, matching the 9.0.0 default. Defaults to false for backward compatibility. Refer to the Script compatibility section in the Integrations user guide for more details.

Note: This parameter is deprecated and will be removed in the 9.0.0 version.

Defaultfalse

Responses

200

Incoming integration example

{
  "integration": {
    "type": "webhook-incoming",
    "username": "test.cat",
    "channel": [
      "#general"
    ],
    "scriptEnabled": true,
    "name": "test.cat",
    "enabled": true,
    "scriptEngine": "isolated-vm",
    "overrideDestinationChannelEnabled": false,
    "token": "XuHp73MccmCvJ9m3fKdQK6HKW9tjhBcbTKKHCSSLsv7qn4fk",
    "userId": "CkCPNcvsvCDfmWLqC",
    "_createdAt": "2024-01-10T14:12:07.739Z",
    "_createdBy": {
      "_id": "CkCPNcvsvCDfmWLqC",
      "username": "test.cat"
    },
    "_id": "659ea5b72dd9f928ada3e43e"
  },
  "success": true
}

Outgoing integration example

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

Expand All

object

integration

object

type

string

username

string

channel

Array of string

string

scriptEnabled

boolean

name

string

enabled

boolean

scriptEngine

string

overrideDestinationChannelEnabled

boolean

token

string

userId

string

_createdAt

string

_createdBy

object

_id

string

username

string

_id

string

success

boolean

400

Bad Request

Example 1

{
  "success": false,
  "error": "must have required property 'type'\n must have required property 'type'\n must match exactly one schema in oneOf [invalid-params]",
  "errorType": "invalid-params"
}

Example 2

{
  "success": false,
  "error": "must have required property 'username'\n must have required property 'username'\n must match exactly one schema in oneOf [invalid-params]",
  "errorType": "invalid-params"
}

object

success

boolean

error

string

errorType

string

401

Unauthorized

Authorization Error

{
  "status": "error",
  "message": "You must be logged in to do this."
}

object

status

string

message

string

Was this article helpful?