@ambit-ai/ambit-client v1.3.5

ambit-client

A library to connect with the bot using SocketIO

install

npm install --save @ambit-ai/ambit-client

use

Here is an example of usage, written in Typescript.

import {AmbitClient, ConnectionStatus, Activity} from "AmbitClient";

// Initialize the client
const botConnection = new AmbitClient({
    baseUrl: 'https://yourUrlHere.ambithub.com',
    secret: "yourSecretHere"
});

// Subscribe to the connection status event
botConnection.connectionStatus$.subscribe(
  connectionStatus => {
    if (connectionStatus === ConnectionStatus.Online) {

        // Connection estableshed sucessfully. Lets try sending a message to the bot
        const activity: Activity = {
            type: "message",
            from: botConnection.user,
            locale: 'en-GB',
            text: 'Hi!'
        };
        
        botConnection.postActivity(activity).subscribe(); // post the activity to the Bot
    }
  }
);

botConnection.activity$.subscribe(activity => {

    // An incoming activity has been recieved
    if (activity.type === 'event' && activity.name === 'synapseBotEvent') {
        // A generic bot event
    }
    if (activity.type === 'operatorHandOver' || activity.type === 'operatorHandBack') {
        // Convesation handed over from and to the human operator
    }
    if (activity.type === 'typing') {
        // Typing event sent by the bot
    }
    if (activity.type === 'message') {
        if (activity.from.id === botConnection.user.id) {
        // Received activity sent by the client
        } else {
        // Received activity sent by the bot
        }
    }
});

N.B.: Currently all connections to bots are made publically. Meaning, the client does not need any form of authentication to talk to a Bot. The logic behind this is all bots are already avaliable publically on the internet, so anyone can already talk to them anyways. This is subject to change in the future. TL;DR: the secret parameter used when constructing an instance of AmbitClient is arbitrary, enter any value you like.

The client connection provides two RxJs streams, connectionStatus$ and activity$.

The first one can be used to listen to connectivity events. The bot will be ready to start talking with the connection status is ConnectionStatus.Online.

After the connection gets stablished, both user and conversationId will be available so they can be stored to reconnect to the conversation at a later stage.

The second provides a stream of activities (messages) coming from the bot, it also provides activies that the user has sent to the bot. Messages come in a variety of formats, see below for a few examples.

Message (Activity) Formats

This provides information about the shape of the "activity" objects sent between the bot and client. Please note, this documentation isn't complete, but should hopefully cover most of the basics.

Basics

The most important fields in an activity sent to, or recieved from, the bot are explained below.

Type (string)

The type of activity. Important types include "message", a message from/to the bot; and "typing", sent when the bot is generating a reply. Other types exist, but these are enough to send/recieve messages and indicate a reply is being sent.

Text (string)

Text content, used for "message" type activities. When a user sends or recieves a message, this is the text content for that message.

Timestamp (string)

UTC formatted date string, indicates when the activity occured. For a message, this would be when the message was sent, for example.

Local (string)

Local format for the message, for english messages you should use "en-GB".

From ({name: string, id: string})

Name and GUID ID of the user (or the bot) sending the message.

Conversation ({id: string})

GUID ID of the conversation the message relates to.

Attachments ({contentType: string, content: object}[])

Represents an attachment, such as a card or embedded content. This is an array of objects, with a string content type, and an object representing the content of that attachment. This object can vary, depending on the kind of attachment. For a more detailed explanation, see below.

Attachments

Hero Card

Hero Card attachments are represented as Microsoft Bot Builder framework Hero Cards. These attachments have the content type "application/vnd.microsoft.card.hero". Documentation attached, with summary below.

Title (string)

The title for the card.

Subtitle (string)

The subtitle for the card.

Text (string)

Text content for the card.

Images ({url: string}[])

Array of images for the card. Includes an url for the image to be displayed.

Buttons ({type: string, value: string, title: string, color: string})

Array of buttons for the card. Type indicates what action the button performs, for example, "openUrl" indicates the button should open an url on click. Value in the case of an "openUrl" button is the url to open. Title is the text content of the button. Color can be either "primary" or "secondary.