lakeel-messenger-apis v0.1.19

Lakeel Messenger APIs

Table of Contents

• Getting Started
  • Install
• Usage
  • Send/Receive messages
  • Send message with buttons
  • Send carousel message
  • File
  • Get talks
  • Presence
  • Room
  • User
  • Csv
  • Movie
  • Browserify
• Error
• Example

Getting Started

This package is built for Lakeel Messenger API ver1.0 in TypeScript. Any questions regarding set up and API management, please visit here. Detailed documentation is also up on the website above.

This API simplifies the process of setting up headers and string manipulations required for executing Lakeel Messenger API. Authentication set up is only needed once, and the type checks are featured to reduce any invalid requests to the server. Response type is not modified but passed as Promise object for easier error handling.

Install

npm

npm install --save lakeel-messenger-apis

And start using the API:

const lakeel = require("lakeel-messenger-apis");

const messenger = new lakeel.LM("apikey", "secretkey", "example.hostname.com");

Usage

JID is a unique identification code given to every user and room. Most functions require to input a JID and invalid code will result in an error.

All functions use the asynchronous method to process data and return value of these functions are in Promise object. Use then() and catch() to process their callbacks.

Send/Receive messages

Send

This function will send a message to the specified JID. If the API account is a bot, it must already exist in the room to post messages. Otherwise, use a user API to send messages to rooms without joining.

The API account status will change to online during the process.

messenger.sendMessage("target_JID", "Hello World!");

Request

Response

Receive

This function will download sent messages between an API account and a target user or room. The messages are marked as read once downloaded.

Optional settings
force: False (default) will download new messages since the last time this function is called. Setting it True will result in downloading any past 1000 messages.
include: False (default) will not download messages sent by this account.

messenger.receiveMessage("target_JID", true, false);

Request

Response

Message Object

User Object

Organization Object

File Object

Send message with buttons

User API account will be required to join the room before posting messages. Bot API account can send messages to rooms without joining. However, the bot will join the room after sending a message.

The API account status will change to online during the process.

An array of button objects are required. Use the button() function to create the objects.

let button1 = lakeel.button("message", "Clicked!", "Button One", "success");
...

messenger.sendButton("target_JID", "It's a message!", "horizontal", [button1, button2...]);

Request

Response

Button Object

Send carousel message

Send a carousel message to a specified user or room.

User API account will be required to join the room before posting messages. Bot API account can send messages to rooms without joining. However, the bot will join the room after sending a message.

The API account status will change to online during the process.

An array of panel objects are required. Use the panel() function to create the objects. The panel itself will act as a button, and its behaviour is defined by a panel button object using panelButton(). Within the panel, custom buttons can be placed using an array of the button objects.

let button1 = lakeel.button("message", "Button Clicked!", "Button One");
var panelButton1 = lakeel.panelButton("message", "Panel Clicked!");
var panel = lakeel.panel("It's a panel!", panelButton1, [button1...]);

let buttonMsg = messenger.sendCarousel("target_JID", "It's a message!", [panel]);

Request

Response

Panel Object

Panel Button Object

Button Object

File

There are three ways to send a file using this API. Local file path method , binary method and base64 method.

Send file method #1 FILE PATH

Send a file to a specified user or room.

User API account will be required to join the room before sending files. Bot API account can send files to rooms without joining. However, the bot will join the room after sending a file.

The API account status will change to online during the process.

The file path must include the target file name and its file extension.

messenger.sendFileByPath("target_JID", "file_path/abc.jpg");

Request

Response

Send file method #2 Row

Send a file to a specified user or room.

User API account will be required to join the room before sending files. Bot API account can send files to rooms without joining. However, the bot will join the room after sending a file.

The API account status will change to online during the process.

const imgData = fs.readFilesync("file_path/abc.jpg");

messenger.sendFileByRow("target_JID", imgData, "abc.jpg");

Request

Response

Send file method #3 base64 encoded string

Send a file to a specified user or room.

User API account will be required to join the room before sending files. Bot API account can send files to rooms without joining. However, the bot will join the room after sending a file.

The API account status will change to online during the process.

const imgDataStr = "img_encoded_in_base64_string";

messenger.sendFileByBase64("target_JID", imgDataStr, "abc.jpg");

Request

Response

Receive file

Download a file sent in a chat using File ID.

File ID can be obtained from receiveMessage() function or from the sendFile function's receipt. This function will return a File object containing a filename and binary data.

let receive = messenger.receiveFile("target_JID", "file_id");

Request

Response

Make File

Input the response of receiveFile() function and an output file path. This will rebuild the file from downloaded binary data.

messenger.makeFile("./output", receive);

Request

Response

Get talks

Get your own talk. (Up to 1000 cases)

If the force parameter is not specified or set to false, only the talks updated since the last call of this function is downloaded.

messenger.getTalks(false);

Request

Response

Talk Object

Presence

Get a presence of a specified user.

messenger.getPresence("target_JID");

Request

Response

Room

Get room

Get information about a specified room.

messenger.getRoom("target_roomJID");

Request

Response

Owner Object

User Object

Create room

Use to create a room with specified owner and users.

Use makeOwner() and makeUser() to create Owner and User objects.

※ Do not include the owner in the User array

let owner = lakeel.makeOwner("owner_JID");
let user1 = lakeel.makeUser("user_JID");

messenger.createRoom(owner, [user1...], "Room One", true);

Request

Response

User Object

Edit room

Edit an existing room.

There are two statuses for User object. Set as "enter" when adding a new user and "leave" when withdrawing an existing member.
When changing the owner, be sure to designate the member whose status is "enter".

Use makeOwner() and makeUser() to create Owner and User objects.

Previously makeUser() did not require a user status when creating a room. However, user status is required when editing room.

let owner = lakeel.makeOwner("owner_JID");
let user1 = lakeel.makeUser("user_JID", "enter");
let user2 = lakeel.makeUser("user_JID", "leave");

let room = messenger.editRoom("target_roomJID", owner, [user1, user2], "New Name", true);

Request

Response

User Object

User

Get user info

Get user info by specifying single or multiple conditions. Use UserSearchCondition class to create condition object.

const condition = new lakeel.UserSearchCondition();
condition.setIsAdmin(true)
            .setLastAccessAtAfter("2020-09-01T00:00:00.000Z")
            .setLastAccessAtBefore("2020-09-09T00:00:00.000Z")
            .setPage(2)
            .setPerPage(5);

messenger.getUsers(condition);

If you omit to pass in condition, this method will return the result with pagination of page 1 and perPage 1000.

messenger.getUsers();

Request(UserSearchCondition object)

※1 'jo' will hit 'joe', 'john', 'johnson', 'jordan'. ※2 All conditions are optional. If you omit them all, you get first 1000 user data out of all data.

Response

User Data Object

Affiliation Info Object

Account lock status

Update an account lock status of a specified user.

messenger.changeLock("target_JID", true);

Request

Response

Change password

Change a password of a specified user.

messenger.changePassword("target_JID", "newpass", true);

Request

Response

Reset password

Reset an existing password of a specified user to a character string created with random number.

messenger.resetPassword("target_JID");

Request

Response

Csv

There are two ways of uploading csv data. One is updating the whole DB data with uploaded csv data(uploadCsvAll) and another is only updating DB data with differential one(uploadCsvDiff).

Suppose we have user data A and B on DB. A's id is 1 and B's 2. You have your own user csv file, in which there's only A's data and it says its id is 3. Here you want to update user A's id from 1 to 3.

This time, you can't use uploadCsvAll because it'll result in losing B's data and not being able to keep data consistency. uploadCsvAll replace the whole DB data with uploaded one. But you can use uploadCsvDiff instead. It only updates A's data and B's doesn't change at all.

Upload Csv (All)

Select file paths and their encodings.

messenger.uploadCsvAll("some/organization/csv/file/path", "utf8", "some/user/csv/file/path", "utf8", "some/affiliation/csv/path", "utf8", "", "")

Request

※1 You have to select at least one file. ※2 If you select a file, you must also specify its encoding. If not, just leave it an empty string.

Response

Upload Csv (Diff)

Select file paths and their encodings.

messenger.uploadCsvDiff("some/organization/csv/file/path", "utf8", "some/user/csv/file/path", "utf8", "some/affiliation/csv/path", "utf8", "", "")

Request

※1 You have to select at least one file. ※2 If you select a file, you must also specify its encoding. If not, just leave it an empty string.

Response

Movie

Send movie

Send a movie to a specified user or room.

User API account will be required to join the room before sending a movie. Bot API account can send a movie to rooms without joining. However, the bot will join the room after sending a file.

The API account status will change to online during the process.

The file path must include the target file name and its file extension.

messenger.sendMovie("target_JID", "some/file/path");

Request

Response

Browserify

How to use it in HTML and web page using Browserify

Install Browserify globally

npm install -g browserify

Create an empty project and install Lakeel Messenger APIs.

Make sure "lakeel-messenger-apis" exists in your node_module folder.

Create a main.js at the project directory.

//main.js
'use strict';
console.log("Module Loaded");
const lakeel = require('lakeel-messenger-apis');

window.lakeel = lakeel;

Save and run

browserify main.js -o bundle.js

Now take the bundle.js and place it in your web folder. Import and done.

Sample

//index.html
<script type="text/javascript" src="bundle.js"></script>
<script type="text/javascript">
    const apiKey = "api";
    const secretKey = "secret";
    const hostname = "example.hostname.com";
    const messenger = new lakeel.LM(apiKey, secretKey, hostname);
    const jid ="target@example.hostname.com";
</script>

<form>
<h1>Message test</h1><br>
<input type="text" value="Hi" id="msg"><br>
<input type="submit" onclick="messenger.sendMessage(jid,document.getElementById('msg').value)">
</form>

Error handling

Errors can be caught using catch().

Sample

Failed to send a message.

const send = messenger.sendMessage("target_JID", "Hi!")

.then((success) => console.log("Success"))
.catch((err) => console.log(err));

Error response is in the following format

{
    "error": {
        "code": 400,
        "message": "Missing parameters.",
        "function": "sendMessage",
        "err": Error
    }
}

{
    "error": {
        "code": 400,
        "message": "Posted data has problems.",
        "invalidData": {
            "users": [
                {
                    "jid": "userxxx@example.lakeel.com",
                    "cause": "Non-existent user."
                },
                {
                    "jid": "useryyy@example.lakeel.com",
                    "cause": "Duplicated user."
                }
            ]
        }
    }
}

Help

Bugs

Known bugs

• Error 503 page is returned when calling a receieveFile with an invalid file ID
• Editing room does not return room JID after a successful process

Example

What does it do?

• Sends an image
• Downloads the sent image
• Rebuilds the downloaded data to an output folder as an image

All using a Promise chain

const lakeel = require('lakeel-messenger-apis');

const apiKey = "api";
const secretKey = "secret";
const hostname = "example.hostname.com";
const img = fs.readFilesync("file_path/abc.jpg");
const messenger = new lakeel.LM(apiKey, secretKey, hostname);

const jid ="target@example.hostname.com";

//Send the file
messenger.sendFileByRow(jid, img, "abc.jpg")
.then((data) => {
    let fileId = data['fileId']; //Extract the file ID
    return messenger.receiveFile(jid, fileId); //Download the image
})
.then((result) => {
    //Rebuild the image to the output folder
    return messenger.makeFile("./output", result);
})
.finally(() => {
    console.log("Success :)");
})
.catch((err) => {
    console.log("Something went wrong :( " , err);
});

Author

Kamata Takashi, Ryoei Shimaura

License

ISC