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-chat-sdk-web

v1.6.1

Published

Amio Chat JavaScript SDK for custom webchat implementation. https://amio.io

Downloads

63

Readme

Amio Chat SDK for Web

JavaScript client library for Amio Chat.

Installation

npm install amio-chat-sdk-web --save

Quickstart

The library should work in all JS environments, including ES6, ES5 and (common) browsers.

You can find your Channel ID in Amio administration.

ES5

var amioChat = require('amio-chat-sdk-web')

amioChat.connect({
  channelId: '6495613231087502282'
})

ES6

import {amioChat} from 'amio-chat-sdk-web'

amioChat.connect({
  channelId: '6495613231087502282'
})

Browser (script tag)

Minified version available amio-chat-sdk-web.min.js (will be available in CDN in the future).

<html>
  <head>
    <script src="path/to/amio-chat-sdk-web.min.js" type="text/javascript"></script>
  </head>
  <body>
    <script type="text/javascript">
        amioChat.connect({
          channelId: '6495613231087502282'
        });
    </script>
  </body>
</html>

Best Practices

Quick Replies

Quick Replies are buttons with a set of pre-defined short replies. Their look and feel are subject to front-end implementation, but certain design aspects should always be true:

  • Quick Reply buttons are displayed above the user input
  • When a Quick Reply button is clicked, its title is rendered as a text message and, at the same time, a call to Amio Chat server is made (see below)
  • All of the Quick Reply buttons are dismissed as soon as user clicks one or replies using text input
  • Quick Replies can be attached to any message type (text, image...)
  • Text input can be disabled (if desirable) when Quick Reply buttons are displayed

Quick Replies API

When a message is received via events.onMessageReceived(func) callback, the message's content can have a quick_replies field indicating that one or more Quick Reply buttons should be displayed.

{
"content": {
  "type": "{{MESSAGE TYPE}}",
  "payload": "{{MESSAGE PAYLOAD}}",
  "quick_replies": [
    {
      "type": "text",
      "title": "Yes",
      "payload": "QR_YES"
    },
    {
      "type": "text",
      "title": "No",
      "payload": "QR_NO"
    }
  ]
}

Parameters:

  • quick_replies - Array of up to 11 Quick Reply buttons.
    • type - Button type. Only text is supported.
    • title - Button's title text. Maximum 20 characters.
    • payload - Button's payload is used to identify which button was pressed. Maximum 1000 characters.
    • image_url - Optional. URL of an image that would be used as a button icon.

When user clicks on one of the Quick Reply buttons, use messages.send(content, metadata) function to notify Amio Chat server (or use shortcut messages.sendQuickReply(text, quickReplyPayload, metadata)). The content must be a text message with Quick Reply's title as a payload and quick_reply field with Quick Reply's payload:

{
"content": {
  "type": "text",
  "payload": "Yes",
  "quick_reply": {
    "payload": "QR_YES"
  }
}

API

connect(config)

Connects to Amio Chat server.

Parameters:

  • config - Configuration object. Currently supported params are:
    • channelId - ID of your Amio Chat channel.
    • externalContactId - (optional) Use external contact ID to connect and reconnect to a chat session. The same external contact ID will always connect to the same session.
    • storageType - (optional) Allows to choose if session data will be stored in localStorage or sessionStorage. Default value is 'local'. Allowed values are:
      • 'local' - use localStorage
      • 'session' - use sessionStorage
amioChat.connect({
  channelId: '6495613231087502282',
  externalContactId: 'externalContactId',
  storageType: 'local'
})
.then(() => {
  console.log('Connection successful')
})
.catch(err => {
  console.log('Connection error:', err)
})

disconnect()

Disconnects from Amio Chat server.

isConnected()

Returns true if the client is successfully connected to Amio Chat server.

getSessionId()

It returns session ID of the client connected to Amio Chat server. Returns null if the connection was not successful.

dictation.sendData(binaryData)

Sends audio data to be transcribed as text. The data can only be sent after dictation request is started by calling dictation.start(mimeType)

Parameters:

  • binaryData - Binary data of the audio. Accepts all data types that are accepted by Buffer.from.

Example usage:

amioChat.dictation.start('audio/webm')
.then(() => {
  amioChat.dictation.sendData(/* audio data */)
    .then(() => {
      console.log('Data sent successfully.')
    })
    .catch(() => {
      console.log('Error while sending audio data:', err)
    })
})
.catch(err => {
  console.log('Error while starting dictation:', err)
})

dictation.start(mimeType)

Initializes dictation request, making the voice recognition engine ready to receive data.

Parameters:

  • mimeType - MIME type of the file.

Example usage:

amioChat.dictation.start('audio/webm')
.then(() => {
  console.log('Dictation started successfully.')
})
.catch(err => {
  console.log('Error while starting dictation:', err)
})

dictation.stop()

Ends dictation request, marking the voice recognition request as complete.

Example usage:

amioChat.dictation.stop()
.then(() => {
  console.log('Dictation stopped successfully.')
})
.catch(err => {
  console.log('Error while stopping dictation:', err)
})

files.upload(fileName, mimeType, binaryData)

Uploads the specified file and returns URL of the uploaded file. Can be used in combination with messages.sendFile(url, metadata) to implement sending of local files through Amio Chat.

Parameters:

  • fileName - Name of the file.
  • mimeType - MIME type of the file.
  • binaryData - Binary data of the file. Accepts all data types that are accepted by Buffer.from.

Response format:

  • url - URL of the uploaded file.

Example usage:

amioChat.files.upload('test.txt', 'text/plain', 'test')
.then((response) => {
  console.log('File uploaded successfully')

  // Now let's send the file through Amio Chat
  amioChat.messages.sendFile(response.url)
})
.catch(err => {
  console.log('Error while uploading file:', err)
})

files.uploadVoice(mimeType, binaryData)

Uploads a voice recording for voice-to-text recognition. This function is recommended for transcripting longer recordings in a request-response manner.

For asynchronous voice-to-text recognition, see Dictation.

Parameters:

  • mimeType - MIME type of the audio.
  • binaryData - Binary data of the audio. Accepts all data types that are accepted by Buffer.from.

Response format:

  • text - Text transcription of the audio recording.

Example usage:

amioChat.files.uploadVoice('audio/webm', buffer)
.then((response) => {
  console.log('Transcription:', response.text)
})
.catch(err => {
  console.log('Error while uploading voice:', err)
})

messages.send(content, metadata)

Sends a message.

Parameters:

  • content - Message content. See Amio documentation for details about the format.
  • metadata - Optional. Add metadata to the message. Metadata has to be an object and can carry whatever data needed to be sent along with the message.

Example usage:

amioChat.messages.send({
  type: 'text',
  payload: 'Hello world'
}, {
  any: "arbitrary data"
})
.then(() => {
  console.log('Message sent successfully')
})
.catch(err => {
  console.log('Error while sending message:', err)
})

messages.sendText(text, metadata)

Sends a text message. This is just a handy shortcut for messages.send({type: 'text', payload: '...'}, metadata)

Parameters:

  • text - The content of the text message.
  • metadata - Optional. Add metadata to the message. Metadata has to be an object and can carry whatever data needed to be sent along with the message.

messages.sendImage(url, metadata)

Sends an image message. This is just a handy shortcut for messages.send({type: 'image', payload: '...'}, metadata)

Parameters:

  • url - The URL of the image.
  • metadata - Optional. Add metadata to the message. Metadata has to be an object and can carry whatever data needed to be sent along with the message.

messages.sendFile(url, metadata)

Sends an file message. This is just a handy shortcut for messages.send({type: 'file', payload: '...'}, metadata)

Parameters:

  • url - The URL of the file.
  • metadata - Optional. Add metadata to the message. Metadata has to be an object and can carry whatever data needed to be sent along with the message.

messages.sendQuickReply(text, quickReplyPayload, metadata)

Sends a text message with Quick Reply payload, indicating that user pressed the Quick Reply button. This is just a handy shortcut for messages.send({type: 'text', payload: '...', quick_reply: {payload: '...'}}, metadata)

Parameters:

  • text - The content of the text message.
  • quickReplyPayload - Payload indicates which Quick Reply button has been pressed.
  • metadata - Optional. Add metadata to the message. Metadata has to be an object and can carry whatever data needed to be sent along with the message.

messages.list(nextCursor, max)

Loads messages from message history. Can be called multiple times to move further back in history.

Parameters:

  • nextCursor - Reference point (message id) indicating where to start loading messages in history. If set to null, messages will be read from the beginning (newest first).
  • max - Number of messages to load. Should be between 1 and 100 (default is 10).

Response format:

  • messages - Array of messages, sorted from newest to oldest.
  • cursor.next - Cursor pointing to subsequent messages. Use this cursor in the next call of messages.list().
  • cursor.has_next - False if there are no more messages in the history, true otherwise.
{ 
  "messages": [ 
    { 
      "id": "6500763984087564228",
      "direction": "received",
      "sent": "2019-02-11T16:35:12.163Z",
      "delivered": null,
      "read": null,
      "content": {
        "type": "text",
        "payload": "World"
      },
      "metadata": {
        "any": "arbitrary data"
      }
    },
    { 
      "id": "6500754972885466525",
      "direction": "received",
      "sent": "2019-02-11T15:59:23.722Z",
      "delivered": null,
      "read": null,
      "content": {
        "type": "text",
        "payload": "Hello"
      }
     },
  ],
  "cursor": {
    "next": "6500754972885466525",
    "has_next": true
  } 
}

Example usage:

var nextCursor = null
amioChat.messages.list(nextCursor, 5)
.then(response => {
  console.log('First 5 messages loaded:', response.messages)
  nextCursor = response.cursor.next //save the cursor so we can load more messages later

  amioChat.messages.list(nextCursor, 5)
  .then(nextResponse => {
    console.log('Next 5 messages loaded:', nextResponse.messages)
    nextCursor = nextResponse.cursor.next //save the cursor so we can load more messages later
  })
})
.catch(err => {
  console.log('Error while loading messages:', err)
})

notifications.send(payload)

Sends a notification. The payload can be any valid JSON element (string, object, number...).

amioChat.notifications.send({
  event: 'my_awesome_event'
})
.then(() => {
  console.log('Notification sent successfully')
})
.catch(err => {
  console.log('Error while sending notification:', err)
})

notifications.sendMessagesRead()

Sends an event indicating that all received messages were read by the receiver. It is up to the implementer to decide when the messages are considered read and call this function.

Parameters:

  • none
amioChat.notifications.sendMessagesRead()
.then(() => {
  console.log('Messages marked as read')
})
.catch(err => {
  console.log('Error while marking messages as read:', err)
})

postbacks.send(postbackPayload)

Sends a postback. Postbacks are usually triggered when user presses a button.

Parameters:

  • postbackPayload - Arbitrary string that is usually used to determine which button was pressed. Must not be empty.
amioChat.postbacks.send('test_payload')
.then(() => {
  console.log('Postback sent successfully.')
})
.catch(err => {
  console.log('Error while sending postback:', err)
})

Events

events.onMessageReceived(func)

Sets a callback function that will be called every time a message is received from server.

Parameters:

  • func - Function. It should accept one parameter which contains the message content. The message content format is following:
{
  "id": "{{MESSAGE ID}}",
  "direction": "received",
  "content": {
    "type": "{{MESSAGE TYPE}}",
    "payload": "{{MESSAGE PAYLOAD}}",
    "quick_replies": [
      {
        "type": "text",
        "title": "Click me!",
        "payload": "DEVELOPER_DEFINED_PAYLOAD"
      }
    ]
  },
  "metadata": {
    "any": "arbitrary data"
  },
  "sent": "{{SENT_TIMESTAMP}}",
  "delivered": "{{DELIVERED_TIMESTAMP}}",
  "read": "{{READ_TIMESTAMP}}"
}

Example usage:

amioChat.events.onMessageReceived((data) => {
  console.log('received message', data)
})

events.onMessageEcho(func)

Sets a callback function that will be called every time a message echo is received from server. Message echo means a message was sent through a different connection associated with the same session (for example, the user has two browser tabs opened, so that's the same session but two different connections).

Parameters:

  • func - Function. It should accept one parameter which contains the message content. The message content format is following (conveniently, it's the same as received message, except direction will be sent):
{
  "id": "{{MESSAGE ID}}",
  "direction": "sent",
  "content": {
    "type": "{{MESSAGE TYPE}}",
    "payload": "{{MESSAGE PAYLOAD}}"
  },
  "metadata": {
    "any": "arbitrary data"
  },
  "sent": "{{SENT_TIMESTAMP}}",
  "delivered": "{{DELIVERED_TIMESTAMP}}",
  "read": "{{READ_TIMESTAMP}}"
}

Example usage:

amioChat.events.onMessageEcho((data) => {
  console.log('message echo', data)
})

events.onNotificationReceived(func)

Sets a callback function that will be called every time a notification is received from server.

Parameters:

  • func - Function. It should accept one parameter which contains the notification payload. The payload can be any valid JSON element (string, object, number...).

Example usage:

amioChat.events.onNotificationReceived((payload) => {
  console.log('received notification', payload)
})

events.onConnectionStateChanged(func)

Sets a callback function that will be called when connection state changes from offline to online or vice versa.

Parameters:

  • func - Function. It should accept one parameter which will be set to true when connection changes to online, and false when connection changes to offline.

Example usage:

amioChat.events.onConnectionStateChanged((online) => {
  if(online) {
    console.log('We are online :)')
  } else {
    console.log('We are offline :(')
  }
})

events.onDictationResultReceived(func)

Sets a callback function that will be called when there's a new result of recognized text from dictation.

See also:

Parameters:

  • func - Function. It should accept one parameter which contains the trancribed text. The format is following:
{
  "text": "transcribed text"
}

Example usage:

amioChat.events.onDictationResultReceived((data) => {
  console.log('Received dictation result:' data.text)
})

Tests

Tips - quicker testing

During development, comment the lib import and replace it with src one:

// import amioChat from '../lib/amio-chat-sdk-web'
import {amioChat} from '../src/amio-chat-client'

Tips - promises

Since we can't use async/await, always pay attention that every promised base test has this form:

it('test', () => {
  return createPromise() // mocha handles it
})

Execute all tests

  1. Build the code - npm run build
  2. Run the test suite - npm run test.

Execute single test

  1. Build the code - npm run build
  2. To run a single test, you have to include mocha --require babel-register --colors.

License

MIT