Integrations WebHooks

Ministry.Chat supports WebHooks to integrate tools and services you like into the platform. WebHooks are simple event-notifications via HTTP POST. This way any application implementing a WebHook is able to POST a message to a Ministry.Chat instance and much more.

With Scripts you can point any WebHook to Ministry.Chat and process the request to print customized messages, define the username and avatar of the user of the message and change the channel where the message will be posted or you can cancel the request to prevent undesired messages.

Available integrations:

  • Incoming WebHook → Let an external service send a request to Ministry.Chat to be processed.

  • Outgoing WebHook → Let Ministry.Chat trigger and optionally send a request to an external service and process the response.

By default the WebHooks is designed to post a message only. The message is part of a JSON structure, which has the same format as described in the API documentation on how to “Post a chat message”.

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

Incoming WebHook Script

WebHooks can be handled by ES2015 / ECMAScript 6 scripts to process the request, to print a customized messages or cancel the request to prevent undesired messages.

Create a new Incoming WebHook

  • Go to your Admin Panel

  • Go to Integrations

  • Create a New Integration and select Incoming WebHook

  • Select the channel where you prefer to receive the alerts; it is possible to override in messages.

  • Set Script Enabled to true

  • Paste your script inside the Script field

  • Save the integration

  • Use the generated WebHook URL to POST messages to Ministry.Chat

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 process_incoming_request, your server calls this method every time is receives a new request. It is called with an Object as a parameter with the requestproperty.

The process_incoming_requestmethod returns an object with a contentproperty that contains valid Ministry.Chat message, or an object with an error property that returns as the response to the request in JSON format and Code 400 status.

A valid Ministry.Chat message can contain a text field that is the body of the message. When you redirect the message to a channel other than the one indicated by the Webhook token, you can specify a channel field, which accepts room id or, if prefixed with "#" or "@", channel name or user.

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

/* 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.ministry.chat/direct/rocket.cat",
        //   "author_icon": "https://open.ministry.chat/avatar/rocket.cat.jpg",
        //   "title": "Ministry.Chat",
        //   "title_link": "https://Ministry.Chat",
        //   "text": "Ministry.Chat, the best open source chat",
        //   "fields": [{
        //     "title": "Priority",
        //     "value": "High",
        //     "short": false
        //   }],
        //   "image_url": "https://ministry.chat/images/mockup.png",
        //   "thumb_url": "https://Ministry.Chat/images/mockup.png"
        // }]
       }
    };

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

Outgoing WebHook Script

Use Scripts to process all messages from a channel, and change how Ministry.Chat makes or cancels the request. You can cancel the request and return a message, or just do nothing. Also, you can make another request inside the script by using the HTTP global helper.

The response of the request also executes the script, calling another method so you can process the response, just like in Incoming WebHooks

Create a new Outgoing WebHook

  • Go to your Admin Panel

  • Go to Integrations

  • Create a New Integration and select Outgoing WebHook

  • Select the channel where you prefer to use the commands and receive the responses

  • Enter the URL you want to call in URLs, you can modify this URL inside the script

  • Set Script Enabled to true

  • Paste your script inside the Script field

  • Save your integration

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, this method is called for every message in the configured channel, or it can be filtered by Trigger Words. It is called with an Object as parameter a that contains the request property.

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

This class has a method named process_outgoing_response. It is called for every response of the request, with an Object as a parameter that contains the request property, i.e. the object you returned in the previous method, and a response property.

The process_outgoing_response method can return nothing to proceed the default processing, return false to stop it, or an object with the content property that contains a valid Ministry.Chat message.

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

/** Global Helpers
 *
 * console - A normal 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.Ministry.Chat/direct/rocket.cat",
          //   "author_icon": "https://open.ministry.chat/avatar/rocket.cat.jpg",
          //   "title": "Ministry.Chat",
          //   "title_link": "https://ministry.chat",
          //   "text": "Ministry.Chat, the best open source chat",
          //   "fields": [{
          //     "title": "Priority",
          //     "value": "High",
          //     "short": false
          //   }],
          //   "image_url": "https://ministry.chat/images/mockup.png",
          //   "thumb_url": "https://ministry.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.ministry.chat/direct/rocket.cat",
        //   "author_icon": "https://open.ministry.chat/avatar/rocket.cat.jpg",
        //   "title": "Ministry.Chat",
        //   "title_link": "https://ministry.chat",
        //   "text": "Ministry.Chat, the best open source chat",
        //   "fields": [{
        //     "title": "Priority",
        //     "value": "High",
        //     "short": false
        //   }],
        //   "image_url": "https://ministry.chat/images/mockup.png",
        //   "thumb_url": "https://ministry.chat/images/mockup.png"
        // }]
      }
    };
  }
}
PreviousGoogle Auto TranslateNextAdd Jira notifications via WebHook

Last updated