Create Integration

Prev Next
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