Skip to content

Latest commit

 

History

History
82 lines (65 loc) · 4.2 KB

IntegrationCreation.md

File metadata and controls

82 lines (65 loc) · 4.2 KB
Raw

Creating New Integrations

Quick Reference

What is an Integration?

An integration is a piece of code used by Concierge to connect with the specified chat platform API. It tells Concierge what to do when opening/closing a connection with the platform, how to send messages, etc. The integration acts like a middleman between Concierge and the chat platform and encapsulates their API nicely.

Creating an integration for a chat platform is a relatively simple process. It can be thought of as a special kind of module that provides I/O for Concierge.

  • Each integration must be in its own module located within the modules directory.
  • No two integrations are allowed to have the same name.

Integration Formats

Integrations can take two forms:

  • A Native Module (see below).
  • A Hubot Adapter. These can be installed as a directory within the core/core_integrations directory.

Methods

Each integration must provide the methods found in Integration.md.

Handling Messages - API and Event

When messages are received by your integration they need to be passed to the callback method. This callback takes an api and an event.

Event

The event is an object of the format found in Event.md. The best way to generate this object is to use the globally defined object shim as can be seen in the following example:

let event = shim.createEvent(thread_id, sender_id, sender_name, body);

API

The API must provide all of the methods found in Api.md. As it is not possible for every platform to provide every API, it is possible to use the globally provided shim object to simplify the process of creating this API as seen below. It is recommended you only create an API once per call of the start method. At the most basic level, the sendMessage method must be provided.

Appoach 1: ES6 Class Extension

Extend only the methods needed and create a new instance of the class. A commandPrefix must be passed during instantiation of the base class.

class TestIntegration extends shim {
    sendMessage(message, thread) {
        // some implementation of sendMessage
    }
}
let api = new TestIntegration(exports.config.commandPrefix);

Approach 2: Object Definition

Create an object with only the methods needed. This will at runtime extend the IntegrationApi class as needed. The commandPrefix for your module should be provided within the object.

let apiObject = {
    commandPrefix: exports.config.commandPrefix,
    sendMessage: function(message, thread) {
        // some implementation of sendMessage
    }
};
let api = shim.createIntegration(apiObject);

Convenience Methods

_chunkMessage(message, limit, callback) => Array

Splits a message into chunks with a given message size, returns an array of messages. Includes an optional callback which is passed the array of messages.

Kind: API method

Param Type Description
message string the message to chunk.
limit Integer the size of each message chunk.
?callback Function optional callback.

Example Chunk "This is a test of a very long message. But one that is not too long\n I mean come on how much text do you expect me to make up for this. I'm simply too lazy to do more."

let message = 'This is a test of a very long message. But one that is not too long\n I mean come on how much text do you expect me to make up for this. I\'m simply too lazy to do more.',
 newMesage = _chunkMessage(message, 10);

 // [ 'This is a ', 'test of a ', 'very long ', 'message. ', 'But one ', 'that is ', 'not too ', 'long\n I ', 'mean come ', 'on how ', 'much text ', 'do you ', 'expect me ', 'to make ', 'up for ', 'this. I\'m ', 'simply ', 'too lazy ', 'to do ', 'more.' ]

Best Practises

  • In order to be configurable at runtime, an integration should not read/depend on full configuration until the point that start is called. Before this point (e.g. in load) configuration should not be required for use (it can be initialised or looked at but not depended upon).