API usage guide

1. Overview

YuWee JavaScript SDK is intended to be used by developers to integrate real-time communication in their existing platform with features like Audio-Video calls, Chat and screen sharing. The SDK is provided in the form of an easy-to-use JavaScript library YuWee.js which contains a set of functions and call-backs to facilitate integration.

_images/image1.png

Figure1: Overview of API integration

2. Setup Integration

2.1 Register your application with YuWee

User can sign up and register their application on the YuWee-integrate home page via following link: https://connect.yuwee.com/#/login

On registering, the user needs to verify their account via email. Once email is verified, the user waits for a confirmation mail from YuWee. After that developer can login to the developer panel and register their app(s) and obtain following credentials- client Id, App key and App secret which would be needed to connect to YuWee servers via the SDK.

At the developer panel, one needs to customise call email templates and add their own SMTP details (mandatory) from which call emails would be fired. Along with the SMTP credentials, developer also need to specify a base url of their site under Configure ->Email Configuration, needed for the email invite links. This is to make sure that the email invite links generated by YuWee should be redirected to developers site for their handling.

2.2 Setup and configure SDK

To use the YuWee Javascript SDK, the Application must include the following javascript files to their project:

● YuWee.js

● yConstants.js

● conferenceManager.js

● jquery.js

● socket.io

The SDK is basically a javascript library consisting of a set of APIs and callbacks. Most of these APIs are asynchronous and hence trigger callbacks on their completion. The SDK invokes the callbacks as a result of the events triggered by various actions such as ‘onIncomingCall’,’onCallRejected’, ‘onRemoteCallHangUp’, etc. These callbacks must be implemented by the application in order to handle necessary events.

2.3 Initialize YuWee client(yuwee)

YuWee is the core class to leverage the YuWee SDK. Instantiate the SDK class “YuWee” to get access to all the APIs and callbacks

yuWee = new YuWee ( );

This creates an instance of the SDK Class, which is then used to perform all other operations.

2.4 Set event handlers

There are several callback events that needs to be handled in the application which aims to utilise the capabilities of YuWee SDK. Developer can assign their handler functions to these event hooks via setHandler method of YuWee in the following way:

var myHandlers = {
		
	'onAccountCreateSuccess': $scope.accountCreateSuccess,
	'onAccountCreateFailure': $scope.accountCreateFailure,
	'onSessionCreateSuccess': $scope.sessionCreateSuccess,
	'onSessionCreateFailure': $scope.sessionCreateFailure,
	'onCallSetupFailed' : $scope.callSetupFailure,
	'onAllUsersOffline': $scope.allUsersOffline,
	'onAllUsersBusy': $scope.allUsersBusy,

	...
  
	};

yuWee.setHandlers(myHandlers);

Above code snippet defines various event handlers and registers them to the respective hook that is fired from within SDK. Whenever an event occurs within the library, the respective handler is called. In above code snippet, the left side contains the event name and the right side depicts the name of the handler function that binds to the event.

2.5 Set application credentials

yuWee.setAppCredentials(appId, appSecret, clientId);

Description & Usage

This API is used to set the Application credentials received after registering the application with YuWee in step 2.1. These credentials are used for the authentication purpose.

Parameters

Parameter name Type Mandatory Description
appId String Yes Application ID obtained from developer console
appSecret String Yes Application secret obtained from developer
clientId String Yes Client ID obtained from the developer console

2.6 Create/Register user

yuWee.createUser(name, email, password)

Description & Usage

This API is used to signup a new user in YuWee.

Note

For more security, These APIs can be called from server side as well. API to export the user list via CSV is also available for initial migration. Please request for “Server-side API” document for the same

Parameters

Parameter name Type Mandatory Description
name String Yes 3-30 chars limit
email String Yes Requires a valid email
password String Yes 6-20 chars limit

Call-back Events:

Event name Response data Description
onAccountCreateSuccess Success message This event is called when an account has been successfully created in YuWee
onAccountCreateFailure Error message This event is called when account creation fails for some reason

2.7 Create session via credentials

yuWee.createSessionViaCredentials(email, password, sessionExpirationTime)

Description & Usage

This API will create a new session for the user

Parameters

Parameter name Type Mandatory Description
email String Yes Valid email
password String Yes 6-20 chars limit
sessionExpirationTime String No Time after which the session should expire and hence renew. It should be provided in seconds. Renewal of session is handled internally by YuWee SDK

Call-back Events:

Event name Response data Description
onSessionCreateSuccess Success message, userinfo (user details and Access Token) This even is called when a session has been successfully created. The Callback handler will receive user information and access token to be used for other APIs authentication
onSessionCreateFailure Error message This even is called when session creation fails for some reason

2.8 Create Session Via Email Token

yuWee.createSessionViaToken ( inviteToken )

Description & Usage

This API is used to create session for a Callee who has responded to a call (accept/reject) via email. This scenario will be further revisited and explained in Answer a call via email

Parameters

Parameter name Type Description
inviteToken String Encrypted token with user info, call info and access token

Call-back Events:

Event name Response data Description
onInvitationExpired nil This event is fired when the call has already ended. A call is considered to be ended when at least one of the member has ended the call and no one is left in the room
onSessionCreateSuccess Success message, userinfo (user details, call details and access token) This even is called when a session has been successfully created. The Callback handler will receive user information, call information and access token to to be used for other APIs authentication and call setup
onSessionCreateFailure Error message This event is called when session creation fails for some reason

2.9 Initialise Session

yuWee.init ( yuWeeInitParam )

Description & Usage

This is the last step for setup. In this initialisation step, user’s information and authorisation token received from 2.7 or 2.8 needs to be passed to the YuWee library for internal API calls. When User logs in via createSessionByCredentials or createSessionByToken, these APIs provide “userInfo” that we need to initialise YuWee:

yuWeeInitParam.user = userInfo.user;
yuWeeInitParam.authToken = userInfo.auth_token;
yuWee.init(yuWeeInitParam);        

Call-back Events

Event name Response data Description
onInitialisationSuccess nil This event is triggered when the session has been successfully initialised

2.10 Refresh session (Client side)

yuWee.refreshSession()

Description & Usage

This API is used when the session is being managed at the client’s side, the existing access token has expired and a new access token is to be fetched.

Call-back events

Event name Response data Description
onSessionRefreshSuccess nil This event is triggered when the session has been successfully refreshed
onSessionRefreshFailure nil This event is triggered when the session failed to refresh

2.11 Refresh session (Server Side)

yuWee.reinit(newAccessToken, newRefreshToken)

Description and Usage

When the session is being managed at the server end using server side API, new tokens should only be requested at the server end only following the expirations of the tokens. The server side API responds with a renewed access token and a new refresh token. Once the new tokens have been received by the client, it needs to refresh the session and also the server connection with the new tokens. This is done with this API.

2.12 Logout/Destroy session

yuWee.logout()

This API will destroy user’s current session and also disconnects the user from the YuWee server

3. Audio-Video Call

3.1 Setup Call

yuWee.setupCall(callParams)

Description

This API is used to setup a call. It takes a JSON parameter in the following format:

Usage of API

  1. Direct call using email
 callParams = 
{
	isGroup: false,   
    	inviteeEmail: “ronny@yuwee.com,
    	inviteeName: “Ronny”,
    	invitationMessage: “Hi Ronny, Lets have a call”,
    	callType: “video”
};

yuWee.setupCall(callParams);
  1. Group call using emails
callParams = 
{
    isGroup: true,   
    inviteeEmails: “ronny@yuwee.com, sunny@yuwee.com”,
    groupName: “New Group”,
    invitationMessage: “Hi Ronny and Sunny, Lets have a Group call”,
    callType: “video”
};
  
yuWee.setupCall(callParams);
  1. Direct/Group call using roomId

Using this API, a call can be initiated using the already generated roomID. RoomId can either be fetched from an existing room/conversation from the chat list or via the api Create Chat Room API as described later under chat section

callParams = 
{
    isGroup: true,   
    roomId: roomId,
    groupName: “New Group”,
    invitationMessage: “Hi Ronny and Sunny, Lets have a Group call”,
    callType: “video”
};
  
yuWee.setupCall(callParams);

Note

Advantage of using roomId over emails in group calls is that when emails are used, a new room will be created every time a call is made even for the same set of users. Hence roomId should be used when calling over an existing room or group of users

Parameters

Key Type Description
callType String “audio” or “video” based on the type of call that needs to be started
invitationMessage String Optional
inviteeEmail(s) String Email of the participants
inviteeName String Optional
isGroup boolean true/false
groupName String Mandatory for group call
roomId String Fetched from ChatList or FetchChatRoom API

Call-back Events

Event name Response data Description
onBrowserIncompatible nil This event is triggered when caller’s browser is incompatible and doesn’t support YuWee. For details on the supported OS and browsers check the functional documentation of YuWee-integrate
onAllUsersOffline nil This event is triggered if none of the callees is online. In this case, a mail is triggered for the callees with links to join the call. The callee can click on the email link so as to re-initiate the call to the caller. The caller gets a call notification in its screen if he is not ready on the call.
onAllUsersBusy nil This event is triggered in case all the Callees are busy on another call and hence unavailable
onReadyToInitiateCall callType, list of busy users The event is triggered when at least one callee is online and available. By now the available callees have already received a call notification via a callback. At this point, the caller can be taken to the next step of call connection

3.2 Capture Local Stream

yuWee.getMediaStream(callType)

Description & Usage

This method will initialise and start capturing media (Audio/Video) from the media device (webcam and/or Mic).

Call-back Events:

Event name Response data Description
onLocalStreamReceived localStream This event is called when a session has been successfully created. The call-back handler will receive user information and accesss token to be used for other APIs authentication
onStreamRequestDowngrade Downgrade Message

By default the video stream captured is of HD quality. In case of incompatible hardware, one or many of the following can happen: 1. If webcam is non-HD, this event is received and the request automatically fall backs to normal SD type. If SD stream is successfully captured “onLocalStreamReceived” event is fired which receives the SD stream(video+audio) as a parameter

2. If webcam is missing, this event is fired and the request fallbacks to an “Audio-only” call. If audio-stream is successfully captured, “onLocalStreamReceived” is fired which received the Audio-stream as the parameter.

3. If both WebCam and microphone are missing, “onStreamCaptureFailure” is called. The call can be terminated on receiving this event.

onStreamCaptureFailure Error message This event is called when stream capture fails for some hardware compatibility issues

3.3 Manage Local Stream

yuWee.attachMediaStream(stream)

Description & Usage

Now, the stream received in the callback handler in 3.2 needs to be rendered to an HTML Video or Audio element. This API facilitates the same

gotLocalStream = function(myStream)
{
	var bigVideo = document.querySelector('#bigVideo');
	yuWee.attachMediaStream(bigVideo,myStream);
}

3.4 Register in Room

yuWee.registerInRoom()

Description & Usage

Once local stream has been managed via the previous step, the caller needs to register in the room via this API. Once registered, the call will be idle and wait for the call to be answered by the callee or other participants.

Call-back Events:

Event name Response Data Description
onRoomRegistrationSuccess Success message This event is fired when registration is successfull
onRoomRegistrationFailure Error message This event is fired when registration to room fails
onCallAccepted Nil This event is called at caller’s side, when a callee has accepted the call via API 2.2.5
onRemoteStreamReceived Remote Stream Once a connection has been established, this event is fired to each user and they will receive the remote stream as a callback parameter for this event

3.5 Answer an incoming call- I(Direct call)

Whenever there is an incoming call, ‘onIncomingCall’ event is triggered at the callee’s end. In the handler of this event, user can perform following 2 actions:

Option 1 - Accept a Call

yuWee.acceptCall(callType)

Description & Usage:

Callee can accept an incoming call using this API

Parameters

Parameter name Type Description
callType String “audio” or “video” based on the type of call that needs to be started

Post accepting the call using above API, user needs to follow the steps from 3.2 to 3.4 (getMediaStream, attachMediaStream and registerInRoom). Once registered a room, a connection is established between all the call participants via YuWee servers and all will start recieving the streams of each other if it is a 1-to-1 call, or a mixed stream if it is a group call. The received remote stream can be attached to the main video element via attachMediaStream as discussed earlier. The local stream can be attached to a smaller video element.

gotRemoteStream = function(remoteStream)
{
	var bigVideo = document.querySelector('#bigVideo');
	var smallVideo = document.querySelector('#smallVideo');
	yuWee.attachMediaStream(bigVideo, remoteStream);
	yuWee.attachMediaStream(smallVideo, localStream);
}

Call-back Events:

Event name Response data Description
onRoomRegistrationSuccess Success Message This event is fired when registration to room is successful
onVideoRoomRegistrationFailure Error message This event is fired when registration to room fails
onCallAccepted nil This event is called at caller’s side, when a callee has accepted the call via above API
onRemoteStreamReceived Remote stream Once a connection has been established, this event is fired to each user and they will receive the remote stream as a callBack parameter of this event

Option 2 - Reject A Call

yuWee.rejectIncomingCall()

Callee can reject an incoming call using above API

Call-back Events:

Event name Response data Description
onCallRejected userId of rejector This event is called once the call is rejected by any of the callee. userId of the rejector is received as the callback parameter. The caller can choose to drop the call and redirect to dashboard if needed.

3.6 Answer a call- II (via email)

When a Callee clicks on an email call invite which contains the encrypted token having the required user, call information and authorisation token embedded, following thing happens in sequence:

● Callee is supposed to be taken to the dashboard of the web application.

● Since call-page is common for direct caller, callee or email callee, we need to have a check if the flow needed is for an email call or not. The same can be done via following API. It checks the url to detect the same.

yuWee.checkIfCallViaEmailInvite(url)

Parameters

Parameter name Type Description
url String

This url can either be the dashboard url if its a direct incoming call, or the url of the email invite sent to callee via email. We have to check for the later, to decide the flow

Ideally pass the value of window.location.href of the page which opens up on clicking the email

Return

Key Type Description
inInvite boolean true: url corresponds to the call accepted invite email. false: url doesn’t correspond to call accepted via invite email
inviteToken string This is an encrypted token, containing userinfo of self, callinfo and accessToken. These values are deciphered from the encrypted string via another API described below: createSessionViaToken()

Once inviteToken is received and a Session has been created via createSessionViaToken(), and if the the callee joining via email is the first user to join the call, i.e. the call hasn’t started yet and is not ongoing, every other participants will get a “onIncomingCall” Event to join the call. In other case, the callee will simply join an ongoing call. In both the case, the callee follows the flow described in Flow 3 in the Annexure-1. All the concerned API have already been covered earlier.

3.7 Pause/Un-Pause Video Stream

yuWee.toggleVideoPause ()

Description & Usage:

A call participant can choose whether he wants his video stream to be shown to other participants or not. This can be done by toggling the Video stream to pause or unpause via this API. For a Video Call, Video stream is by default in unpaused state, whereas in Audio call, It is in paused state. Calling the API will toggle the state.

Call-back Events:

Event name Response data Description
onVideoToggle isVideoPaused(boolean) This event is received when participant’s own video has been toggled successfully. Video stream state is also received as callback parameter
onRemoteVideoToggle {isVideoPaused(boolean), email(String)} This event is received when some other participant has toggled his video stream. Video stream state and the email of the participant is also received as callback parameter

3.8 Mute/Unmute Audio Stream

yuWee.toggleAudioMute ()

Description & Usage:

A call participant can choose whether he wants to share his audio stream with other participants or not. This can be done by toggling the Audio stream to mute or unmute state via this API. For both Audio and Video Call, Audio stream is by default in unpaused state. Calling the API will toggle the state.

Callback events

Event name Response data Description
onAudioToggle isAudioMuted(boolean) This event is received when participant’s own audio stream has been toggled successfully. Audio stream state is also received as callback parameter
onRemoteAudioToggle {isAudioMuted(boolean), email(string)} This event is received when some other participant has toggled his audio stream. Audio stream state and the email of the participant is also received as callback parameter

3.9 Add participants to an Exisiting Call

yuWee.addParticipantsToCall (newParticipants, groupName)

Description & Usage:

This API is used to add new participants to an ongoing call.

Parameters

Parameter name Type Description
newParticipants Array of emails Array of email of all the users being added to the call
groupName String This is to provide a group name in case adding participant to a 1-to-1 call

Callback events

Event name Response data Description
onNewMemberAddedToCall Array of userInfo with id, name and email This event is received by all the existing participants in a call when new participants are added via above API

3.10 Fetch recent calls list

yuWee.getRecentCalls (String skipCount)

Description & Usage:

This API is used to fetch list of recent calls made or received by the user, including the ongoing calls

Parameters

Parameters name Type Description
skipCount String skipCount is the number of calls that needs to be skipped from last. Ex: First time skipCount can be 0 because you want to get 20 recent most calls. To get next 20 calls, value of skipCount should be 20.
limit String It is the number of records to be returned

Callback events

Event name Parameter Description
onFetchRecentCallSuccess JSONObject response This event is received when the call list has been successfully fetched
onFetchRecentCallFailure String error This event is received when call list fetch has failed

3.11 Join an ongoing call

yuWee.joinOngoingCall (callId, mediaType);

Description & Usage:

This API is used to join an ongoing call

Parameters

Parameter name Parameter Description
callId String callId is the identifier which is unique for each call and can be used to join a specific call. To join a specific call, developer can look at the response of the fetch recent calls list API which contains callId of each ongoing as well as past call.
mediaType String Its value will be “audio” to join the ongoing call with only audio enable and “video” for both audio and video

Callback events

Event name Parameter Description
onReadyToJoinOngoingCall nil This event is received when the initial setup to join the ongoing call is complete. On listener of this developer need to call APIs- 3.2 and 3.3 and 3.4 in sequence as in normal call to manage stream and register in call to connect
onError Error message This event is received when joining of the call fails

3.12 Call hangup

yuWee.hangupCall ( callEndType )

Description & Usage:

This API ends the ongoing call and clears up all the used resources

Parameter Name Type Description
callEndType String

“end&notify”-> If a call is hung with this parameter, notification is sent to all other participants via event “onRemoteCallHangUp”

“end”-> If a call is hung with this parameter, no notification is sent to other participants of the call

Callback events

Event name Response data Description
onCallHangupSuccess Nil This event is received by a participant when it has successfully ended the call
onRemoteCallHangUp Remote user info, {userId,name,email} This event is received by a participant of a call, when some other participant has ended/left the call
onCallEnded Nil This event is called when a call has ended, i.e all the participants have left it successfully

3.13 Other important events

Event name Response data Description
onIncomingCallWhileBusy Call information in JSON This event is received when a user receives a new call notification while he is already busy in one.
onCallRespondedFromOtherLogin Nil This event is received when the user is logged-in at multiple devices and has responded(accepted/rejected) from the other device. All other login platforms will receive this event. Developer may choose to drop the incoming call notification listening to this event, showing a missed call.

4. Screen Sharing

yuWee.toggleScreenShare( )

Description & Usage:

User can share their screen during a call via this API. Currently this feature is supported only for Web Chrome and Web Mozilla. While Screen sharing feature works by default in Mozilla, a chrome-extension plugin is needed for Chrome.

Note

Providing the Chrome extension along with code-base is in the scope of YuWee.

Callback events:

Event name Response data Description
onScreenSharingError Error message This event is received when there occurs an error while initiating screen share. Screen share usually fails because of one of the following reasons: 1. Incompatible browser 2. Screen sharing cancelled from the confirmation window of chrome extension 3. Chrome plugin missing
onScreenShareStatusChanged statusId, stream

This event is triggered whenever the status of screen sharing lifecycle changes. Screen sharing feature has 3 different states:

0- inactive: When this event is triggered with status=0, it depicts that screen sharing has been deactivated

1- active: When this event is triggered with status=1, it depicts that screen screen share is active. Local screen stream is received as a callback. The same can be attached to a HTML element as described earlier. Others users start receiving your screen stream

2- deactivating: When this event is triggered with status=2, it depicts that screen share is being deactivated as a callback. The same can be attached back to the HTML element

5. Meeting scheduler

5.1 Schedule a meeting

yuWee.scheduleMeeting ( callParamsObj )

Description & Usage:

This API is used to schedule a call for a future date-time. Once a call has been scheduled, a meeting setup mail is sent to each participant with the meeting information. The email automatically makes entry to the respective email client calendar for native client reminder for the meeting. E.f. if the mail goes to outlook, an event is entered to the outlook calendar. Other supported clients/Calendars are Gmail, Apple calendar. User can accept/reject the meeting via calendar.

Parameters

Parameter name Type Description
meetingName String Name of the meeting
meetingDescription String Meeting description
date String Format dd/mm/yyyy, eg 17/Aug/2019
time String Format HH:MM
duration String Format HH:MM
mediaCallType String “audio”/”video”
timeZone String Format: “GMT+HH:MM” e.g GMT+05:30
alertBeforeMeeting number In minutes
members Array Array of emails

Callback events

Event name Response data Description
onMeetingCreatedSuccessfully Meeting details This event is received by each participant once a meeting has been successfully registered
onMeetingCreationFailure Error message This event is fired when a meeting creation fails
onMeetingCallActivated Meeting details This event is received by each participant when a scheduled call has got activated, i.e. just before the reminder duration prior to the scheduled time
onMeetingExpired Meeting details This event is received by each participant once a meeting has expired
onMeetingDeleted Meeting details This event is received by each participant once a meeting has been been deleted by the host

5.2 Fetch upcoming call list

yuWee.fetchAllUpcomingCalls()

Description & Usage:

This API is used to get list of all upcoming calls for the user.

Callback events

Event name Parameter Description
onFetchUpcomingCallSuccess JSONObject response This event is received when the list of upcoming calls has been fetched successfully
onFetchUpcomingCallFailure Error message This event is received when fetching of list fails

5.3 Delete an upcoming/schedule call

yuWee.deleteMeeting(string SchedulerId)

Description & Usage:

This API is used to delete a particular upcoming or scheduled call.

Callback events

Event name Parameter Description
onDeleteMeetingSuccess Meeting details This event is received when an upcoming call has been successfully deleted
onDeleteMeetingError Error message This event is received when deletion of the upcoming call fails

5.4 Join an Active upcoming/schedule call

yuWee.joinMeeting (callId, mediaType);

Description & Usage:

This API is used to join a particular upcoming or scheduled call. callId is the identifier which is unique for each call. Developer can look at the response of the Get Upcoming Call List API which contains details along with callId of each upcoming/scheduled call.

Callback events

Event name Parameter Description
onReadyToJoinMeeting nil This event is received when the initial setup to join the call is complete. On listener of this developer need to call APIs- 3.2 and 3.3 and 3.4 in sequence as in normal call to manage stream and register in call to connect
onError Error message This event is received when joining of the call fails

6. Chat

6.1.1 Create a chat room

yuWee.fetchChatRoombyUserIds(ArrayList<String> userIds)
yuWee.fetchChatRoombyEmails(ArrayList<String> emails)

Description & Usage:

These APIs are used to create a new chat room. They will return the roomId which can be used to communicate messages and also calls. If a chat room with provided users or emails already exists, existing roomId will be returned otherwise a new roomId will be returned.

Parameters

Parameters name Type Description
userIds/emails Array Array of userIds or Array of email for users with whom chat room is to be created
allowReuseOfRoom Boolean If this boolean is false, a new room is created even if there is an existing room in the DB with the same users. If true, existing room is returned if there exists any otherwise a new room is created
groupName** Boolean(optional) A groupName can be given if a room is being fetched for more than 2 users. If groupName is not provided a default name is used for the group with initials “unnamed_conversation”

groupName can be used as Room Name too. However it must be noted that rooms and groups are two different entities, in the way that room is a separate collection used for communication purpose whereas group is used for user management purpose.

Callback events

Event name Parameter Description
onFetchChatRoomSuccess room details This event is received when a room has been successfully created or fetched
onFetchChatRoomFailure error message This event is received when room creation fails

6.1.2 Fetch Room Details

yuWee.fetchRoomDetails(roomId)

This API is used to fetch details of a particular room.

Parameters

Parameters name Type Description
roomId String roomId of the room whose details needs to be fetched

Callback Events

Event name Parameter Description
onFetchRoomDetailsSuccess JSONObject response This event is received when room details has been successfully fetched.
onFetchRoomDetailsFailed String error This even is recieved when room details fetch has failed

6.1.3 Send a chat message

yuWee.sendMessage(RoomId, Message, messageIdentifier);

Description & Usage:

This API is used to send chat messages

Parameters

Parameter name Parameter Description
Message String Message to be send
RoomId String The roomId on which the message will be sent. It can be either received through “Create a chat room” API or through parameter in the roomList
messageIdentifier String This is unique ID defined by developer, so that when this message is delivered, developer will know which message has been delivered and keep track

Callback events

Event name Parameter Description
onMessageDeliverySuccess messageDetails This event is received when a message has been successfully delivered to the other participant or group members
onNewMessageReceived messageDetails This event is received when a new message is recieved from other user or in a group

6.1.4 Fetch a chat list

yuWee.fetchChatList()

Description & Usage:

This API is used to fetch all the chat list (list of conversations or rooms) of the users.

Callback events

Event name Parameter Description
onFetchChatListSuccess JSONObject chatList This event is received when chat list has been successfully fetched
onFetchChatListFailed String error This event is received when fetching the chat list fails

6.1.5 Fetch a conversation

yuWee.fetchChatMessages( roomId, skipCount)

Description & Usage:

This API is used to fetch all the messages of a particular conversation or room

Parameters

Parameters name Type Description
roomId String roomId of the room whose conversation needs to be fetched
skipCount String skipCount is the number of messages that needs to be skipped from last. Ex first time skipCount can be 0 because you want to get 20 recent most messages. To get next 20 messages, value of skipCount should be 20

Callback events

Event name Parameter Description
onFetchChatMessagesSuccess JSONObject response This event is received when messages of the chat room has been successfully fetched
onFetchChatMessagesFailed String error This event is received when messages fetch for the room has failed

6.1.6 Mark message as read

yuWee.markMessagesReadInRoom(roomId)

Description & Usage:

This API is used to mark the messages as “read”

Parameters

Parameters name Type Description
roomId String roomId of the room whose all messages need to be marked as read

Callback events

Event name Parameter Description
onReadMessageInRoomSuccess JSONObject response This event is received when all messages of a room are successfully marked as read
onReadMessageInRoomFailed String error This event is received when process for marking all the messages in a room as read has failed

6.1.7 Delete message in a conversation

yuWee.deleteMessageInRoom( roomId, messageId, messagetype) 

Description & Usage:

This API is used to delete a particular message of a conversation or room.

Parameters

Parameters name Type Description
roomId String roomId of the room whose message needs to be deleted
messageId String MessageId of the message to be deleted
MessageDeleteType String

“FOR_ME”: Delete the message for me only.

“FOR_ALL”: Delete the messages for everyone in the room

Callback events

Event name Parameter Description
onDeleteMessageInRoomSuccess JSONObject response This event is received when the targeted message has been successfully deleted
onDeleteMessageInRoomFailed String error This event is received when deletion of the target message has failed
onMessageDeletedBySender JSONObject messageDetails This event is received by all the room participants when a message is deleted by the sender in that room

6.1.8 Clear conversation

yuWee.clearChatRoom(roomId)

Description & Usage:

This API is used to delete all messages of a particular conversation or room

Parameters

Parameters name Type Description
roomId String roomId of the room whose conversation needs to be cleared

Callback events

Event name Parameter Description
onClearChatRoomSuccess JSONObject response This event is received when the targeted conversation/room is cleared successfully
onClearChatRoomFailed String error This event is received when the method to clear the room has failed

6.1.9 Delete a conversation/room

yuWee.deleteChatRoom(roomId)

Description & Usage:

This API is used to delete a particular conversation or room completely from the listing.

Parameters

Parameter name Type Description
roomId String roomId of the room which needs to be deleted

Callback events

Event name Parameter Description
onDeleteChatRoomSuccess JSONObject response This event is received when the targeted conversation/room is deleted successfully
onDeleteChatRoomFailed String error This event is received when the method to delete the conversation/room has failed

6.2.1 Send typing events in room

yuWee.sendTypingStatus(roomId)

Description & Usage:

This API is used to broadcast user’s typing event to the room. Everyone else in the room receives the typing status of other users via a listener described in 2.8.13

Parameters

Parameter name Type Description
roomId String roomId of the room where typing status needs to be broadcasted

Callback events

Event name Parameter Description
onUserTypingInRoom JSONObject roomDetails This event is received when any other user is typing a message in the room

6.2.2 Share File Via External URL

yuWee.shareFile(roomID, fileInfo, messageIdentifier)

This API is used to share a file (via URL) as a chat message. Developer needs to manage the storage of the file of its own and use a file URL with this API for file sharing.

Parameters

Parameters name Type Description
roomId String The roomId on which the file to be shared. It can be either recieved through “Create a chat room” API or through parameter in the roomList.
fileInfo JSON It contains information about the file to be shared. It should have following keys: fileName, fileExtension, fileSize, downloadUrl. e.g- fileInfo= {“fileName”:”newfile.png”, “fileExtention”:’png’, “fileSize”:1024, “downloadUrl”:”www.myImage.com”}
messageIdentifier String This is unique ID defined by developer, so that when this message is delivered, developer will know which message has been delivered and keep track.

Callback Events

Event name Parameter Description
onMessageDeliverySuccess messageDetails This event is received when a message/file has been successfully delivered to other participants of group members.
onNewMessageReceived messageDetails This event is received when a new message is received from other user or in group. Developer can look for key “messageType” to be “File” to segregate file messages from normal text messages

6.2.3 Add New Users to Existing Group Chat

yuWee.addMembersInGroupByEmail(roomId,emails)
yuWee.addMembersInGroupByUserId(roomId,userIds)

This API is used to add new users to an existing group chat or room.

Parameters

Parameter name Type Description
roomId String The roomId on which the new users to be added
userIds/emails Array Array of userIds or Array of emails for users with whom chat room is to be created

Callback Events

Event name Parameter Description
onMembersAddedToGroupSuccess groupInfo This event is received when new users have been successfully added to a group by an existing user.
onMembersAddedToGroupFailure Error This event is recevied when new user’s addition to the group has failed
onNewMembersAddedToGroup groupInfo and new members info This event is received by a user when new users have been added to a group by some other existing user.

6.2.4 Remove Users From Existing Group Chat

yuWee.removeMembersFromGroupByEmail(roomId, emails)
yuWee.removeMembersFromGroupByuserId(roomId, userIds)

This API is used to remove users from an existing group or room.

Parameters

Parameter name Type Description
roomId String The roomId on which the new user are to be added
userIds/emails Array Array of userIds or Array of Emails for user with whom chat room is to be created

Callback Events

Event name Type Description
onMembersRemovedFromGroupSuccess groupInfo This event is received when users have been successfully removed from a group by an existing user
onMembersRemovedFromGroupFailure Error This event is received when user’s removal from the group has failed
onMembersRemovedFromGroup groupInfo and new members info This event is received by a user when users have been removed from a group by some other existing user

Removed users would still show up in the response list. Lookout for the “hasLeft” key under “members”. Key is false when the user has left or removed from the group. It is true for existing users.

7. Contact Management

7.1.1 Add Contact

yuWee.addContact(name,email,otherDetails)

This API is used to add a new contact. Please note that by adding someone to your contact, you are allowing YuWee to share your real time status with the other user. You receive real time status of users who have added you to your contacts. So, if you have added someone to your contact, you are not entitled to receive the real time status of the contact user for privacy reasons, unless the other user has added you

Parameters

Parameteres Name Type Description
Name String Name of contact
email String Email of contact
other details JSON Other details {‘phoneNumber’:‘8454548’, ‘companyName’:’YuWee’, ‘jobTitle’:’Associate Manager’, ‘address’:‘221B Baker Street’, ‘dob’=‘30.08.1987’, ‘notes’=’Hard to beat guy’, ‘contactImage’=’https://yuwee.com/myImage.jpg’}

Callback Event

Event name Parameter Description
onContactAddSuccess JSONObject response with contactId This event is received when a contact has been successfully added.
onContactAddFailed String Error This event is recevied when a contact contact failed to be added.

7.1.2 Fetch Contact Details

yuWee.fetchContactDetails(contactId)

This API is used to fetch details of an existing contact.

Parameters

Parameters name Type Description
contactId String contactId of the contact whose details to be fetched.

Callback Event

Event Name Parameter Description
onContactDetailsSuccess JSONObject response This event is received when details of a contact has been successfully fetched
onContactDetailsFailed String Error This event is received when contact details fetch has failed.

7.1.3 Fetch Contact List

yuWee.fetchContactList()

This API is used to fetch list of all existing contacts

Callback Event

Event name Parameter Description
onFetchContactListSuccess JSONObject response This event is received when contact list has been successfully fetched
onFetchContactListFailed String Error This event is received when contact list fetch has failed.

7.1.4 Delete a Contact

yuWee.deleteContact(contactId)

This API is used to delete a particular contact.

Parameters

Parameters name Type Description
contactId String contactId of the contact to be deleted

Callback Event

Event Name Parameters Description
onContactDeleteSuccess JSONObject response This event is received when a contact has been successfully deleted.
onContactDeleteFailed String Error This event is received when contact delete has failed.

7.1.5 Set Status

yuWee.setStatus(status)

This API is used to update the status of the logged-in user.

Parameters

Parameters name Type Description
status String Status of the user. It can be either of: “ONLINE”,”BUSY”,”AWAY”,”INVISIBLE”

7.1.6 Fetch Status of a Particular User

yuWee.getParticularUserStatusByEmail(email)
yuWee.getParticularUserStatusByUserId(userId)
yuWee.getParticularUsersStatusByContactId(contactId)

These APIs are used to fetch status of a particular user. Please note that for privacy reasons, a status will only be received if the target user has added you to his contacts.

Parameters

Parameters name Type Description
email String Email of the user whose status is to be fetched
userId String UserId of the user whose status is to be fetched
contactId String ContactId of the user whose status is to be fetched

Callback Events

Event name Parameters Description
onUserStatusFetchSuccess JSONObject response This event is received when a status of a user has been successfully deleted
onUserStatusFetchFailed String error This event is received when a user status fetch has failed