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
NameTypeDescription
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)

Example

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.

Example

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.
    });
});

Example

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

Example

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

notifyClient.call({
    phoneNumber: "+18001112223"
});

Example

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

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

Example

This example shows a button click handler.

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

Example

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

Example

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: "+17012345678",
    dtmf: "1234"
}
client.forwardCall(arg);

Example

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.

Example

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

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

Example

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.

Example

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

Example

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

Example

This example shows how to initialize the Notify client.

$j(function() {
  notifyClient = new SNC.Notify.Client( notifyConfig );
  notifyClient.setCallerId( '+31858889170' );
  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

Example

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

Example

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

Example

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

Example

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( '+31858889170' );
  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