Skip to content
Multi-messenger Node.js library for API.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


CircleCI npm version

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. ;-)


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


npm install amio-sdk-js --save


Send a message

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

const amioApi = new AmioApi({
  accessToken: 'get access token at'

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: {
amioWebhookRouter.onMessageReceived(function(data) {
  console.log('new message received from contact ' + + 'with content ' + data.content)
})'/webhooks/amio', function (req, res) {
  amioWebhookRouter.handleEvent(req, res)


API - setup & usage

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

const amioApi = new AmioApi({
  accessToken: 'get access token at'

// 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
  const message = await amioApi.messages.send({/* message */})
} catch(err){
    if (err.amioApiError) {
      console.error(err.jsonify(), err) 
With promises
amioApi.messages.send({/* message */})
  .then(message => ...)
  .catch(err => {
    if (err.amioApiError) {
    console.error(err.jsonify(), 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?')
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()
  • contentBuilder.typeText(text)

API - content builders - horizontal scroll

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

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


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;
  verify: attachRawBody
  1. 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 must be a string. The numbers can be converted to a different value
      // get CHANNEL_ID at
      // get SECRET at{{CHANNEL_ID}}/webhook
    // xhubEnabled: false // disables X-Hub-Signature verification, do it at your own risk only

// 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 ${} was received!'))
amioWebhookRouter.onMessagesDelivered(webhook => {/* TODO */})
amioWebhookRouter.onMessagesRead(webhook => {/* TODO */})
amioWebhookRouter.onMessageEcho(webhook => {/* TODO */})
amioWebhookRouter.onPostbackReceived(webhook => {/* TODO */})
amioWebhookRouter.onOptIn(webhook => {/* TODO */})'/webhooks/amio', (req, res) => amioWebhookRouter.handleEvent(req, res))

module.exports = router
  1. Attach router to express app
const amioWebhookRouter = require('path/to/amio-webhook-router.js')
app.use('/', amioWebhookRouter)

Webhooks - event types


Viber Bot:

Viber Business Messages:



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

    .then(response => {
      // ...
You can’t perform that action at this time.