NotifyClient - Client

The NotifyClient API provides methods that enable you to use Notify telephony functionality, such as making and receiving calls from a web browser.

Several NotifyClient methods take a callback function as a parameter. Because NotifyClient method calls are made asynchronously, these methods can't return a value directly. Use the callback function to parse the returned data, such as by assigning variables or making other API calls.

NotifyClient - Client(Object notifyConfig, Boolean initializeVendorClientLazily)

Instantiates a new Notify WebRTC Client object.

Table 1. Parameters

Name	Type	Description
initializeVendorClientLazily	Boolean	Flag that indicates whether to use the autoSelectVendorCallback function passed in the setCallerId() method to automatically set the caller's associated vendor (notifyConfig.vendor does not need to be defined in the constructor). false: Default. Do not use the autoSelectVendorCallback function to set the caller's vendor. The vendor must be set in the constructor. true: Use the autoSelectVendorCallback function to define the vendor when the caller ID is set.
notifyConfig	Object	JSON object that contains the configuration settings for the Notify WebRTC Client.
notifyConfig.autoLoadScriptResources	Boolean	Flag that indicates how to load the core JS library needed by the vendor client. false: Default. Use vendor specific codes to load the required vendor JS library (enables backwards compatibility). true: Use notifyClient.js to load the core JS library.
notifyConfig.callerId	Number	Registered Notify number to use. Do not directly set this value. Use the method notifyClient.setCallerID() to set this value.
notifyConfig.forceRefreshToken	Boolean	Flag that indicates whether to auto-renew expired client tokens. false: Do not automatically renew client tokens when they expire. true: Default. Automatically renew client tokens when they expire.
notifyConfig.skipParentId	Boolean	Flag that indicates whether to immediately invoke the onIncoming caller for incoming calls. false: Default. Do not immediately invoke the onIncoming event handler. true: Immediately invoke the onIncoming event handler. By setting this flag, if there is another call, where the <Dial><Client> Twiml caused the incoming call, then setting this flag causes the system to auto poll the backend. This auto poll obtains the parent notify_call reference.
notifyConfig.vendor	Constant	Vendor to which the caller belongs. SNC.Notify.Vendor.TWILIO_DIRECT SNC.Notify.Vendor.TWILIO (older, deprecated Twilio driver)

The following example shows how to create the NotifyClient constructor, register various event listeners, and initialize the client driver.

jQuery(function () {

  var notifyConfig = {
    autoLoadScriptResources: true // This will take care of auto loading the JS resources needed by the client (if any)
  };
  var client = new SNC.Notify.Client(notifyConfig, true); // The second argument ensures that the proper vendor for the given number is auto determined
  client.setCallerId('valid_notify_long_number', function () {
    // This is called after the vendor has been determined.

    if (!notifyConfig.vendor) // Means this number has no compatible vendor
      return;

    client.addEventListener(SNC.Notify.STD_EVENTS.ONLINE, function () {
      // Ability to call is available
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.OFFLINE, function () {
      // Ability to call is _not_ available right now
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.ERROR, function (msg, code) {
      // Some error happened
    });
      //... register other event handlers here
      //Show UI elements which can be used to invoke client.call() and other APIs
    client.init(); // This is important to call this.
    });
});

NotifyClient - addEventListener(String event, Function fn)

Registers an event handler to listen for changes in a Notify client.

Using this method you can register multiple listeners. Each listener must be a separate method call.

Table 2. Parameters

Name	Type	Description
event	String	Name of the event to listen for. Instead of passing strings, use the constants defined in SNC.Notify.STD_EVENTS. CALL_START: call has started and is in progress. CALL_CANCEL: caller canceled the call. CALL_INIT: WebRTC connected to a call (incoming or outgoing). CALL_DISCONNECT: current call has been disconnected. ERROR: Error occurred. Parameters: message(string), errCode(string) message: error message to display. errCode: Optional. Associated error code. INCOMING_CALL: Call is coming in. Parameters: from(string), to(string), callId(string), parentId(string), sysId(string), isFromClient(boolean) from: caller's phone number. to: called phone number. callId: SID of the call. parentId: parent notify_call reference. If skipParentId is set to true, this parameter should not be passed. sysId: WebRTC-to-WebRTC calls only. Unique identifier (sys_id) of the caller. isFromClient: WebRTC-to-WebRTC calls only. Flag that indicates whether the call is from another WebRTC client. CALL_MUTE: client is muted. CALL_UNMUTE: client is unmuted. OFFLINE: WebRTC session is not active. ONLINE: WebRTC session is ready. Must be set after calling the init() method.

Table 3. Returns

Type	Description
Function	Function to use to de-register a listener.

This example shows how to register multiple listeners.

jQuery(function () {

  var notifyConfig = {
    autoLoadScriptResources: true // This will take care of auto loading the JS resources needed by the client (if any)
  };
  var client = new SNC.Notify.Client(notifyConfig, true); // The second argument ensures that the proper client for the given number is auto determined
  client.setCallerId('valid_notify_long_number', function () {
    // This is called after the client has been determined.

    if (!notifyConfig.vendor) // Means this number has no compatible client
      return;

    client.addEventListener(SNC.Notify.STD_EVENTS.ONLINE, function () {
      // Ability to call is available
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.OFFLINE, function () {
      // Ability to call is _not_ available right now
    });
    client.addEventListener(SNC.Notify.STD_EVENTS.ERROR, function (msg, code) {
      // Some error happened
    });
      //... register other event handlers here
     
    client.init(); // This is important to call this.
    });
});

This example shows how to de-register a listener.

var dereg = notifyClient.addEventListener(SNC.Notify.STD_EVENTS.ONLINE, function () {
 ... 
 }); 
 dereg(); 
  // The event listener function is no longer triggered.

NotifyClient - call(Object identifier)

Calls the specified phone number or the phone number associated with a specified user.

Note:

When checking the status of a call/connection, always compare against the constants provided by SNC.Notify.Status.

Table 4. Parameters

Name	Type	Description
identifier	Object	JSON object that contains either a phone number to call or the sys_id of a WebRTC user. Passing a user sys_id causes the call to be made through browser-to-browser communication. You can obtain the user sys_id from the Notify WebRTC Session table. Note: If you provide both a phone number and user sys_id, the method only uses the phone number.

Table 5. Returns

Type	Description
void

This example demonstrates passing a phone number as the function parameter.

notifyClient.call({
    phoneNumber: "[phone]"
});

This example demonstrates passing a user record sys_id as the function parameter.

notifyClient.call({
    userId: "6816f79cc0a8016401c5a33be04be441"
});

This example shows a button click handler.

$j("#pickupCallBtn").on("click", function() {
	notifyClient.hangupCall();
});

This example shows an event handler.

onConnect: function(status) {  
  // webRTC receives a call connection event (incoming or outgoing).
  if (status == SNC.Notify.Status.OPEN) {
    setStatus(getTimeStamp() + " -- Successfully established call");
    showHangupButton();
  }
},

NotifyClient - destroy()

Kills the current Notify client, rendering it unusable.

Table 6. Parameters

Name	Type	Description
None

Table 7. Returns

Type	Description
void

NotifyClient - forwardCall(Object argument)

Forwards an ongoing incoming or outgoing phone call to either a different phone number or a different WebRTC client.

Table 8. Parameters

Name	Type	Description
argument	Object	JSON object that contains the necessary information for forwarding the call to either a phone number or a WebRTC client (user sys_id). You can obtain this sys_id from the Notify WebRTC Session table.

Table 9. Returns

Type	Description
void

This example demonstrates forwarding a call to a different phone number. The dtmf attribute allows you to send DTMF dial tones to the receiving number.

var arg = {
    type: "number",
    id: "[phone]",
    dtmf: "1234"
}
client.forwardCall(arg);

This example demonstrates forwarding a call to a different Notify client.

var arg = {
    type: "userId",
    id: "6816f79cc0a8016401c5a33be04be441"
}
client.forwardCall(arg);

NotifyClient - getAvailableClients(Function callback)

Returns a list of clients available to accept calls.

This method excludes the current client from the list. The equivalent Notify-getAvailableClients() method does not filter any user.

Table 10. Parameters

Name	Type	Description
callback	Function	Function to use to parse the list of clients. This function accepts a single parameter, an array of JSON objects with the following format: [{ sys_id: "...", // user's sys_id name: "..." // user's name }]

Table 11. Returns

Type	Description
void

NotifyClient - getParentId(String callId, Function callback)

Returns the parent call identifier for a specified call identifier, if one exists.

Depending on the telephony provider, there may be a delay before the parent call identifier is returned; therefore you must provide a callback function.

Table 12. Parameters

Name	Type	Description
callId	String	Unique identifier of the call for which to return the parent call identifier.
callback	Function	Function that obtains the JSON object that contains either the parent call identifier or an error message if the identifier could not be obtained after several tries.

Table 13. Returns

Type	Description
String	Parent call identifier.

This example shows how to use this method to obtain the parent call identifier.

notifyClient.getParentId( callId, function(jsonObj) {} );

This example shows the contents of the jsonObj parameter.

{
	parentId: "xyz",
	error: "msg"
}

NotifyClient - getStatus()

Returns the normalized status of the current call.

Table 14. Parameters

Name	Type	Description
None

Table 15. Returns

Type	Description
String	Current status of the call. The values returned by the telephony provider API are normalized by replacing the returned driver value with its equivalent value as defined in SNC.Notify.Status.

This example shows how to obtain the status of the current Notify client.

clientStatus = notifyClient.getStatus();

NotifyClient - hangupCall()

End the current call.

Table 16. Parameters

Name	Type	Description
None

Table 17. Returns

Type	Description
void

This example how to hang up a call.

$j("#pickupCallBtn").on("click", function() {
    notifyClient.hangupCall();
});

NotifyClient - init()

Initializes the client driver.

For example, when using the Twilio client, it invokes the method Twilio.Device.setup(). Call this method after the user has interacted with the page. This initialization process is asynchronous, therefore, you must provide an ONLINE event handler. This handler is called when the setup process is complete and the system is ready to take or make calls.

Table 18. Parameters

Name	Type	Description
None

Table 19. Returns

Type	Description
void

This example shows how to initialize the Notify client.

$j(function() {
  notifyClient = new SNC.Notify.Client( notifyConfig );
  notifyClient.setCallerId( '[phone]' );
  notifyClient.init();
});

NotifyClient - mute(Boolean muted)

Mute or unmute the current client.

Table 20. Parameters

Name	Type	Description
muted	Boolean	Mutes or unmutes the current call. false: (or any non-true value) unmutes the current call. true: mutes the current call.

Table 21. Returns

Type	Description
void

This example shows how to send mute the current call.

notifyClient.mute( "true" );

NotifyClient - pickupCall()

Answers and connects to an incoming call from a WebRTC client.

Call this method when there is a notification of an incoming call.

Table 22. Parameters

Name	Type	Description
None

Table 23. Returns

Type	Description
void

This example shows how to pickup a call.

$j("#pickupCallBtn").on("click", function() {
    notifyClient.pickupCall();
});

NotifyClient - sendDtmf(String digits)

Send one or more DTMF-valid digits over the current call.

Table 24. Parameters

Name	Type	Description
digits	String	One or more DTMF-valid digits.

Table 25. Returns

Type	Description
void

This example shows how to send DTMF signals to the current call.

notifyClient.SendDtmf( "1246AF" ) {} );

NotifyClient - setCallerId(String value, Function autoSelectVendorCallback)

Sets the caller ID for the current client session.

You can change or update the caller ID at any time however, the caller ID must belong to the same vendor.

Table 26. Parameters

Name	Type	Description
value	String	Phone number to use to make and receive calls.
autoSelectVendorCallback	Function	Optional. initializeVendorClientLazily must be set to "true" in the constructor to use this function, otherwise an error is thrown. Name of the callback function to call once the vendor is automatically set for the specified phone number. With this option, the vendor does not need to be specified in the constructor (notifyConfig.vendor). Auto vendor selection is an asynchronous operation. Therefore, this callback is required to indicate when it is safe to call notifyConfig.init(), as this method requires that the vendor be set before it is called. In addition, you must also check if notifyConfig.vendor has been set in the callback to ensure that a vendor has been specified.

Table 27. Returns

Type	Description
void

This example shows how to set the caller ID. This example assumes that the vendor is set in the constructor.

$j(function() {
  notifyClient = new SNC.Notify.Client( notifyConfig );
  notifyClient.setCallerId( '[phone]' );
  notifyClient.init();
});

NotifyClient - setClientAvailable(Boolean available)

Sets the availability of an active WebRTC client agent.

This type of availability is different than an agent being in a call. In this case, an active WebRTC client may be connected and not on a call, but may not want to receive calls.

Calling this method updates the Available field value on the Notify Client Connected Session [notify_client_session] record associated with this client session. You can get a list of available clients using the getAvailableClients() method.

Table 28. Parameters

Name	Type	Description
available	boolean	Flag that indicates whether an active WebRTC client wants to receive calls. false: client does not want to receive calls. true: client does want to receive calls.

Table 29. Returns

Type	Description
void