Webim Cordova Plugin

Webim Cordova Plugin is the free software for integrating Webim chat functionality into mobile apps developed using the Apache Cordova framework.

Table of contents

Setting up

Methods

method init

method requestDialog

method getMessagesHistory

method typingMessage

method sendMessage

method editMessage

method deleteMessage

method replyMessage

method sendFile

method sendKeyboardRequest

method sendSurveyAnswer

method cancelSurvey

method onMessage

method onDeletedMessage

method onFile

method onTyping

method onConfirm

method onDialog

method onBan

method onSurvey

method onNextQuestion

method onSurveyCancel

method onChatState

method rateOperator

method rateOperatorWithNote

method showRateOperatorWindow

method sendDialogToEmailAddress

method onUnreadByVisitorMessageCount

method getUnreadByVisitorMessageCount

method setChatRead

method getShowEmailButton

method onLogging

method close

Objects

Message

DialogState

Employee

Survey

SurveyConfig

SurveyCurrentQuestionInfo

SurveyQuestion

Keyboard

KeyboardButton

KeyboardRequest

KeyboardResponse

Setting up

The plugin can be installed from git repository.

Example: cordova plugin add https://github.com/webim/webim-cordova-plugin.git

Methods

For further reference about development of plugins for Apache Cordova, please consult the official Plugin Development Guide .

method webimsdk.init(param, successCallback, errorCallback)

Webim session initialization. Another plugin methods don't work without session initialization.

Parameter param is JSON with:

accountName field — Webim service account name. Specify either full server base URL (e. g., "https://demo.webim.ru") or just account slug (e. g., "demo"). Type — String.

location field — String-typed location name. Usually default available location names are "mobile" and "default". To create any other one you can contact service support. Field is mandatory.

pushSystem field — String-typed push system ("fcm" or "hpk") for push notification receiving.

pushToken field — String-typed push token for push notification receiving.

visitorFields field — visitor authorization data. Without this method calling a visitor is anonymous, with randomly generated ID. This ID is saved inside app UserDefaults and can be lost (e.g. when app is uninstalled), thereby message history is lost too. Authorized visitor data are saved by server and available with any device. More information on Webim web site. Type — JSON. Field is mandatory.

storeHistoryLocally field. By default session doesn't save message history inside SQLite DB file. To activate this functionality you can use this method with true value. Type — Boolean.

closeWithClearVisitorData field. If this parameter is true, session will close with deleting visitor data. Type — Boolean.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.requestDialog(successCallback, errorCallback)

Start chat. When a user sends a message, the chat begins automatically, so calling the method is optional.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.getMessagesHistory(limit, offset, successCallback, errorCallback)

Requests the messages above in history.

limit parameter — method returns not more than limit of messages. Type — Int.

offset parameter — histrory offset. Type — Int, 0 value means last message in history, another value returns next messages after previous method running.

Function successCallback(messages) is executed when the method is successfully completed. messages parameter contains messages array. See Message

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.typingMessage(message, successCallback, errorCallback)

This method must be called whenever there is a change of the input field of a message transferring current content of a message as a parameter.

When there's multiple calls of this method occurred, draft message is sending to service one time per second.

message parameter — draft message Type — String. When empty string value passed it means that visitor stopped to type a message or deleted it.

Function successCallback(text) is executed when the method is successfully completed. text parameter contains draft message.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.sendMessage(message, successCallback, errorCallback)

Send message.

message parameter — sending message. Type — String. Max message length — 32000 symbols.

Function successCallback(message) is executed when the method is successfully completed. message parameter contains message, type — Message.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.editMessage(newText, message, successCallback, errorCallback)

Edit message. Message can be edited if its parameter canBeEdited is true.

newText parameter — new message text. Type — String. Max message length — 32000 symbols.

message parameter — edited message. Type — Message. JSON with message parameters.

Function successCallback(message) is executed when the method is successfully completed. message parameter contains message, type — Message.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.deleteMessage(message, successCallback, errorCallback)

Delete message. Message can be deleted if its parameter canBeEdited is true.

message parameter — deleted message. Type —Message. JSON with message parameters.

Function successCallback(message) is executed when the method is successfully completed. message parameter contains message, type — Message.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.replyMessage(message, repliedMessage, successCallback, errorCallback)

Reply message. Message can be replied if its parameter canBeReplied is true.

message parameter — sending message. Type — String. Max message length — 32000 symbols.

repliedMessage parameter — replied message. Type — Message. JSON with message parameters.

Function successCallback(message) is executed when the method is successfully completed. message parameter contains message, type — Message.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.sendFile(filePath, successCallback, errorCallback)

Sends a file message.

filePath parameter — file path.

Function successCallback(id) is executed when the method is successfully completed. id parameter contains file message ID, type — String.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.sendKeyboardRequest(requestMessageCurrentChatId, buttonId, successCallback, errorCallback)

Sends a file keyboard request.

requestMessageCurrentChatId parameter — message current chat id.

buttonID parameter — selected button id.

Function successCallback(id) is executed when the method is successfully completed. id parameter contains file message ID, type — String.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.sendSurveyAnswer(surveyAnswer, successCallback, errorCallback)

Sends a answer to current question.

surveyAnswer parameter — survey answer.

Function successCallback(jsonString) is executed when the method is successfully completed.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.surveyCancel(successCallback, errorCallback)

Close the survey.

Function successCallback(jsonString) is executed when the method is successfully completed.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.onMessage(successCallback, errorCallback)

Success callback called when added a new operator message, a new system message or sending visitor message.

Function successCallback(message) is executed when the method is successfully completed. message parameter contains message, type — Message.

Function errorCallback() will never be executed.

method webimsdk.onDeletedMessage(successCallback, errorCallback)

Success callback called when deleted a message.

Function successCallback(message) is executed when the method is successfully completed. message parameter contains message, type — Message.

Function errorCallback() will never be executed.

method webimsdk.onFile(successCallback, errorCallback)

Success callback called when added a new file message.

Function successCallback(message) is executed when the method is successfully completed. message parameter contains message, type — Message.

Function errorCallback() will never be executed.

method webimsdk.onTyping(successCallback, errorCallback)

Success callback called when operator types message.

Function successCallback(message) is executed when the method is successfully completed. message parameter always contains empty string.

Function errorCallback() will never be executed.

method webimsdk.onConfirm(successCallback, errorCallback)

Success callback called when visitor message received by the server.

Function successCallback(id) is executed when the method is successfully completed. id parameter contains file message ID, type — String.

Function errorCallback() will never be executed.

method webimsdk.onDialog(successCallback, errorCallback)

Success callback called when operator changed in the chat.

Function successCallback(dialogState) is executed when the method is successfully completed. dialogState parameter contains new dialog state, type — DialogState.

Function errorCallback() will never be executed.

method webimsdk.onBan(successCallback, errorCallback)

Success callback called when the visitor is baned.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback() will never be executed.

method webimsdk.onSurvey(successCallback, errorCallback)

Success callback called when the visitor can answer to survey.

Function successCallback(survey) is executed when the method is successfully completed. survey parameter contains Survey object.

Function errorCallback() will never be executed.

method webimsdk.onNextQuestion(successCallback, errorCallback)

Success callback called when the visitor can answer to this question.

Function successCallback(surveyQuestion) is executed when the method is successfully completed. surveyQuestion parameter contains SurveyQuestion object.

Function errorCallback() will never be executed.

method webimsdk.onSurveyCancel(successCallback, errorCallback)

Success callback called when the survey is canceled.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback() will never be executed.

method webimsdk.onChatState(successCallback, errorCallback)

Success callback called when chat state was changed.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains chatState field with chat state name: unknown, none, queue, chatting, chattingWithRobot, deleted, routing, invitation, closedByVisitor or closedByOperator.

Function errorCallback() will never be executed.

method webimsdk.rateOperator(id, rating, successCallback, errorCallback)

Rates an operator.

id parameter — operator id. Type — String.

rating parameter — a number in range (1...5) that represents an operator rating. If the number is out of range, rating will not be sent to a server. Type — Int.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.rateOperatorWithNote(id, rating, note, successCallback, errorCallback)

Rates an operator.

id parameter — operator id. Type — String.

rating parameter — a number in range (1...5) that represents an operator rating. If the number is out of range, rating will not be sent to a server. Type — Int.

note parameter — some commentary. Type — String.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.showRateOperatorWindow(successCallback, errorCallback)

Success callback called when the visitor should rate an operator at the end of chat.

Function successCallback() is executed when the method is successfully completed.

Function errorCallback() will never be executed.

method webimsdk.sendDialogToEmailAddress(emailAddress, successCallback, errorCallback)

Rates an operator.

emailAddress parameter — send dialog to this email address. Type — String.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.onUnreadByVisitorMessage(successCallback, errorCallback)

Success callback called when operator send new message.

Function successCallback(unreadByVisitorMessageCount) is executed when value of unread by visitor message count changed. unreadByVisitorMessageCount parameter contains unread by visitor message count, type — Int.

Function errorCallback() will never be executed.

method webimsdk.getUnreadByVisitorMessage(successCallback, errorCallback)

Success callback returns unread by visitor message count.

Function successCallback(unreadByVisitorMessageCount) returns value of unread by visitor message count. unreadByVisitorMessageCount parameter contains unread by visitor message count, type — Int.

Function errorCallback() will never be executed.

method webimsdk.setChatRead(successCallback, errorCallback)

All messages will be read by visitor.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.getShowEmailButton(successCallback, errorCallback)

Method returns true if app should show send chat to email button.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains showEmailButton field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

method webimsdk.onLogging(successCallback, errorCallback)

Success callback called when new log entry appears.

Function successCallback(log) returns new log entry appears. log parameter contains new log entry, type — String.

Function errorCallback() will never be executed.

method webimsdk.close(successCallback, errorCallback)

Close session and stop session network activity.

Function successCallback(jsonString) is executed when the method is successfully completed. jsonString parameter contains result field with execution method completion information.

Function errorCallback(jsonString) is executed when the method is unsuccessfully completed. jsonString parameter contains result field with execution method completion information.

Objects

Message

Message information.

id field— message ID. Type — String.

text field — message text. Type — String.

url field — file URL. No field if message isn't file message. Type — String.

fileSize field — file size. No field if message isn't file message. Type — long.

contentType field — file content type. No field if message isn't file message. Type — String.

timestamp field — sending time in ms. Type — String.

sender field — message sender name. No field if message is system message. Type — String.

operator field — operator information. No field if message isn't operator message. Type — Employee.

keyboard field — keyboard information. Type — Keyboard.

isFirst field — true if message is the first message in current chat. Type — Boolean.

isReadByOperator field — true if message is read by operator. Type — Boolean.

canEdited field — true if message is can be edited and deleted. Type — Boolean.

canBeReplied field — true if message is can be replied. Type — Boolean.

quote field — quote information. Type — Quote.

extraText field — extra text in broadcast. Type — String.

DialogState

Dialog state info. See method onDialog.

employee field — new operator in current chat. Type — Employee.

Employee

Operator information.

id field — operator ID. Type — String.

firstname field — operator first name. Type — String.

avatar field — operator avatar URL. Type — String.

Survey

Survey information.

id field — survey ID. Type — String.

config field — survey config. Type — SurveyConfig.

currentQuestionInfo field — information about current question in survey URL. Type — SurveyCurrentQuestionInfo.

SurveyConfig

Survey config information.

id field — survey config ID. Type — String.

version field — survey config version. Type — String.

SurveyCurrentQuestionInfo

Survey current question information.

formId field — survey current question form ID. Type — String.

questionId field — survey current question ID. Type — String.

SurveyQuestion

Survey question information.

type field — survey question type. Type can be "stars", "radio", "comment". Type — String.

text field — survey question text. Type — String.

Keyboard

Keyboard information.

state field — keyboard state. Type can be "pending" (all buttons aren't selected), "completed" (keyboard has selected button), "canceled" (keyboard is canceled without selected button). Type — String.

buttons field contains buttons array. See KeyboardButton.

keyboardResponse field contains information about selected button. Type — KeyboardResponse.

KeyboardButton

Keyboard button information.

text field — text on button. Type — String.

id field — button id. Type — String.

KeyboardRequest

Keyboard request information.

messageID field — id of message with keyboard. Type — String.

button field — selected button. Type — KeyboardButton.

KeyboardRequest

Keyboard request information.

buttonID field — selected button id. Type — String.

messageID field — id of message with keyboard. Type — String.

Quote

Quote information.

state field — quote state. Type — String. Can be filled, pending and notFound.

senderName field — name of message author. No field if message isn't operator message. Type — String.

text field — quote text. Type — String.

timestamp field — sending time in ms. Type — String.

authorID field — author id. No field if message isn't operator message. Type — String.

id field — replied message id. Type — String.

url field — file URL. No field if replied message isn't file message. Type — String.