amio-sdk-js

Server-side library implementing Amio API for instant messengers. It supports API calls as well as webhooks.

Let us know how to improve this library. We'll be more than happy if you report any issues or even create pull requests. ;-)

• Installation
• Quickstart
  • send a message
  • receive a message
• SDK API
  • setup & usage
  • error handling
  • methods
  • content builders
• Webhooks
  • setup & usage
  • event types
• Missing a feature?

Prerequisities

Signup to Amio and create a channel before using this library.

Installation

npm install amio-sdk-js --save

Quickstart

Send a message

const AmioApi = require('amio-sdk-js').AmioApi

const amioApi = new AmioApi({
  accessToken: 'get access token at https://app.amio.io/administration/settings/api'
})

async function sendMessage() {
  const message = await amioApi.messages.send({
    channel: {id: '{CHANNEL_ID}'},
    contact: {id: '{CONTACT_ID}'},
    content: content
  })

  return message
}

Receive a message

const express = require('express')
const router = express.Router()
const WebhookRouter = require('amio-sdk-js').WebhookRouter

const amioWebhookRouter = new WebhookRouter({
    secrets: {
      '{CHANNEL_ID}':'{SECRET}'
    }
})

amioWebhookRouter.onMessageReceived(function(data) {
  console.log('new message received from contact ' + data.contact.id + 'with content ' + data.content)
})

router.post('/webhooks/amio', function (req, res) {
  amioWebhookRouter.handleEvent(req, res)
})

SDK API

API - setup & usage

const AmioApi = require('amio-sdk-js').AmioApi

const amioApi = new AmioApi({
  accessToken: 'get access token at https://app.amio.io/administration/settings/api'
})

// request with async/await
const message = await amioApi.messages.send({/* message */})

// request with a promise
amioApi.messages.send({/* message */})
 .then(message => ...)

API - error handling

Amio API errors keep the structure described in the docs.

With async/await

try{
  const message = await amioApi.messages.send({/* message */})
} catch(err){
    if (err.amioApiError) {
      console.error(err.jsonify(), err)
      return
    }

    console.error(err)
}

With promises

amioApi.messages.send({/* message */})
  .then(message => ...)
  .catch(err => {
    if (err.amioApiError) {
    console.error(err.jsonify(), err)
    return
  }

  console.error(err)
})

API - methods

amioApi.*	Description	Links
channels.get(channelId)	Get information about specified channel.	docs
channels.list(params)	List available channels.	docs, params
channels.create(request)	Create a new channel.	docs
channels.update(channelId, request)	Update specified channel.	docs
channels.delete(channelId)	Delete specified channel.	docs
contentBuilder.typeAudio(url)	Start building Audio content.	sdk-docs
contentBuilder.typeFile(url)	Start building File content.	sdk-docs
contentBuilder.typeGeneric(payload, type)	Start building any content.	sdk-docs
contentBuilder.typeImage(url)	Start building Image content.	sdk-docs
contentBuilder.typeVideo(url)	Start building Video content.	sdk-docs
contentBuilder.typeStructure()	Start building Structure content.	sdk-docs
contentBuilder.typeText(text)	Start building Text content.	sdk-docs
contacts.get(channelId, contactId)	Get information about a contact in specified channel.	docs
contacts.list(channelId, params)	List contacts for specified channel.	docs, params
contacts.delete(channelId, contactId)	Delete a contact within specified channel.	docs
messages.send(message)	Send a message to a contact.	docs
messages.list(channelId, contactId, params)	List messages for specified channel and contact.	docs, params
notifications.send(notification)	Send a notification to a contact.	docs
settings.get(channelId)	Get settings for specified channel.	docs
settings.set(channelId, setting)	Modify settings for specified channel.	docs

API - content builders

Use content-builders to better structure your code. The builders represent all available message types and it's up to you pick the right builder for the right platform.

For example, you can add a location quick reply to your question:

const content = amioApi.contentBuilder.typeText('Where are you now?')
  .addQuickReply('location')
  .build()

assertEquals(content, {
  type: 'text',
  payload: 'Where are you now?',
  quick_replies: [{type: 'location'}]
})

Then you just send the content in the message:

amioApi.messages.send({channel, contanct, content})

All available builders have these methods:

• addQuickReply(quickReply) - adds a quick reply according to docs
• addQuickReply(type) - adds a quick reply for type of location, email or phone_number. Suitable for quickReplies with type field only.
• build() - returns final content

Available builders are:

• contentBuilder.typeGeneric(payload, type)
• contentBuilder.typeImage(url)
• contentBuilder.typeVideo(url)
• contentBuilder.typeStructure()
  • use .addNextStructure() to create a horizontal scroll
• contentBuilder.typeText(text)

API - content builders - horizontal scroll

const content = contentBuilder.typeStructure()
        .setText('structure 1')
        .addNextStructure()
        .setText('structure 2')
        .build();

assertEquals(content, {
  type: 'structure',
  payload: [
    {text: 'structure 1'},
    {text: 'structure 2'}
  ]
})

Webhooks

Central logic to handle webhooks coming from Amio is WebhookRouter. What does it do?

• It responds OK 200 to Amio.
• It verifies X-Hub-Signature.
• It routes events to handlers (e.g. event message_received to a method registered in amioWebhookRouter.onMessageReceived())

Webhooks - setup & usage

1. Attach raw body to requests.

const bodyParser = require('body-parser');
const attachRawBody = require('amio-sdk-js').attachRawBody;
app.use(bodyParser.json({
  verify: attachRawBody
}))

2. Setup webhook routing

const express = require('express')
const router = express.Router()
const WebhookRouter = require('amio-sdk-js').WebhookRouter

const amioWebhookRouter = new WebhookRouter({
    secrets: {
      // CHANNEL_ID: SECRET
      // !!! CHANNEL_ID must be a string. The numbers can be converted to a different value
      // get CHANNEL_ID at https://app.amio.io/administration/channels/
      // get SECRET at https://app.amio.io/administration/channels/{{CHANNEL_ID}}/webhook
      '15160185464897428':'thzWPzSPhNjfdKdfsLBEHFeLWW'
    }
    // xhubEnabled: false // disables X-Hub-Signature verification, do it at your own risk only
})

// add secret dynamically
amioWebhookRouter.setSecret('48660483859995133', 'fdsafJzSPhNjfdKdfsLBEjdfks')

// error handling, e.g. x-hub-signature is not correct
amioWebhookRouter.onError(error => console.error(error))

// assign event handlers
amioWebhookRouter.onMessageReceived(webhook => console.log('a new message from contact ${data.contact.id} was received!'))
amioWebhookRouter.onMessagesDelivered(webhook => {/* TODO */})
amioWebhookRouter.onMessagesRead(webhook => {/* TODO */})
amioWebhookRouter.onMessageEcho(webhook => {/* TODO */})
amioWebhookRouter.onPostbackReceived(webhook => {/* TODO */})
amioWebhookRouter.onOptIn(webhook => {/* TODO */})

router.post('/webhooks/amio', (req, res) => amioWebhookRouter.handleEvent(req, res))

module.exports = router

3. Attach router to express app

const amioWebhookRouter = require('path/to/amio-webhook-router.js')
app.use('/', amioWebhookRouter)

Webhooks - methods

amioWebhookRouter.*	Description
setSecret(channelId, secret)	Pairs a channelId with a secret. Setting secret for the same channelId twice will override the previous value.
getSecret(channelId)	Returns a secret if found.

Webhooks - event types

Facebook:

• Message Received
• Messages Delivered
• Messages Read
• Message Echo
• Postback Received
• Opt-in

Viber Bot:

• Message Received
• Messages Delivered
• Messages Read
• Message Echo
• Postback Received

Viber Business Messages:

• Messages Delivered
• Messages Read
• Message Failed
• Message Echo

SMS:

• Message Received
• Messages Delivered
• Message Failed

Debugging

To enable logging for debugging purposes, set the following environment variable:

variable	value
process.env.DEBUG	amio-sdk-js:*

To narrow down logs even further, replace the * wildcard with a specific endpoint.

Missing a feature?

File an issue or create a pull request. If you need a quick solution, use the prepared axios http client:

const amioHttpClient = require('amio-sdk-js').amioHttpClient

amioHttpClient.get('/v1/messages')
    .then(response => {
      // ...
    })