> ## 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, see Integrations.
From Rocket.Chat 9.0.0, scripts are stored and run as written, without Babel. Existing scripts keep their transpiled version until they're edited and saved on Rocket.Chat 9.0.0 or later. See Script compatibility for the script patterns that must be updated.
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 |
| ---------------- | ------------|
|9.0.0 | Removed `skipTranspile`. |
|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"
}
],
"tags": [
{
"name": "Integration"
},
{
"name": "OAuth Apps"
}
],
"paths": {
"/api/v1/integrations.create": {
"post": {
"tags": [
"Integration"
],
"summary": "Create Integration",
"description": "Use this endpoint to create an incoming or outgoing integration. For details, see Integrations.\n\nFrom Rocket.Chat 9.0.0, scripts are stored and run as written, without Babel. Existing scripts keep their transpiled version until they're edited and saved on Rocket.Chat 9.0.0 or later. See Script compatibility for the script patterns that must be updated.\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|9.0.0 | Removed `skipTranspile`. |\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."
}
},
"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 [error-invalid-params]",
"errorType": "error-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 [error-invalid-params]",
"errorType": "error-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": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
}
}
},
"examples": {
"Authorization Error": {
"value": {
"success": false,
"error": "You must be logged in to do this."
}
}
}
}
}
}
}
}
}
````