npm install zbox-addonLibrary to create ZBox Now! addons for Express
npm install --save zbox-addon
In your project root create a file called zbox-addon.json with the following schema:
``json`
{
"key": "hello-addon",
"name": "Hello!",
"description": "My very first ZBox Addon",
"vendor": {
"name": "Elias Nahum",
"icon_url": "{{localBaseUrl}}/images/logo.png"
},
"price": {
"currency": "CLP",
"value": 0
},
"links": {
"published_url": "{{localBaseUrl}}/published",
"descriptor_url": "{{localBaseUrl}}/zbox-addon.json",
"homepage_url": "http://localhost:3000"
},
"installable": {
"installed_url": "{{localBaseUrl}}/installed",
"uninstalled_url": "{{localBaseUrl}}/uninstalled",
"config_url": "{{localBaseUrl}}/config",
"allow_global": true,
"allow_channel": false
},
"webhook": {
"enable_incoming": true,
"outgoing": [
{
"key": "hello_webhook_1",
"callback_urls": [
"{{localBaseUrl}}/webhook"
],
"triggers": [
"hello:"
]
}
]
}
}
And then another file called config.json like this one:
`json`
{
"development": {
"baseUrl": "http://localhost:3000"
},
"production": {
"baseUrl": "http://myaddon.com"
}
}
If your zbox-addon.json file has the {{localBaseUrl}} pattern it will be replace by the baseUrl
in config.json at runtime with the one that corresponds to the environment.
`javascript
var express = require('express');
var zbox = require('zbox-addon').addon;
var app = express();
var addon = zbox(app, opts, logger, callback);
`
- app mandatory express app
- opts options to configure the addon
- logger optional logger to use (winston used by default if no logger is supplied)
- callback function to call when the addon has finish configuration
#### Options
log_to_filesystem(bool)
when using the default logger you can log entries to a log file in the logs directory
in your project root. The logs will auto rotate each day with the following format: filename-yyyy-MM-dd.log
log_filename(string)
the name of the file to use with the default logger if none is supplied zboxaddon will be used.
#### Methods
context()
Middleware to be use in conjuction with express routes.
In case of a webhook the req.hook object will be set with the following values:
`json`
{
"token": "use this to validate the webhook",
"team_id": "the id of the team from where the webhook was initiated",
"channel_id": "the id of the channel from where the webhook was initiated",
"channel_name": "the name of the channel from where the webhook was initiated",
"datetime": "Date and time when the webhook was initiated",
"user_id": "the id of the user who initiated the webhook",
"username": "the username of the user who initiated the webhook",
"message": "the text written by the user"
}
For the configuration route req.context is set with the following values:`json`
{
"team_id": "The id of the team that is configuring the addon",
"team_name": "The name of the team"
}
#### Events
The addon will return some important information through events
- published
Once your addon has been published on ZBox Now! the published event will be triggered with the following(string)
arguments:
- client_id
- client_secret
IMPORTANT: This credentials should be save in case you later need to make api calls.
Note: client_secret cannot be recovered if you lose it.
- installed
Once your addon has been installed by a team in ZBox Now! the installed event will be triggered with
the following arguments:
- team(object)
- id: the Id of the team that installed the addon(string)
- name: the name of the team that installed the addon(object)
- incoming
- token the token to use when sending messages to ZBox Now! to this team
- outgoing: one for each webhook registered(string)
- key: the key used in the zbox-addon.json to configure the webhooks(string)
- token: the token to validate a webhook request.
Note: The team name is latter use with every api call so you probably want to save this
values somewhere like in your Database.
- uninstalled
If your addon is uninstalled by a team in ZBox Now! the uninstalled event will be triggered with
the following arguments:
- team_id(string)
Note: Use this to remove all the necesary information for a team. Once the team has uninstalled your addon,
you will no longer be able to use the API, you won't be able to send messages and your webhooks won't be triggered.
The API is used to get information from ZBox Now!
In order to use the API you need to register the addon, client_id and client_secret
`javascript
var api = require('zbox-addon').api;
var zboxApi = api(addon, opts);
`
- client_id(string)
- client_secret
- url: use this option when you want to use the API from a URL different than
ZBox Now! production server.
- sendMessage(opts, callback)
This method lets you send a message to ZBox Now! using your incoming webhook token for one of the teams.
if you define a callback(err) it will be called after the message has been sent or an error has ocurred.
- opts
- message(string): the message to send markdown is available.(string)
- channel_name: the name of the channel that will recieve the messagetown-square
(if none is supplied then the message will be sent to the default channel )
- prepare(message)
Prepares the message to be sent to ZBox Now!
for example:
`javascript`
return res.json(zboxApi.prepare(message));
- getChannels(teamName, callback)
Returns all the existing channels for a team to the callback function as an array of objects argument.
- teamName(string): the name of the team
The returned array of objects to the callback have the following structure:
`json`
[
{
"id": "the id of the channel",
"type": "the type of channel values can be 'channel' or 'group'",
"display_name": "The name of the channel the way it is shown to the users",
"name": "The actual name of the channel (use this with sendMessage)"
}
]
- getUsers(teamName, callback)
Returns all the existing users for a team to the callback function as an array of objects argument.
- teamName(string): the name of the team
The returned array of objects to the callback have the following structure:
`json``
[
{
"id": "the id of the user",
"username": "the username of the user",
"email": "The email address of the user",
"nickname": "(only if is set)",
"firs_name": "(only if is set)",
"last_name": "(only if is set)",
"locale": "The user preferred language"
}
]
(The MIT License)
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.