> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Integration
> 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 |
## OpenAPI
````json POST /api/v1/integrations.create
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Integrations"
},
"servers": [
{
"url": "https://apiexplorer.support.rocket.chat"
}
],
"paths": {
"/api/v1/integrations.create": {
"post": {
"tags": [
"Integration"
],
"summary": "Create Integration",
"description": "Use this endpoint to create an incoming or outgoing integration. For details, you can refer to the Integrations user guide.\n\nPermissions required to create incoming integrations:\n* `manage-incoming-integrations`\n* `manage-own-incoming-integrations`\n\nPermissions required to create outgoing integrations:\n* `manage-outgoing-integrations`\n* `manage-own-outgoing-integrations`\n### Changelog\n| Version | Description |\n| ---------------- | ------------|\n|8.4.0 | Added `skipTranspile` field to opt-out of Babel transpilation |\n|1.1.0 | Separate permissions in incoming and outgoing. |\n|0.49.0 | Added |",
"operationId": "post-api-v1-integrations-create",
"parameters": [
{
"$ref": "#/components/parameters/X-Auth-Token"
},
{
"$ref": "#/components/parameters/X-User-Id"
}
],
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of integration to create. The possible values are:\r\n* `webhook-incoming`\r\n* `webhook-outgoing`"
},
"username": {
"type": "string",
"description": "The username to post this the messages as."
},
"channel": {
"type": "string",
"description": "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": {
"type": "boolean",
"description": "Whether the script should be enabled."
},
"script": {
"type": "string",
"description": "The script that is triggered when this integration is triggered."
},
"name": {
"type": "string",
"description": "The name of the integration."
},
"enabled": {
"type": "boolean",
"description": "Whether this integration should be enabled or not."
},
"alias": {
"type": "string",
"description": "The alias which should be applied to messages when this integration is processed."
},
"avatar": {
"type": "string",
"description": "The logo to apply to the messages that this integration sends. For example, http://res.guggy.com/logo_128.png"
},
"emoji": {
"type": "string",
"description": "The emoji which should be displayed as the avatar for messages from this integration.",
"example": ":ghost:"
},
"event": {
"type": "string",
"description": "**Required for outgoing integrations.**\n\nThe type of event can be any of the following: \n* `sendMessage`\n* `fileUploaded`\n* `roomArchived`\n* `roomCreated`\n* `roomJoined`\n* `roomLeft`\n* `userCreated`"
},
"urls": {
"type": "array",
"description": "**Required for outgoing integrations.**\n\nThe urls to call whenever this integration is triggered.",
"items": {
"type": "string"
}
},
"triggerWords": {
"type": "string",
"description": "This is an outgoing integration parameter.\nSpecific words, separated by commas, that should trigger this integration."
},
"token": {
"type": "string",
"description": "This is an outgoing integration parameter.\nIf your integration requires a special token from the server (API key), use this parameter."
},
"skipTranspile": {
"type": "boolean",
"description": "From 8.4.0, the optional `skipTranspile` field is available to opt out of Babel transpilation for the integration script.\nFrom 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. \n\nThis 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.\n\nWhen `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.\n\nNote: This parameter is deprecated and will be removed in the 9.0.0 version.",
"default": "false"
}
},
"required": [
"type",
"username",
"channel",
"scriptEnabled",
"name",
"enabled",
"event",
"urls"
]
},
"examples": {
"Incoming integration example": {
"value": {
"type": "webhook-incoming",
"username": "test.cat",
"channel": "#general",
"scriptEnabled": "true",
"name": "test.cat",
"enabled": "true"
}
},
"Outgoing integration example": {
"value": {
"type": "webhook-outgoing",
"username": "test.cat",
"channel": "#general",
"scriptEnabled": "true",
"name": "test.cat",
"enabled": "true",
"event": "sendMessage",
"urls": [
"https://text2gif.guggy.com/guggify"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"integration": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"username": {
"type": "string"
},
"channel": {
"type": "array",
"items": {
"type": "string"
}
},
"scriptEnabled": {
"type": "boolean"
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"scriptEngine": {
"type": "string"
},
"overrideDestinationChannelEnabled": {
"type": "boolean"
},
"token": {
"type": "string"
},
"userId": {
"type": "string"
},
"_createdAt": {
"type": "string"
},
"_createdBy": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"_id": {
"type": "string"
}
}
},
"success": {
"type": "boolean"
}
}
},
"examples": {
"Incoming integration example": {
"value": {
"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": {
"value": {
"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"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/authorizationError"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
},
"errorType": {
"type": "string"
}
}
},
"examples": {
"Example 1": {
"value": {
"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": {
"value": {
"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"
}
}
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"X-Auth-Token": {
"name": "X-Auth-Token",
"in": "header",
"description": "The authorization token of the user.",
"required": "true",
"schema": {
"type": "string"
},
"example": "9HqLlyZOugD_0YdwAJF8V47U3QHXSq"
},
"X-User-Id": {
"name": "X-User-Id",
"in": "header",
"description": "The user ID of the user.",
"required": "true",
"schema": {
"type": "string"
},
"example": "aobEdbYhXfu5hkeqG"
}
},
"responses": {
"authorizationError": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"examples": {
"Authorization Error": {
"value": {
"status": "error",
"message": "You must be logged in to do this."
}
}
}
}
}
}
}
}
}
````