Mesibo Video & Voice Call APIs - Listeners

Estimated reading time: 12 minutes

The Mesibo Call API provides the following listeners:

  • IncomingListener, MesiboCall.IncomingListener provides listeners to handle incoming calls, errors, show call UI, etc.

  • InProgressListener, MesiboCall.InProgressListener allows listeners to handle various call events for an ongoing call example, call ringing, answered, declined, hang up, audio device changed, etc.

You can use mesibo calls with default call handling logic and call UI as it is. You only need to implement these call listeners - IncomingListener and InProgressListener if you would like to customize how mesibo handles and displays call in your application. For example, filtering an incoming call, display a custom call screen, etc.

IncomingListener

Your app needs to implement an IncomingListener to handle incoming calls and any error conditions. We recommend that you implement this listener interface in MainApplication in Android or AppDelegate in iOS. However, you can implement it wherever it suits your application architecture.

The following are the listeners available in MesiboCall.IncomingListener:

MesiboCall_OnIncoming

Every time there is a new incoming call, mesibo will call MesiboCall_OnIncoming. Depending on your app logic, you can decide to allow the incoming call or filter it. For example, perform call filtering at the application level to reject callers who are blocked/identified as spam, etc. If you decide to allow the Call, you need to create a CallProperties object and return it. In the CallProperties object, you can set the video/audio bitrate, etc. Mesibo sets the default values for the call properties, but you can override it as required by your app. To reject an incoming call, return null from MesiboCall_OnIncoming.

Parameters:

  • profile, Contains the caller’s profile details such as the photo, address, etc.
  • video, true in case of a video call, false otherwise.

For example, in Android,

@Override
public MesiboCall.CallProperties MesiboCall_OnIncoming(Mesibo.UserProfile profile, boolean video){
	// In this example, we use video as a filter to accept video calls only
	if(!video)
		return null; //Accept video calls only
	
	if(profile.address == null || profile.address.isEmpty())
		return null;

	// your app specific function to check if the caller is allowed
	if(isInBlockedList(profile.address)){
		// Check if the caller is part of the blocked list. 
		// You can block spam callers this way.
		return null; // reject the Call by returning null
	}
	
	// Define call properties 
	MesiboCall.CallProperties cp = MesiboCall.getInstance().createCallProperties(true);
	
	// Define optional parameters
	cp.video.enabled = true; 
	cp.video.bitrate = 2000; //bitrate in kbps

	return cp;
}

Return the MesiboCall.CallProperties object to continue with the call. Return null to reject the call.

MesiboCall_OnError

MesiboCall_OnError is called when an error occurs while making a call.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.
  • error, An integer error code. For example, while making an outgoing call, if the destination is busy, the error code will be MESIBOCALL_ERROR_BUSY.

For example, In Android,

void MesiboCall_OnError(MesiboCall.CallProperties properties, int error){
	//Handle error
}

MesiboCall_OnShowUserInterface

If an incoming call is accepted, mesibo prepares the call API object and calls MesiboCall_OnShowUserInterface to show the user-interface. Your application should return true to show your user interface or return false to show the mesibo default call user interface.

Parameters:

  • call, A MesiboCall.Call object which you can use to handle the call in your Activity/View Controller.
  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.

Returns:

  • true to show custom call user interface
  • false to show default mesibo call user interface

For example, In Android,

boolean MesiboCall_OnShowUserInterface(Call call, CallProperties properties){

	//Show defalult Call UI
	return false;
}

MesiboCall_onNotify

Called to notify the app of missed calls, etc., through which you can display call notifications.

Parameters:

  • type, Notification type
  • profile, UserProfile object containing the photo, address, etc.
  • video, Set to true if it is a video call, false otherwise

Returns: true to if you are showing the notification, false to dismiss it.

For example, In Android,

boolean MesiboCall_onNotify(int type, Mesibo.UserProfile profile, boolean video){
	// Show call notifications
}

InProgressListener

You only need to implement the InProgress listener if you are creating a custom use-interface. The InProgress listener is invoked by mesibo for various events such as - change in call status (ringing, answered, etc.), when remote peer mutes, when the active audio device changes from an earpiece to a speaker, etc.

Using these callbacks, you get continuous feedback on what is happening on the Call, and you can accordingly update your UI using this information. The following are the listeners in MesiboCall.InProgressListener.

MesiboCall_OnUpdateUserInterface

MesiboCall_OnUpdateUserInterface is called when there a change in the call state that may require the app to modify the displayed call screen. Note, it is not mandatory to update the UI. Mesibo only recommends that the app reflects changes in the call state in the displayed UI.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.

  • state, Call State indicated by any of the following:
    • MESIBOCALL_UI_STATE_SHOWINCOMING, Show incoming call screen
    • MESIBOCALL_UI_STATE_SHOWINPROGRESS, Show InProgress call screen.
    • MESIBOCALL_UI_STATE_SHOWCONTROLS, show or hide controls. This is only called for video calls. For example, when a video call is connected, it is recommended to hide controls for the best user experience.
  • video, Set to true if it is a video call, false otherwise.
  • enable, Set to true, to enable the UI, false to hide it.

For example, In Android,

void MesiboCall_OnUpdateUserInterface(CallProperties p, int state, boolean video, boolean enable){
	//Update Call UI
}

MesiboCall_OnStatus

Called when the status of the call changes.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.
  • status, The call status indicated by any one of the following:
    • CALLSTATUS_COMPLETE, The Call has ended
    • CALLSTATUS_CONNECTED, Call is set up and connected
    • CALLSTATUS_INPROGRESS, The call is active
    • CALLSTATUS_RINGING, In case of an outgoing call, when the destination is ringing until they accept the Call
    • CALLSTATUS_BUSY, In case of an outgoing call, when destination declines the Call
    • CALLSTATUS_NOANSWER, In case of an outgoing call, when the destination does not answer the Call
    • CALLSTATUS_NETWORKERROR, A network error has occurred
    • CALLSTATUS_UNREACHABLE, In case of an outgoing call when the destination is not reachable
    • CALLSTATUS_INVALIDDEST, Unable to place an outgoing call, as the provided destination address is not valid
    • CALLSTATUS_NOTALLOWED, Unable to place Call due to app restriction or being blocked by destination
    • CALLSTATUS_RECONNECTING, Reestablishing Call connection
    • CALLSTATUS_HOLD, The Call has been put on hold either by the destination or the local user
    • CALLSTATUS_ANSWER, The outgoing Call was answered
  • video, Set to true if it is a video call, false otherwise

For example, in Android,

void MesiboCall_OnStatus(CallProperties p, int status, boolean video){
	// Handle change in the call status
}

MesiboCall_OnSetCall

MesiboCall_OnSetCall is called when the call object is initialized.

Parameters:

  • activity, The MesiboCallActivity that was launched to display the call UI.
  • ** Call**, The call object which you can store for further use

For example, in Android,

void MesiboCall_OnSetCall(MesiboCallActivity activity, MesiboCall.Call call)

MesiboCall_OnMute

MesiboCall_OnMute is called when either of the two parties on the call mutes their audio or video.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.
  • audioMuted, Set to true if the audio was muted
  • videoMuted, Set to true if the video was muted
  • remote, Set to true if it was muted by remote peer end, false for local mute

For example, in Android,

void MesiboCall_OnMute(CallProperties p, boolean audioMuted, boolean videoMuted, boolean remote){
	//Handle Mute
}

MesiboCall_OnPlayInCallSound

MesiboCall_OnPlayInCallSound is called when an in call ringing / busy or custom caller tune sound needs to be played. When you are making an outgoing call, you can play a sound until the destination answers the Call. The sound can be anything. A simple ringing sound, a custom caller tune, etc. To play the in-call sound, you can use a utility function playInCallSound.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.
  • type, The type of the in-call sound
  • play, Set to true if the ringing sound is being played.

Return:

  • true to play your audio for the in-call sound
  • false to play the default mesibo in-call sound

For example, in Android

boolean MesiboCall_OnPlayInCallSound(CallProperties p, int type, boolean play){	
	// Play ringing sound
	return 1;
} 

MesiboCall_OnHangup

MesiboCall_OnHangup is called when the remote peer or local user hangs up on the call.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.
  • reason, Reason for hanging up the call.
    • MESIBOCALL_HANGUP_REASON_USER, Call hanged up on the local end
    • MESIBOCALL_HANGUP_REASON_REMOTE, Call hanged up by the remote end
    • MESIBOCALL_HANGUP_REASON_ERROR, An error occurred which ended the call. Also, see MesiboCall_OnError

For example, in Android,

void MesiboCall_OnHangup(CallProperties p, int reason){ 
	//Handle hangup
}

MesiboCall_OnAudioDeviceChanged

MesiboCall_OnAudioDeviceChanged is called when the active audio device is changed either by calling setAudioDevice() or by a user action, for example, headset inserted, Bluetooth was turned ON.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.
  • active, The new AudioDevice that you have switched to and is considered to be active.
  • inactive, The previous AudioDevice that was active before you switched to a different one. The previous device is now considered to be inactive.

See AudioDevice.

When the audio device is changed, you may need to display that in the call UI—for example, grey out the icon of the inactive device.

For example, in Android,

void MesiboCall_OnAudioDeviceChanged(CallProperties p, AudioDevice active, AudioDevice inactive){
	//Handle audio device change
}

MesiboCall_OnDTMF

MesiboCall_OnDTMF is called when a DTMF digit is received from the remote end.

Parameters:

  • properties, The CallProperties object which was set while initiating an outgoing call or receiving an incoming call.
  • digit, the DTMF digit which was sent by the remote end

For example, in Android,

void MesiboCall_OnDTMF(CallProperties p, int digit){	
}

To send Dtmf tones, you can use sendDtmf.

MesiboCall_OnVideo

MesiboCall_OnVideo is called when there is a video feed received from the remote end or local end in a video call.

Parameters:

  • properties, A CallProperties object. Defines various call properties and behavior, for example, video size, bitrate, hide on proximity, the call peer’s profile, etc.
  • videoProperties, A MesiboCall.CallProperties.VideoProperties object which contains information about the video feed such as the bitrate, codec, etc.
  • remote, Set to true if remote video feed, false if local video feed.

For example, in Android,

void MesiboCall_OnVideo(CallProperties p, VideoProperties video, boolean remote){
	// Display video feeds
} 
listeners, voice, video