npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

amio-sdk-js

v4.4.2

Published

Multi-messenger javascript library for Amio.io API. https://amio.io

Downloads

26

Readme

amio-sdk-js

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

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()
  • 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
}))
  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: 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
  1. 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:

Viber Bot:

Viber Business Messages:

SMS:

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 => {
      // ...
    })