https://github.com/flint-bot/flint

Webex Bot SDK for Node.js (deprecated in favor of https://github.com/webex/webex-bot-node-framework)
https://github.com/flint-bot/flint

cisco spark

Last synced: 12 days ago
JSON representation

Webex Bot SDK for Node.js (deprecated in favor of https://github.com/webex/webex-bot-node-framework)

• Host: GitHub
• URL: https://github.com/flint-bot/flint
• Owner: flint-bot
• License: mit
• Created: 2016-02-14T23:21:30.000Z (almost 9 years ago)
• Default Branch: master
• Last Pushed: 2023-01-11T11:51:59.000Z (almost 2 years ago)
• Last Synced: 2024-10-11T20:15:22.258Z (3 months ago)
• Topics: cisco, spark
• Language: JavaScript
• Homepage:
• Size: 1.99 MB
• Stars: 86
• Watchers: 13
• Forks: 26
• Open Issues: 20
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-webex - flint - Bot SDK for Node.js (by nmarus). (Bot frameworks)

README

        
# node-flint (v4)

### Bot SDK for Node JS

## News

**03/01/2020 Please consider the Webex Node Bot Framework:**

* This framework is no longer being actively maintained by the original author.  Developers who are familiar with flint may consider trying the [webex-node-bot-framework](https://github.com/webex/webex-bot-node-framework).  While not 100% directly compatible with flint, this framework is inspired by flint and should be extremely familiar to developers who already use flint.   For more information see the [migration from flint guide](https://github.com/webex/webex-bot-node-framework/blob/master/docs/migrate-from-node-flint.md)

**10/25/19 Support for Adaptive Cards:**

* Cisco recently introduced support for [Adaptive Cards](https://developer.webex.com/docs/api/guides/cards/) in the Webex Teams.   Bots can send cards, using the new `attachment` attribute of the message object. Cards are useful as an alternative to text messages and files in order to display or collect complex bits of information. Cards can be sent by passing an object to the bot.say() method that includes a valid attachment.   To process user input to cards, apps must implement a `flint.on('attachmentaction', ..)` function.   For more details see the [adaptive-card-example](./docs/adaptive-card-example.md)

**6/21/19 Deploying behind a firewall:**

* Cisco has recently introduced support in the Webex Javascript SDK which allows applications to register to receive the message, membership, and room events via a socket instead of via wehbhoks.   This allows applications to be deployed behind firewalls and removes the requirement that webex bots and integrations must expose a public IP address to receive events.   To take advantage of this in your flint applications simply remove the `webhookUrl` field from the configuration object passed to the flint constructor.   If this field is not set, flint will register to listen for these events instead of creating webhooks.

  

**6/21/18 IMPORTANT:**

* On August 31st, 2018 all bots with the sparkbot.io domain name will be

  renamed with a webex.bot domain. Today in flint, the code compares the bot's

  email with the trigger email to filter out messages from itself. If this code

  is running on August 31st the bot will start responding to its own messages.

  Please update to Flint v4.7.x as soon as possible to avoid interruption. 

**3/19/18 IMPORTANT:**

* Note that Flint v4 is still using the node-sparky library version 3.x.

  However the repo for node-sparky is now on version 4 which has some major

  differences. This misalignment between Flint and Sparky version

  will be fixed with the release of Flint v5. In the

  short term if you are accessing the spark object directly from Flint via

  `flint.spark` be sure to use the documentation for [node-sparky 3.x](https://github.com/flint-bot/sparky/tree/v3).   

**See [CHANGELOG.md](/CHANGELOG.md) for details on changes to versions of Flint.**

## Contents

- [Installation](#installation)

    - [Via Git](#via-git)

    - [Via NPM](#via-npm)

    - [Example Template Using Express](#example-template-using-express)

- [Overview](#overview)

- [Authentication](#authentication)

- [Storage](#storage)

- [Bot Accounts](#bot-accounts)

## Installation

#### Via Git

```bash

mkdir myproj

cd myproj

git clone https://github.com/nmarus/flint

npm install ./flint

```

#### Via NPM

```bash

mkdir myproj

cd myproj

npm install node-flint

```

#### Example Template Using Express

```js

var Flint = require('node-flint');

var webhook = require('node-flint/webhook');

var express = require('express');

var bodyParser = require('body-parser');

var app = express();

app.use(bodyParser.json());

// flint options

var config = {

  webhookUrl: 'http://myserver.com/flint',

  token: 'Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u',

  port: 80

};

// init flint

var flint = new Flint(config);

flint.start();

// say hello

flint.hears('/hello', function(bot, trigger) {

  bot.say('Hello %s!', trigger.personDisplayName);

});

// define express path for incoming webhooks

// This is not necessary if webhookUrl is not set in the config

app.post('/flint', webhook(flint));

// start express server

// This is not necessary if webhookUrl is not set in the config

// unless the bot uses express for other reasons

var server = app.listen(config.port, function () {

  flint.debug('Flint listening on port %s', config.port);

});

// gracefully shutdown (ctrl-c)

process.on('SIGINT', function() {

  flint.debug('stoppping...');

  server.close();   // remove if not using webhooks and express

  flint.stop().then(function() {

    process.exit();

  });

});

```

[**Restify Example**](https://github.com/nmarus/flint/blob/master/docs/example2.md)

## Overview

Most of Flint's functionality is based around the flint.hears function. This

defines the phrase or pattern the bot is listening for and what actions to take

when that phrase or pattern is matched. The flint.hears function gets a callback

than includes two objects. The bot object, and the trigger object.

Flint generates a bot object instance of the Bot class for each room the Spark

account Flint is running under. The bot object instance tracks the specifics

about the room it is running in and is passed to the  "hears" command callback

when a phrase is heard.

Flint also generates a trigger object based on the person and room that the

flint.hears function was triggered.

A simple example of a flint.hears() function setup:

```js

flint.hears(phrase, function(bot, trigger) {

  bot.

    .then(function(returnedValue) {

      // do something with returned value

    })

    .catch(function(err) {

      // handle errors

    });

});

```

* `phrase` : This can be either a string or a regex pattern.

If a string, the string is matched against the first word in the room message.

message.

If a regex pattern is used, it is matched against the entire message text.

* `bot` : The bot object that is used to execute commands when the `phrase` is

triggered.

* `bot.` : The Bot method to execute.

* `then` : Node JS Promise keyword that invokes additional logic once the

previous command is executed.

* `catch` : handle errors that happen at either the original command or in any

of the chained 'then' functions.

* `trigger` : The object that describes the details around what triggered the

`phrase`.

* `commands` : The commands that are ran when the `phrase` is heard.

## Authentication

The token used to authenticate Flint to the Spark (now Webex) API is passed as part of the

options used when instantiating the Flint class. To change or update the

token, use the Flint#setSparkToken() method.

**Example:**

```js

var newToken = 'Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u';

flint.setSparkToken(newToken)

.then(function(token) {

  console.log('token updated to: ' + token);

});

```

## Storage

The storage system used in flint is a simple key/value store and resolves around

these 3 methods:

* `bot.store(key, value)` - Store a value to a bot instance where 'key' is a

  string and 'value' is a boolean, number, string, array, or object. *This does

  not not support functions or any non serializable data.* Returns the a promise

  with the value.

* `bot.recall(key)` - Recall a value by 'key' from a bot instance. Returns a

  resolved promise with the value or a rejected promise if not found.

* `bot.forget([key])` - Forget (remove) value(s) from a bot instance where 'key'

  is an optional property that when defined, removes the specific key, and when

  undefined, removes all keys. Returns a resolved promise if deleted or not found.

When a bot despawns (removed from room), the key/value store for that bot

instance will automatically be removed from the store. Flint currently has an

in-memory store and a Redis based store. By default, the in-memory store is

used. Other backend stores are possible by replicating any one of the built-in

storage modules and passing it to the `flint.storeageDriver()` method. *See

docs for store, recall, forget for more details.*

**Example:**

```js

var redisDriver = require('node-flint/storage/redis');

flint.storageDriver(redisDriver('redis://localhost'));

```

## Bot Accounts

**When using "Bot Accounts" the major differences are:**

* Webhooks for message:created only trigger when the Bot is mentioned by name

* Unable to read messages in rooms using the Spark (now Webex) API

**Differences with trigger.args using Flint with a "Bot Account":**

The trigger.args array is a shortcut in processing the trigger.text string. It

consists of an array of the words that are in the trigger.message string split

by one or more spaces. Punctation is included if there is no space between the

symbol and the word. With bot accounts, this behaves a bit differently.

* If defining a `flint.hears()` using a string (not regex), `trigger.args` is a

  filtered array of words from the message that begins *after* the first match of

  bot mention.

* If defining a flint.hears() using regex, the trigger.args array is the entire

  message.

# Flint Reference

## Classes



Flint



Bot





## Objects





Message : object





Message Object





File : object





File Object





Trigger : object





Trigger Object





## Events



"log"



Flint log event.



"stop"



Flint stop event.



"start"



Flint start event.



"initialized"



Flint initialized event.



"roomLocked"



Room Locked event.



"roomUnocked"



Room Unocked event.



"personEnters"



Person Enter Room event.



"botAddedAsModerator"



Bot Added as Room Moderator.



"botRemovedAsModerator"



Bot Removed as Room Moderator.



"personAddedAsModerator"



Person Added as Moderator.



"personRemovedAsModerator"



Person Removed as Moderator.



"personExits"



Person Exits Room.



"mentioned"



Bot Mentioned.



"message"



Message Recieved.



"files"



File Recieved.



"spawn"



Bot Spawned.



"despawn"



Bot Despawned.







## Flint

**Kind**: global class  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Flint UUID |

| active | boolean | Flint active state |

| intialized | boolean | Flint fully initialized |

| isBotAccount | boolean | Is Flint attached to Spark using a bot account? |

| isUserAccount | boolean | Is Flint attached to Spark using a user account? |

| person | object | Flint person object |

| email | string | Flint email |

| spark | object | The Spark instance used by flint |

* [Flint](#Flint)

    * [new Flint(options)](#new_Flint_new)

    * [.options](#Flint+options) : object

    * [.setSparkToken(token)](#Flint+setSparkToken) ⇒ Promise.<String>

    * [.stop()](#Flint+stop) ⇒ Promise.<Boolean>

    * [.start()](#Flint+start) ⇒ Promise.<Boolean>

    * [.restart()](#Flint+restart) ⇒ Promise.<Boolean>

    * [.getMessage(messageId)](#Flint+getMessage) ⇒ [Promise.<Message>](#Message)

    * [.getFiles(messageId)](#Flint+getFiles) ⇒ Promise.<Array>

    * [.hears(phrase, action, [helpText], [preference])](#Flint+hears) ⇒ String

    * [.clearHears(id)](#Flint+clearHears) ⇒ null

    * [.showHelp([header], [footer])](#Flint+showHelp) ⇒ String

    * [.setAuthorizer(Action)](#Flint+setAuthorizer) ⇒ Boolean

    * [.clearAuthorizer()](#Flint+clearAuthorizer) ⇒ null

    * [.storageDriver(Driver)](#Flint+storageDriver) ⇒ null

    * [.use(path)](#Flint+use) ⇒ Boolean



### new Flint(options)

Creates an instance of Flint.

| Param | Type | Description |

| --- | --- | --- |

| options | Object | Configuration object containing Flint settings. |

**Example**  

```js

var options = {

  webhookUrl: 'http://myserver.com/flint',

  token: 'Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u'

};

var flint = new Flint(options);

```



### flint.options : object

Options Object

**Kind**: instance namespace of [Flint](#Flint)  

**Properties**

| Name | Type | Default | Description |

| --- | --- | --- | --- |

| token | string |  | Spark Token. |

| webhookUrl | string |  | URL that is used for Spark API to send callbacks.  If this field is omitted, flint will use the webex javascript sdk to register to listen for the events via websocket instead.|

| [webhookSecret] | string |  | If specified, inbound webhooks are authorized before being processed. This configuration is ignored if `webhookUrl` is not set.|

| [messageFormat] | string | "text" | Default Spark message format to use with bot.say(). |

| [maxPageItems] | number | 50 | Max results that the paginator uses. |

| [maxConcurrent] | number | 3 | Max concurrent sessions to the Spark API |

| [minTime] | number | 600 | Min time between consecutive request starts. |

| [requeueMinTime] | number | minTime*10 | Min time between consecutive request starts of requests that have been re-queued. |

| [requeueMaxRetry] | number | 3 | Msx number of atteempts to make for failed request. |

| [requeueCodes] | array | [429,500,503] | Array of http result codes that should be retried. |

| [requestTimeout] | number | 20000 | Timeout for an individual request recieving a response. |

| [queueSize] | number | 10000 | Size of the buffer that holds outbound requests. |

| [requeueSize] | number | 10000 | Size of the buffer that holds outbound re-queue requests. |

| [id] | string | "random" | The id this instance of flint uses. |

| [webhookRequestJSONLocation] | string | "body" | The property under the Request to find the JSON contents. This configuration is ignored if `webhookUrl` is not set. |

| [removeWebhooksOnStart] | Boolean | true | If you wish to have the bot remove all account webhooks when starting. This configuration is ignored if `webhookUrl` is not set. |



### flint.setSparkToken(token) ⇒ Promise.<String>

Tests, and then sets a new Spark Token.

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Description |

| --- | --- | --- |

| token | String | New Spark Token for Flint to use. |

**Example**  

```js

flint.setSparkToken('Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u')

  .then(function(token) {

     console.log('token updated to: ' + token);

  });

```



### flint.stop() ⇒ Promise.<Boolean>

Stop Flint.

**Kind**: instance method of [Flint](#Flint)  

**Example**  

```js

flint.stop();

```



### flint.start() ⇒ Promise.<Boolean>

Start Flint.

**Kind**: instance method of [Flint](#Flint)  

**Example**  

```js

flint.start();

```



### flint.restart() ⇒ Promise.<Boolean>

Restart Flint.

**Kind**: instance method of [Flint](#Flint)  

**Example**  

```js

flint.restart();

```



### flint.getMessage(messageId) ⇒ [Promise.<Message>](#Message)

Get Message Object by ID

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Description |

| --- | --- | --- |

| messageId | String | Message ID from Spark API. |



### flint.getFiles(messageId) ⇒ Promise.<Array>

Get Files from Message Object by ID

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Description |

| --- | --- | --- |

| messageId | String | Message ID from Spark API. |



### flint.hears(phrase, action, [helpText], [preference]) ⇒ String

Add action to be performed when bot hears a phrase.

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| phrase | Regex \| String |  | The phrase as either a regex or string. If regex, matches on entire message.If string, matches on first word. |

| action | function |  | The function to execute when phrase is matched. Function is executed with 2 variables. Trigger and Bot. The Trigger Object contains information about the person who entered a message that matched the phrase. The Bot Object is an instance of the Bot Class as it relates to the room the message was heard. |

| [helpText] | String |  | The string of text that describes how this command operates. |

| [preference] | Number | 0 | Specifies preference of phrase action when overlapping phrases are matched. On multiple matches with same preference, all matched actions are excuted. On multiple matches with difference preference values, only the lower preferenced matched action(s) are executed. |

**Example**  

```js

// using a string to match first word and defines help text

flint.hears('/say', function(bot, trigger, id) {

  bot.say(trigger.args.slice(1, trigger.arges.length - 1));

}, '/say  - Responds with a greeting');

```

**Example**  

```js

// using regex to match across entire message

flint.hears(/(^| )beer( |.|$)/i, function(bot, trigger, id) {

  bot.say('Enjoy a beer, %s! 🍻', trigger.personDisplayName);

});

```



### flint.clearHears(id) ⇒ null

Remove a "flint.hears()" entry.

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Description |

| --- | --- | --- |

| id | String | The "hears" ID. |

**Example**  

```js

// using a string to match first word and defines help text

var hearsHello = flint.hears('/flint', function(bot, trigger, id) {

  bot.say('Hello %s!', trigger.personDisplayName);

});

flint.clearHears(hearsHello);

```



### flint.showHelp([header], [footer]) ⇒ String

Display help for registered Flint Commands.

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [header] | String | Usage: | String to use in header before displaying help message. |

| [footer] | String | Powered by Flint - https://github.com/nmarus/flint | String to use in footer before displaying help message. |

**Example**  

```js

flint.hears('/help', function(bot, trigger, id) {

  bot.say(flint.showHelp());

});

```



### flint.setAuthorizer(Action) ⇒ Boolean

Attaches authorizer function.

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Description |

| --- | --- | --- |

| Action | function | The function to execute when phrase is matched to authenticate a user.  The function is passed the bot, trigger, and id and expects a return value of true or false. |

**Example**  

```js

function myAuthorizer(bot, trigger, id) {

  if(trigger.personEmail === '[email protected]') {

    return true;

  }

  else if(trigger.personDomain === 'test.com') {

    return true;

  }

  else {

    return false;

  }

}

flint.setAuthorizer(myAuthorizer);

```



### flint.clearAuthorizer() ⇒ null

Removes authorizer function.

**Kind**: instance method of [Flint](#Flint)  

**Example**  

```js

flint.clearAuthorizer();

```



### flint.storageDriver(Driver) ⇒ null

Defines storage backend.

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Description |

| --- | --- | --- |

| Driver | function | The storage driver. |

**Example**  

```js

// define memory store (default if not specified)

flint.storageDriver(new MemStore());

```



### flint.use(path) ⇒ Boolean

Load a Plugin from a external file.

**Kind**: instance method of [Flint](#Flint)  

| Param | Type | Description |

| --- | --- | --- |

| path | String | Load a plugin at given path. |

**Example**  

```js

flint.use('events.js');

```

**Example**  

```js

// events.js

module.exports = function(flint) {

  flint.on('spawn', function(bot) {

    console.log('new bot spawned in room: %s', bot.myroom.title);

  });

  flint.on('despawn', function(bot) {

    console.log('bot despawned in room: %s', bot.myroom.title);

  });

  flint.on('messageCreated', function(message, bot) {

    console.log('"%s" said "%s" in room "%s"', message.personEmail, message.text, bot.myroom.title);

  });

};

```



## Bot

**Kind**: global class  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Bot UUID |

| active | boolean | Bot active state |

| person | object | Bot Person Object |

| email | string | Bot email |

| team | object | Bot team object |

| room | object | Bot room object |

| membership | object | Bot membership object |

| isLocked | boolean | If bot is locked |

| isModerator | boolean | If bot is a moderator |

| isGroup | boolean | If bot is in Group Room |

| isDirect | boolean | If bot is in 1:1/Direct Room |

| isDirectTo | string | Recipient Email if bot is in 1:1/Direct Room |

| isTeam | boolean | If bot is in Team Room |

| lastActivity | date | Last bot activity |

* [Bot](#Bot)

    * [new Bot(flint)](#new_Bot_new)

    * [.exit()](#Bot+exit) ⇒ Promise.<Boolean>

    * [.add(email(s), [moderator])](#Bot+add) ⇒ Promise.<Array>

    * [.remove(email(s))](#Bot+remove) ⇒ Promise.<Array>

    * [.getModerators()](#Bot+getModerators) ⇒ Promise.<Array>

    * [.newRoom(name, emails)](#Bot+newRoom) ⇒ [Promise.<Bot>](#Bot)

    * [.newTeamRoom(name, emails)](#Bot+newTeamRoom) ⇒ [Promise.<Bot>](#Bot)

    * [.moderateRoom()](#Bot+moderateRoom) ⇒ [Promise.<Bot>](#Bot)

    * [.unmoderateRoom()](#Bot+unmoderateRoom) ⇒ [Promise.<Bot>](#Bot)

    * [.moderatorSet(email(s))](#Bot+moderatorSet) ⇒ [Promise.<Bot>](#Bot)

    * [.moderatorClear(email(s))](#Bot+moderatorClear) ⇒ [Promise.<Bot>](#Bot)

    * [.implode()](#Bot+implode) ⇒ Promise.<Boolean>

    * [.say([format], message)](#Bot+say) ⇒ [Promise.<Message>](#Message)

    * [.dm(email, [format], message)](#Bot+dm) ⇒ [Promise.<Message>](#Message)

    * [.uploadStream(filename, stream)](#Bot+uploadStream) ⇒ [Promise.<Message>](#Message)

    * [.upload(filepath)](#Bot+upload) ⇒ [Promise.<Message>](#Message)

    * [.censor(messageId)](#Bot+censor) ⇒ [Promise.<Message>](#Message)

    * [.roomRename(title)](#Bot+roomRename) ⇒ Promise.<Room>

    * [.getMessages(count)](#Bot+getMessages) ⇒ Promise.<Array>

    * [.store(key, value)](#Bot+store) ⇒ Promise.<String> \| Promise.<Number> \| Promise.<Boolean> \| Promise.<Array> \| Promise.<Object>

    * [.recall([key])](#Bot+recall) ⇒ Promise.<String> \| Promise.<Number> \| Promise.<Boolean> \| Promise.<Array> \| Promise.<Object>

    * [.forget([key])](#Bot+forget) ⇒ Promise.<String> \| Promise.<Number> \| Promise.<Boolean> \| Promise.<Array> \| Promise.<Object>



### new Bot(flint)

Creates a Bot instance that is then attached to a Spark Room.

| Param | Type | Description |

| --- | --- | --- |

| flint | Object | The flint object this Bot spawns under. |



### bot.exit() ⇒ Promise.<Boolean>

Instructs Bot to exit from room.

**Kind**: instance method of [Bot](#Bot)  

**Example**  

```js

bot.exit();

```



### bot.add(email(s), [moderator]) ⇒ Promise.<Array>

Instructs Bot to add person(s) to room.

**Kind**: instance method of [Bot](#Bot)  

**Returns**: Promise.<Array> - Array of emails added  

| Param | Type | Description |

| --- | --- | --- |

| email(s) | String \| Array | Email Address (or Array of Email Addresses) of Person(s) to add to room. |

| [moderator] | Boolean | Add as moderator. |

**Example**  

```js

// add one person to room by email

bot.add('[email protected]');

```

**Example**  

```js

// add one person as moderator to room by email

bot.add('[email protected]', true)

  .catch(function(err) {

    // log error if unsuccessful

    console.log(err.message);

  });

```

**Example**  

```js

// add 3 people to room by email

bot.add(['[email protected]', '[email protected]', '[email protected]']);

```



### bot.remove(email(s)) ⇒ Promise.<Array>

Instructs Bot to remove person from room.

**Kind**: instance method of [Bot](#Bot)  

**Returns**: Promise.<Array> - Array of emails removed  

| Param | Type | Description |

| --- | --- | --- |

| email(s) | String \| Array | Email Address (or Array of Email Addresses) of Person(s) to remove from room. |

**Example**  

```js

// remove one person to room by email

bot.remove('[email protected]');

```

**Example**  

```js

// remove 3 people from room by email

bot.remove(['[email protected]', '[email protected]', '[email protected]']);

```



### bot.getModerators() ⇒ Promise.<Array>

Get room moderators.

**Kind**: instance method of [Bot](#Bot)  

**Example**  

```js

bot.getModerators()

  .then(function(moderators) {

    console.log(moderators);

  });

```



### bot.newRoom(name, emails) ⇒ [Promise.<Bot>](#Bot)

Create new room with people by email

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| name | String | Name of room. |

| emails | Array | Emails of people to add to room. |



### bot.newTeamRoom(name, emails) ⇒ [Promise.<Bot>](#Bot)

Create new Team Room

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| name | String | Name of room. |

| emails | Array | Emails of people to add to room. |



### bot.moderateRoom() ⇒ [Promise.<Bot>](#Bot)

Enable Room Moderation.Enable.

**Kind**: instance method of [Bot](#Bot)  

**Example**  

```js

bot.moderateRoom()

  .then(function(err) {

    console.log(err.message)

  });

```



### bot.unmoderateRoom() ⇒ [Promise.<Bot>](#Bot)

Disable Room Moderation.

**Kind**: instance method of [Bot](#Bot)  

**Example**  

```js

bot.unmoderateRoom()

  .then(function(err) {

    console.log(err.message)

  });

```



### bot.moderatorSet(email(s)) ⇒ [Promise.<Bot>](#Bot)

Assign Moderator in Room

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| email(s) | String \| Array | Email Address (or Array of Email Addresses) of Person(s) to assign as moderator. |

**Example**  

```js

bot.moderatorSet('[email protected]')

  .then(function(err) {

    console.log(err.message)

  });

```



### bot.moderatorClear(email(s)) ⇒ [Promise.<Bot>](#Bot)

Unassign Moderator in Room

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| email(s) | String \| Array | Email Address (or Array of Email Addresses) of Person(s) to unassign as moderator. |

**Example**  

```js

bot.moderatorClear('[email protected]')

  .then(function(err) {

    console.log(err.message)

  });

```



### bot.implode() ⇒ Promise.<Boolean>

Remove a room and all memberships.

**Kind**: instance method of [Bot](#Bot)  

**Example**  

```js

flint.hears('/implode', function(bot, trigger) {

  bot.implode();

});

```



### bot.say([format], message) ⇒ [Promise.<Message>](#Message)

Send text with optional file to room.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [format] | String | text | Set message format. Valid options are 'text' or 'markdown'. |

| message | String \| Object |  | Message to send to room. This can be a simple string, or a object for advanced use. |

**Example**  

```js

// Simple example

flint.hears('/hello', function(bot, trigger) {

  bot.say('hello');

});

```

**Example**  

```js

// Simple example to send message and file

flint.hears('/file', function(bot, trigger) {

  bot.say({text: 'Here is your file!', file: 'http://myurl/file.doc'});

});

```

**Example**  

```js

// Markdown Method 1 - Define markdown as default

flint.messageFormat = 'markdown';

flint.hears('/hello', function(bot, trigger) {

  bot.say('**hello**, How are you today?');

});

```

**Example**  

```js

// Markdown Method 2 - Define message format as part of argument string

flint.hears('/hello', function(bot, trigger) {

  bot.say('markdown', '**hello**, How are you today?');

});

```

**Example**  

```js

// Mardown Method 3 - Use an object (use this method of bot.say() when needing to send a file in the same message as markdown text.

flint.hears('/hello', function(bot, trigger) {

  bot.say({markdown: '*Hello <@personEmail:' + trigger.personEmail + '|' + trigger.personDisplayName + '>*'});

});

```



### bot.dm(email, [format], message) ⇒ [Promise.<Message>](#Message)

Send text with optional file in a direct message. This sends a message to a 1:1 room with the user (creates 1:1, if one does not already exist)

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Default | Description |

| --- | --- | --- | --- |

| email | String |  | Email of person to send Direct Message. |

| [format] | String | text | Set message format. Valid options are 'text' or 'markdown'. |

| message | String \| Object |  | Message to send to room. This can be a simple string, or a object for advanced use. |

**Example**  

```js

// Simple example

flint.hears('/dm', function(bot, trigger) {

  bot.dm('[email protected]', 'hello');

});

```

**Example**  

```js

// Simple example to send message and file

flint.hears('/dm', function(bot, trigger) {

  bot.dm('[email protected]', {text: 'Here is your file!', file: 'http://myurl/file.doc'});

});

```

**Example**  

```js

// Markdown Method 1 - Define markdown as default

flint.messageFormat = 'markdown';

flint.hears('/dm', function(bot, trigger) {

  bot.dm('[email protected]', '**hello**, How are you today?');

});

```

**Example**  

```js

// Markdown Method 2 - Define message format as part of argument string

flint.hears('/dm', function(bot, trigger) {

  bot.dm('[email protected]', 'markdown', '**hello**, How are you today?');

});

```

**Example**  

```js

// Mardown Method 3 - Use an object (use this method of bot.dm() when needing to send a file in the same message as markdown text.

flint.hears('/dm', function(bot, trigger) {

  bot.dm('[email protected]', {markdown: '*Hello <@personEmail:' + trigger.personEmail + '|' + trigger.personDisplayName + '>*'});

});

```



### bot.uploadStream(filename, stream) ⇒ [Promise.<Message>](#Message)

Upload a file to a room using a Readable Stream

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| filename | String | File name used when uploading to room |

| stream | Stream.Readable | Stream Readable |

**Example**  

```js

flint.hears('/file', function(bot, trigger) {

  // define filename used when uploading to room

  var filename = 'test.png';

  // create readable stream

  var stream = fs.createReadStream('/my/file/test.png');

  bot.uploadStream(filename, stream);

});

```



### bot.upload(filepath) ⇒ [Promise.<Message>](#Message)

Upload a file to room.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| filepath | String | File Path to upload |

**Example**  

```js

flint.hears('/file', function(bot, trigger) {

  bot.upload('test.png');

});

```



### bot.censor(messageId) ⇒ [Promise.<Message>](#Message)

Remove Message By Id.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type |

| --- | --- |

| messageId | String | 



### bot.roomRename(title) ⇒ Promise.<Room>

Set Title of Room.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type |

| --- | --- |

| title | String | 

**Example**  

```js

bot.roomRename('My Renamed Room')

  .then(function(err) {

    console.log(err.message)

  });

```



### bot.getMessages(count) ⇒ Promise.<Array>

Get messages from room. Returned data has newest message at bottom.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type |

| --- | --- |

| count | Integer | 

**Example**  

```js

bot.getMessages(5).then(function(messages) {

  messages.forEach(function(message) {

    // display message text

    if(message.text) {

      console.log(message.text);

    }

  });

});

```



### bot.store(key, value) ⇒ Promise.<String> \| Promise.<Number> \| Promise.<Boolean> \| Promise.<Array> \| Promise.<Object>

Store key/value data.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| key | String | Key under id object |

| value | String \| Number \| Boolean \| Array \| Object | Value of key |



### bot.recall([key]) ⇒ Promise.<String> \| Promise.<Number> \| Promise.<Boolean> \| Promise.<Array> \| Promise.<Object>

Recall value of data stored by 'key'.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| [key] | String | Key under id object (optional). If key is not passed, all keys for id are returned as an object. |



### bot.forget([key]) ⇒ Promise.<String> \| Promise.<Number> \| Promise.<Boolean> \| Promise.<Array> \| Promise.<Object>

Forget a key or entire store.

**Kind**: instance method of [Bot](#Bot)  

| Param | Type | Description |

| --- | --- | --- |

| [key] | String | Key under id object (optional). If key is not passed, id and all children are removed. |



## Message : object

Message Object

**Kind**: global namespace  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Message ID |

| personId | string | Person ID |

| personEmail | string | Person Email |

| personAvatar | string | PersonAvatar URL |

| personDomain | string | Person Domain Name |

| personDisplayName | string | Person Display Name |

| roomId | string | Room ID |

| text | string | Message text |

| files | array | Array of File objects |

| created | date | Date Message created |



## File : object

File Object

**Kind**: global namespace  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Spark API Content ID |

| name | string | File name |

| ext | string | File extension |

| type | string | Header [content-type] for file |

| binary | buffer | File contents as binary |

| base64 | string | File contents as base64 encoded string |

| personId | string | Person ID of who added file |

| personEmail | string | Person Email of who added file |

| personAvatar | string | PersonAvatar URL |

| personDomain | string | Person Domain Name |

| personDisplayName | string | Person Display Name |

| created | date | Date file was added to room |



## Trigger : object

Trigger Object

**Kind**: global namespace  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Message ID |

| phrase | string \| regex | Matched lexicon phrase |

| text | string | Message Text (or false if no text) |

| raw | string | Unprocessed Message Text (or false if no text) |

| html | string | Message HTML (or false if no html) |

| markdown | string | Message Markdown (or false if no markdown) |

| mentionedPeople | array | Mentioned People (or false if no mentioned) |

| files | array | Message Files (or false if no files in trigger) |

| args | array | Filtered array of words in message text. |

| created | date | Message Created date |

| roomId | string | Room ID |

| roomTitle | string | Room Title |

| roomType | string | Room Type (group or direct) |

| roomIsLocked | boolean | Room Locked/Moderated status |

| personId | string | Person ID |

| personEmail | string | Person Email |

| personDisplayName | string | Person Display Name |

| personUsername | string | Person Username |

| personDomain | string | Person Domain name |

| personAvatar | string | Person Avatar URL |

| personMembership | object | Person Membership object for person |



## "log"

Flint log event.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| message | string | Log Message |



## "stop"

Flint stop event.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Flint UUID |



## "start"

Flint start event.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Flint UUID |



## "initialized"

Flint initialized event.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| id | string | Flint UUID |



## "roomLocked"

Room Locked event.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| id | string | Flint UUID |



## "roomUnocked"

Room Unocked event.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| id | string | Flint UUID |



## "personEnters"

Person Enter Room event.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| person | object | Person Object |

| id | string | Flint UUID |



## "botAddedAsModerator"

Bot Added as Room Moderator.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| id | string | Flint UUID |



## "botRemovedAsModerator"

Bot Removed as Room Moderator.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| id | string | Flint UUID |



## "personAddedAsModerator"

Person Added as Moderator.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| person | object | Person Object |

| id | string | Flint UUID |



## "personRemovedAsModerator"

Person Removed as Moderator.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| person | object | Person Object |

| id | string | Flint UUID |



## "personExits"

Person Exits Room.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| person | object | Person Object |

| id | string | Flint UUID |



## "mentioned"

Bot Mentioned.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| trigger | object | Trigger Object |

| id | string | Flint UUID |



## "message"

Message Recieved.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| trigger | object | Trigger Object |

| id | string | Flint UUID |



## "files"

File Recieved.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| trigger | trigger | Trigger Object |

| id | string | Flint UUID |



## "spawn"

Bot Spawned.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| id | string | Flint UUID |



## "despawn"

Bot Despawned.

**Kind**: event emitted  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| bot | object | Bot Object |

| id | string | Flint UUID |

## License

The MIT License (MIT)

Copyright (c) 2016-2017

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in

all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN

THE SOFTWARE.