Methods

Open the Widget programmatically, and enable the start button if it is disabled.

If the property autoShow is true, don't use this function after the function connect() that starts the rendering process of the component

widgetInstance.open();

case scenarios:

At the creation stage of the widget it is asked to open the widget automatically, then the property autoShow would be set to true. When the widget is created by the client, they want to have more control over the behavior of the widget and so it is created with the dynamic method, open it up to the use of the integrated methods, and they happen to want to use the open method after the connect() method.

Close Widget programmatically, with optional start button disable property.

/**
 * Close Widget
 * @param {boolean} disable property to deactivate (is optional)
 * @return {void}
 */

widgetInstance.close(true);
widgetInstance.close();

Enable the Widget start button if it is disabled.

widgetInstance.enable()

Set Flow

someFlowId is the id number of a specific flow from the bot that is being used by the widget and someStringValue is the string value of the injected parameters.

/**
 * Get Members Array
 * @param {number} flowId Id of the room
 * @param {Record<string, string>?} storedParams object of params and values, is optional
 * @return {Promise<void>}
 */
// without context 
widgetInstance.setFlow(
    "<someFlowId>"
);
// with context
widgetInstance.setFlow(
    "<someFlowId>", 
    {
        param1: "<someStringValue>",
        param2: "<someStringValue2>",
        ...
        paramN: "<someStringValueN>",
    }
);

Get Room

/**
 * Get Room
 * @param {string} roomId Id of the room
 * @return {Promise<Room>} the room of the used room id
 */

widgetInstance.getRoom("<roomId>");

// example 
// {
//     "unread": 0,
//     "id": "<some-id>",
//     "bot": {
//         "id": "<some-id>",
//         "name": "Widget Shipify 2.0",
//         "type": "Widget"
//     },
//     "type": "client",
//     "company": {
//         "id": "<numeric-id>",
//         "name": "Shippify"
//     },
//     "channel": "Widget",
//     "deleted": false,
//     "members": [
//         "<some-member-id>",
//         "<some-member-id-2>"
//     ],
//     "avatarUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/default_avatar.jpeg",
//     "createdAt": "2022-01-14T21:47:24.918Z",
//     "updatedAt": "2022-01-14T21:47:24.918Z",
//     "name": "operator:123",
//     "membersInfo": [
//         {
//             "id": "<some-id>",
//             "referenceId": "<some-reference-id>",
//             "roomId": "<some-room-id>",
//             "botId": "<some-bot-id>",
//             "companyId": "<numeric-company-id>",
//             "socketId": "<some-socket-id>",
//             "createdAt": "2022-01-14T21:47:24.556Z",
//             "memberType": "user"
//         },
//         {
//             "id": "<some-id>",
//             "legalId": "<some-legal-id>",
//             "names": "alexander",
//             "referenceId": "<some-reference-id>",
//             "roomId": "<some-room-id>",
//             "groupRoomId": "<some-group-room-id>",
//             "botId": "<some-bot-id>",
//             "companyId": "<numeric-company-id>",
//             "socketId": "<some-socket-id>",
//             "createdAt": "2022-01-14T21:47:24.000Z",
//             "memberType": "user"
//         },
//         {
//             "id": "<some-id>",
//             "legalId": "<some-legal-id>",
//             "names": "alexander",
//             "referenceId": "<some-reference-id>",
//             "roomId": "<some-room-id>",
//             "groupRoomId": "<some-group-room-id>",
//             "botId": "<some-bot-id>",
//             "companyId": "<numeric-company-id>",
//             "socketId": "<some-socket-id>",
//             "createdAt": "2021-12-17T22:59:38.000Z",
//             "memberType": "user"
//         }
//     ],
//     "lastMessageAt": "2022-02-08T19:24:19.541Z",
//     "channelProvider": "Widget"
// }

Get Members

/**
 * Get Members Array
 * @param {string} roomId Id of the room
 * @return {Promise<Member[]>} the list of members inside the room
 */

widgetInstance.getMembers("<roomId>");

// example
// [
//     {
//         "id": "<some-id>",
//         "referenceId": "<some-reference-id>",
//         "roomId": "<some-room-id>",
//         "botId": "<some-bot-id>",
//         "companyId": "<numeric-company-id>",
//         "socketId": "<some-socket-id>",
//         "createdAt": "2022-01-14T21:47:24.556Z",
//         "memberType": "user"
//     },
//     {
//         "id": "<some-id>",
//         "legalId": "<some-legal-id>",
//         "names": "alexander",
//         "referenceId": "<some-reference-id>",
//         "roomId": "<some-room-id>",
//         "groupRoomId": "<some-group-room-id>",
//         "botId": "<some-bot-id>",
//         "companyId": "<numeric-company-id>",
//         "socketId": "<some-socket-id>",
//         "createdAt": "2022-01-14T21:47:24.000Z",
//         "memberType": "user"
//     },
//     {
//         "id": "<some-id>",
//         "legalId": "<some-legal-id>",
//         "names": "alexander",
//         "referenceId": "<some-reference-id>",
//         "roomId": "<some-room-id>",
//         "groupRoomId": "<some-group-room-id>",
//         "botId": "<some-bot-id>",
//         "companyId": "<numeric-company-id>",
//         "socketId": "<some-socket-id>",
//         "createdAt": "2021-12-17T22:59:38.000Z",
//         "memberType": "user"
//     }
// ],

Set Current Room

/**
 * Set Current Room
 * @param {string} roomId Id of the room
 * @return {void}
 */

widgetInstance.setCurrentRoom("<roomId>");

Join Room

/**
 * @typedef ApiResponse
 * @property {string[]} message Response message
 * @property {boolean} status Response status boolean
 * @property {string} statusMessage  Response status message
 */


/**
 * Join Room
 * @param {string} roomId Id of the room
 * @param {string} userId Id of the user
 * @return {Promise<ApiResponse>} Promise response
 */

widgetInstance.joinRoom("<roomId>", "<userId>");

Leave Room

/**
 * @typedef ApiResponse
 * @property {string[]} message Response message
 * @property {boolean} status Response status boolean
 * @property {string} statusMessage  Response status message
 */


/**
 * Leave Room
 * @param {string} roomId Id of the room
 * @param {string} userId Id of the user
 * @return {Promise<ApiResponse>} Promise response
 */
 
widgetInstance.joinRoom("<roomId>");

Open Room With User

Open a chat with a specific user.

/**
 * Open Room With User
 * @param {string} userId Id of the user
 * @return {Promise<void>} Promise response
 */
 
widgetInstance.openRoomWithUser({ id: <someId>, names: <someName> });

This method automatically opens the widget if it is closed.

If you are in the home menu view this will hide it and show the chat view, in case you are already in chat view, it will do nothing.

/**
 * Hide Home Menu 
 * @return {void} Promise response
 */
 
widgetInstance.hideHomeMenu();

If you are in the chat view this will show the home menu view. In case the home menu view is already showing, it will do nothing.

/**
 * Show Home Menu
 * @return {void} Promise response
 */
 
widgetInstance.showHomeMenu();

Contacts

Add an array of contacts to start new chats.

Contact Interface

interface Contact {
	id: string | number;
	avatar?: string;
	names?: string;
	color?: string;
	type?: string;
}

Set Contacts

Set contacts on the Widget instance

widgetInstance.setContacts([]);

Add Contacts

Attach contacts on the Widget instance

widgetInstance.addContacts([]);

Add Contact

widgetInstance.addContact({});

Contact List Loading

Sometimes, when adding contacts asynchronously, it is necessary to add a small loader to give feedback to users.

// Start Loading
widgetInstance.startLoading();

// Stop Loading
widgetInstance.stopLoading();

Room Contacts

These contacts can be added to an existing room.

Room Contact Interface

interface Contact {
	id: string | number;
	avatar?: string;
	names?: string;
	color?: string;
	type?: string;
}

Set Room Contacts

Set contacts on the Widget instance

widgetInstance.setContactsForRoom([]);

Add Room Contacts

Attach contacts on the Widget instance

widgetInstance.addRoomContacts([]);

Add Room Contact

widgetInstance.addRoomContact({});

Room Contact List Loading

Sometimes, when adding room contacts asynchronously, it is necessary to add a small loader to give feedback to users.

// Start Loading
widgetInstance.startLoadingForRoom();

// Stop Loading
widgetInstance.stopLoadingForRoom();

Input Management

Enable or Disable input options in the widget.

Disable Input Options

// disable the text input, plus button(document, image and location) and 
// microphone button.

widgetInstance.disableInputs();

Enable Input Options

// enable the text input, plus button(document, image and location) and 
// microphone button.

widgetInstance.enableInputs();

Add Member

Add a contact to an existing room.

/**
 * @typedef ApiResponse
 * @property {string[]} message Response message
 * @property {boolean} status Response status boolean
 * @property {string} statusMessage  Response status message
 */
 
/**
 * Add member
 * @param {Contact} contact object
 * @param {string} roomId Id of the room
 * @return {Promise<ApiResponse | string>} Promise response
 */
widgetInstance.addMember("<contact>", "<roomId>");

/**
 * Add member
 * @param {string} id Id of the user
 * @param {string} roomId Id of the room
 * @return {Promise<ApiResponse | string>} Promise response
 */
widgetInstance.addMember("<id>", "<roomId>");

Add Members

Add a list of contacts to an existing room.

/**
 * @typedef ApiResponse
 * @property {string[]} message Response message
 * @property {boolean} status Response status boolean
 * @property {string} statusMessage  Response status message
 */
 
/**
 * Add members
 * @param {Contact} contact object
 * @param {string} roomId Id of the room
 * @return {Promise<ApiResponse | string>} Promise response
 */
widgetInstance.addMembers(
  "<roomId>",
  [ 
    { 
      referenceId: "<someId1>", 
      names: "<someName1>",
      memberType: "Client" | "Operator" // Optional @default "Client"
    }, 
    { 
      referenceId: "<someId2>", 
      names: "<someName2"> 
    },
    ...,
    { 
      referenceId: "<someIdN>", 
      names: "<someNameN"> 
    }
  ]
);

Get Messages

Returns the message history of a given room, in a defined number and counted from a certain message within that room.

The argument of the getMessages() function is an object with the following keys:

roomId: Is a mandatory key with a value of type “string”, that corresponds to the ID of the room from which messages will be fetched.
limit: Is an optional key with a value of type “number”, that corresponds to the number of messages to be fetched. If not set, the “getMessages” function will take the default value of 20, and therefore it will bring 20 messages.
id: Is an optional key with a value of type “string” or “number”, that corresponds to the message ID from which a number of messages determined by the "limit" parameter will be fetched. If not set, the “getMessages” function will take the default value of null, and therefore it will bring the last sent messages, according to the established “limit”.

/**
* @param {GetMessages} [params]
* @returns {Promise<Message[]>}
**/

widgetInstance.getMessages (
   {
      roomId: "<someStringValue>",
      id?: "<someStringOrNumberValue>",
      limit?: <someNumberValue>,
   }
);

Send Message

The sendMessage() function is the that responsible for sending messages in Widget. You can send the following types of messages:

TextMessage
ImageMessage
AudioMessage
VideoMessage
DocumentMessage
LocationMessage
PostbackMessage
EventMessage

The message to be sent is an object that will have base keys, shared by all message types, and additional keys, which will depend on the type of message being sent.

Base Message Interface

interface BaseMessage {
    id: string | number;
    roomId: string;
    senderId: string;
    createdAt: string;
    timestamp: number;
    by: 'user' | 'bot' | 'operator' | 'company' | 'client';
    type: 'TEXT' | 'IMAGE' | 'AUDIO' | 'FILE' | 'DOCUMENT' | 'LOCATION' | 'POSTBACK' | 'EVENT' | 'VIDEO';
    status: 'CREATED' | 'DELIVERED' | 'FAILED' | 'DELIVERED_CHANNEL' | 'DELIVERED_USER';
    senderNames?: string;
    options?: {
        type: string;
        title: string;
        payload: Record<string, any>;
        order: number;
        url?: string;
    };
    QuickReplies?: {
        title: string;
        payload: Record<string, any>;
        contentType: string;
        imageUrl: string;
        url?: string;
        repliable?: string;
        type?: string;
    }; 
}

Text Message Interface

interface TextBaseMessage {
    text: string;
    readonly type: 'TEXT';
}

Image Message Interface

interface ImageBaseMessage {
    mediaUrl: string;
    caption?: string;
    readonly type: 'IMAGE';
}

Audio Message Interface

export interface AudioBaseMessage {
    mediaUrl: string;
    readonly type: 'AUDIO';
}

Video Message Interface

interface VideoBaseMessage {
    mediaUrl: string;
    caption?: string;
    readonly type: 'VIDEO';
}

Document Message Interface

interface DocumentBaseMessage {
    mediaUrl: string;
    caption?: string;
    readonly type: 'DOCUMENT';
}

Location Message Interface

interface LocationBaseMessage {
    lat: string;
    lng: string;
    readonly type: 'LOCATION';
}

Postback Message Interface

interface PostbackMessage {
    text: string;
    payload: Record<string, any>;
    readonly type: 'POSTBACK';
}

Event Message Interface

interface EventMessage {
    slug: string;
    description: string;
    eventPayload: Record<string, string>;
    readonly type: 'EVENT';
}

Example of use: Text message

/**
* @param {SendMessage} [params]
* @returns {Promise<Message>}
**/

widgetInstance.sendMessage (
    {
        "id": "<someStringOrNumberValue>",
        "roomId": "<someStringValue>",
        "senderId": "<someStringValue>",
        "createdAt": "<someStringValue>",
        "timestamp": <someNumberValue>,
        "by": "user",
        "type": "TEXT",
        "status": "CREATED".
        "text": "<textMessageToBeSent>"
    }
)

PreviousUsing a Headless Widget NextGet Messages

Last updated 1 year ago

Open Widget

Close Widget

Enable Widget