Create Integration

Print
Dark
Light
PDF

Create Integration

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/api/v1/integrations.create

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
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.

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?

What's Next

Get Integration