amio-chat-sdk-web

v1.6.3

Published

6 months ago

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

Downloads

0High
0Medium
0Low

amio-io

amio amio.io webchat livechat

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.

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

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

Execute single test

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

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Amio Chat SDK for Web

Installation

Quickstart

ES5

ES6

Browser (script tag)

Best Practices

Quick Replies

Quick Replies API

API

connect(config)

disconnect()

isConnected()

getSessionId()

dictation.sendData(binaryData)

dictation.start(mimeType)

dictation.stop()

files.upload(fileName, mimeType, binaryData)

files.uploadVoice(mimeType, binaryData)

messages.send(content, metadata)

messages.sendText(text, metadata)

messages.sendImage(url, metadata)

messages.sendFile(url, metadata)

messages.sendQuickReply(text, quickReplyPayload, metadata)

messages.list(nextCursor, max)

notifications.send(payload)

notifications.sendMessagesRead()

postbacks.send(postbackPayload)

Events

events.onMessageReceived(func)

events.onMessageEcho(func)

events.onNotificationReceived(func)

events.onConnectionStateChanged(func)

events.onDictationResultReceived(func)

Tests

Tips - quicker testing

Tips - promises

Execute all tests

Execute single test

License