Integrations

Rocket.Chat supports webhooks to integrate tools and services into the platform to ease your everyday workflows. Webhooks are simple event notifications via HTTP POST. This way, any webhook application can post a message to a Rocket.Chat instance and much more.

With scripts, you can point any webhook to Rocket.Chat and process the requests to print customized messages, define the username and avatar of the message user, and change the channel for sending messages. You can also cancel the request to prevent undesired messages.

Available integrations

• Incoming webhook: Let an external service send a request to Rocket.Chat to be processed.

• Outgoing webhook: Let Rocket.Chat trigger and optionally send a request to an external service and process the response.

By default, a webhook is designed to post messages only. The message is part of a JSON structure, which has the same format as a Rocket.Chat message.

If you would like more power and control over various features of Rocket.Chat, aside from sending and receiving messages, take a look at the available Rocket.Chat Marketplace Apps.

In this document, we will learn about the incoming and outgoing webhook settings and sample scripts.

Incoming webhook script

ES2015 / ECMAScript 6 scripts can handle webhooks to process the request, print customized messages, or cancel the request to prevent undesired messages.

Create a new incoming webhook

To create a new incoming webhook:

1. In your workspace, go to Administration > Workspace > Integrations.

2. Click New at the top right corner.

3. Switch to the Incoming tab.

4. Select the Enabled toggle option under the Settings tab. Update the following settings:

Save the integration. Finally, use the generated Webhook URL to post messages to the selected Rocket.Chat channel or user.

Script details

The Rocket.Chat integration script should be written in ES2015 / ECMAScript 6. The script requires a global class named Script, which is instantiated only once during the first execution and kept in memory. This class contains a method called process_incoming_request, which is called by your server each time it receives a new request. The process_incoming_request method takes an object as a parameter with the request property and returns an object with a content property containing a valid Rocket.Chat message, or an object with an error property, which is returned as the response to the request in JSON format with a Code 400 status.

A valid Rocket.Chat message must contain a text field that serves as the body of the message. If you redirect the message to a channel other than the one indicated by the webhook token, you can specify a channel field that accepts room id or, if prefixed with # or @, channel name or user, respectively.

You can use the console methods to log information to help debug your script. More information about the console can be found here. To view the logs, go to Administration > Workspace > View Logs.

Following is a sample script to help you understand the structure:

/* exported Script */
/* globals console, _, s */

/** Global Helpers
 *
 * console - A normal console instance
 * _       - An underscore instance
 * s       - An underscore string instance
 */

class Script {
  /**
   * @params {object} request
   */
  process_incoming_request({ request }) {
    // request.url.hash
    // request.url.search
    // request.url.query
    // request.url.pathname
    // request.url.path
    // request.url_raw
    // request.url_params
    // request.headers
    // request.user._id
    // request.user.name
    // request.user.username
    // request.content_raw
    // request.content

    // console is a global helper to improve debug
    console.log(request.content);

    return {
      content:{
        text: request.content.text
        // "attachments": [{
        //   "color": "#FF0000",
        //   "author_name": "Rocket.Cat",
        //   "author_link": "https://open.rocket.chat/direct/rocket.cat",
        //   "author_icon": "https://open.rocket.chat/avatar/rocket.cat.jpg",
        //   "title": "Rocket.Chat",
        //   "title_link": "https://rocket.chat",
        //   "text": "Rocket.Chat, the best open source chat",
        //   "fields": [{
        //     "title": "Priority",
        //     "value": "High",
        //     "short": false
        //   }],
        //   "image_url": "https://rocket.chat/images/mockup.png",
        //   "thumb_url": "https://rocket.chat/images/mockup.png"
        // }]
       }
    };

    // return {
    //   error: {
    //     success: false,
    //     message: 'Error example'
    //   }
    // };
  }
}

To test if your integration works, use curl to make a POST request to the generated webhook URL.

curl -X POST \
  -H 'Content-Type: application/json' \
  --data '{
      "emoji": ":smirk:",
      "text": "Example message",
      "attachments": [
          {
              "title": "Rocket.Chat",
              "title_link": "https://rocket.chat",
              "text": "Rocket.Chat, the best open source chat",
              "image_url": "link-to-an-image",
              "color": "#764FA5"
          }
      ]
  }' \
  https://your-webhook-url

Outgoing webhook script

You can utilize scripts to process all messages from a channel and modify how Rocket.Chat creates or cancels the request. You can either cancel the request and return a message or take no action. Additionally, you can create another request within the script using the HTTP global helper. When a response is received from the request, it executes the script, calling another method that allows you to process the response, similar to incoming webhooks. To create a new outgoing webhook, follow these steps.

Create a new outgoing webhook

To create a new outgoing webhook:

1. In your workspace, go to Administration > Workspace > Integrations.

2. Click New in the top right corner.

3. Switch to the Outgoing tab. Update the following settings:

Save your integration once you are done.

Script details

The script should be in ES2015 / ECMAScript 6. The script expects a global class called Script. This class is instantiated once, only on the first execution, and kept in memory. The class has a method called prepare_outgoing_request, called in the configured channel for the event triggers:

• Message Sent: Called in the configured channel when the message starts with any Trigger Words.

• File Uploaded: Called when any file is uploaded in the configured channel.

• Room Archived: Called when a room is archived.

• Room Created: Called when a room is created.

• User Joined Room: Called when a user joins the channel.

The prepare_outgoing_request method returns an object with at least url and method properties. You can also change the request object and replace it. It is possible to return nothing and cancel the request or return a message.

The Script class includes another method called process_outgoing_response, which is invoked for every request response. This method accepts an object as a parameter containing two properties: request (the object returned by the previous method) and response. The process_outgoing_response method can return:

• nothing to continue with the default processing

• false to stop the process

• an object with the content property that contains a valid Rocket.Chat message.

The example script sends commands such as issues, comments, and pull requests to GitHub.

/* exported Script */
/* globals console, _, s, HTTP */

/** Global Helpers
 *
 * console - A standard console instance
 * _       - An underscore instance
 * s       - An underscore string instance
 * HTTP    - The Meteor HTTP object to do sync http calls
 */

class Script {
  /**
   * @params {object} request
   */
  prepare_outgoing_request({ request }) {
    // request.params            {object}
    // request.method            {string}
    // request.url               {string}
    // request.auth              {string}
    // request.headers           {object}
    // request.data.token        {string}
    // request.data.channel_id   {string}
    // request.data.channel_name {string}
    // request.data.timestamp    {date}
    // request.data.user_id      {string}
    // request.data.user_name    {string}
    // request.data.text         {string}
    // request.data.trigger_word {string}

    let match;

    // Change the URL and method of the request
    match = request.data.text.match(/^pr\s(ls|list)/);
    if (match) {
      return {
        url: request.url + '/pulls',
        headers: request.headers,
        method: 'GET'
      };
    }

    // Prevent the request and return a new message
    match = request.data.text.match(/^help$/);
    if (match) {
      return {
        message: {
          text: [
            '**commands**',
            '```',
              '  pr ls [open|closed|all]  List Pull Requests',
            '```'
          ].join('\n')
          // "channel": "#name-of-channel",
          // "attachments": [{
          //   "color": "#FF0000",
          //   "author_name": "Rocket.Cat",
          //   "author_link": "https://open.rocket.chat/direct/rocket.cat",
          //   "author_icon": "https://open.rocket.chat/avatar/rocket.cat.jpg",
          //   "title": "Rocket.Chat",
          //   "title_link": "https://rocket.chat",
          //   "text": "Rocket.Chat, the best open source chat",
          //   "fields": [{
          //     "title": "Priority",
          //     "value": "High",
          //     "short": false
          //   }],
          //   "image_url": "https://rocket.chat/images/mockup.png",
          //   "thumb_url": "https://rocket.chat/images/mockup.png"
          // }]
        }
      };
    }
  }

  /**
   * @params {object} request, response
   */
  process_outgoing_response({ request, response }) {
    // request              {object} - the object returned by prepare_outgoing_request

    // response.error       {object}
    // response.status_code {integer}
    // response.content     {object}
    // response.content_raw {string/object}
    // response.headers     {object}

    var text = [];
    response.content.forEach(function(pr) {
      text.push('> '+pr.state+' [#'+pr.number+']('+pr.html_url+') - '+pr.title);
    });

    // Return false will abort the response
    // return false;

    // Return empty will proceed with the default response process
    // return;

    return {
      content: {
        text: text.join('\n'),
        parseUrls: false
        // "attachments": [{
        //   "color": "#FF0000",
        //   "author_name": "Rocket.Cat",
        //   "author_link": "https://open.rocket.chat/direct/rocket.cat",
        //   "author_icon": "https://open.rocket.chat/avatar/rocket.cat.jpg",
        //   "title": "Rocket.Chat",
        //   "title_link": "https://rocket.chat",
        //   "text": "Rocket.Chat, the best open source chat",
        //   "fields": [{
        //     "title": "Priority",
        //     "value": "High",
        //     "short": false
        //   }],
        //   "image_url": "https://rocket.chat/images/mockup.png",
        //   "thumb_url": "https://rocket.chat/images/mockup.png"
        // }]
      }
    };
  }
}

Integration pattern

The next sub-topics show examples of how you can set up integrations for various platforms.