SDK Reference Material

SDK Global Methods

Init

Acquire a dialer API instance and ensure the dialer interface is ready (see SDK dialer instance methods)

Parameter Type Description
dialerConfig [object] Dialer configuration options.
callback [function] Callback function.

setProvider

Allows switching the provider (CC/UC) after the dialer interface is loaded.

Parameters Type Description
provider "cc" / "uc"
  • CC loads Vonage Call Center ContactPad as a dialer interface /VCC/.
  • UC loads Vonage Business Communicatons ContactPad as a dialer interface /VBC, VBE/.
ccDomain (optional) [string] Use a custom VCC region domain. Well known options are:
  • nam.newvoicemedia.com (default)
  • emea.newvoicemedia.com
  • apac.newvoicemedia.com

placeCall

Shortcut alias to dialer instance method placeCall (to be used when integration does not allow custom initialization).

Parameters Type Description
phoneNumber [string] Phone number to dial
contactable (optional) [entityRef] Optionally pass a preferred contact to be attached to the interaction events.

setProvider

Allows switching the provider (CC/UC) after the dialer interface is loaded.

Parameters Type Description
provider "cc" / "uc"
  • CC loads Vonage Call Center ContactPad as a dialer interface /VCC/.
  • UC loads Vonage Business Communicatons ContactPad as a dialer interface /VBC, VBE/.
ccDomain (optional) [string] Use a custom VCC region domain. Well known options are:
  • nam.newvoicemedia.com (default)
  • emea.newvoicemedia.com
  • apac.newvoicemedia.com

enableClickToDial

Enable/Disable SDK build in phone number annotation library.

Parameters Type Description
enabled [boolean] Annotate phone numbers on the current WEB page with a ClickToDial icon.

setCountryCode

Set default country for national format phone numbers recognition.

Parameters Type Description
countryCode [string] 2 character country code (ISO 3166-1 alpha-2 standard).

SDK Dialer Instance Methods

VonageDialer.init({ debug: true }, (dialer) => {
  dialer // <- dialer instance 
});

setVisibility

Programmatically show/hide the dialer frame in DOT mode. This method has no effect when the dialer is loaded in a container.

Parameters Type Description
visible [boolean] Show/Hide the dialer frame.

setOnDialerEvent

Register a callback function to be executed when a dialer event occurs.

Parameters Type Description
callback [function] Event processing callback function. The parameter sent to the callback function is a polymorphic model object having a property named "type". Each event type has its own properties structure.

registerSvgIcon

(UC dialer only) Set custom integration icon for settings and contacts visualization.

Parameters Type Description
providerCode [string] Custom integration provider programmatic name.
dataUrl [string] Base64 data encoded SVG image (* You can convert any SVG image (recommended size 64x64px) to a data URL with an online tool).

placeCall

Place a call.

Parameters Type Description
phoneNumber [string] Phone number to dial.
contactable (optional) [entityRef] Optionally pass a preferred contact to be attached to the interaction events.

SDK Data Models

dialerEvent

Dialer events are polymorphic objects categorized by type. The SDK uses events for operations that do not require response from the integration code.

Properties Type Description
type [string] Interaction or operation event type:
  • CALL_START - Call first appearance
  • CALL_ANSWER (*UC only) - The call is connected
  • CALL_END - The call reached its final state
  • CALL_HISTORY (*UC only) - The user selected an interaction from the history dialog interface.
  • CHAT_START (*CC only)
  • CHAT_END (*CC only)
  • READY - The user is logged in the interface.
  • LOGOUT - The user logged out.
  • HEALTH - The telephony service status (ability to place and receive calls).
data [object] Event data. Each type has a different data schema.

Event type CALL_START

The event is generated by the SDK only once when a new interaction appear (in any internal state), or when there is an active call after the dialer is reloaded.

Properties Type Description
id [string] Telephony provider interaction identifier. This identifier is not unique for the system. In order to keep association to the Vonage interaction in 3rd party storage use uid instead.
uid [string] A composite interaction identifier (guarantees true uniqueness for the whole system).
direction "INBOUND" / "OUTBOUND" Interaction direction
phoneNumber [string] Interaction remote party phone number
state [string] Interaction fine lifecycle state (INITIALIZING -> RINGING -> ACTIVE -> final disposition).
internal [boolean / undefined] TRUE when this is a Vonage account internal communication.
tag (optional) [string] *VBC only. Call Tagging
contact (optional) [contactable] Attached contact. A contact could be assigned with the place call action.
activity (optional) [entityRef] Attached uncompleted/current 3rd party activity reference.

Event type CALL_ANSWER

(UC only) The event is generated by the SDK when the call is connected.

Properties (extends CALL_START event schema) Type Description
answerDate [datetime] Answer time.

Event type CALL_END | CALL_HISTORY

The END event is generated by the SDK when the interaction reaches its final state. The HISTORY event is generated when the user selects a completed call from the history.

Properties (extends CALL_START event schema) Type Description
answerDate (optional) [datetime] Answer time (unless it is zero duration state).
endDate [datetime] Release time.
const ACTIVE_CALL_STATES = ['INITIALIZING', 'RINGING', 'ACTIVE', 'HELD', 'REMOTE_HELD'];
const TALKING_CALL_STATES = ['ACTIVE', 'HELD', 'REMOTE_HELD'];
const RELEASED_CALL_STATES = ['ANSWERED', 'CANCELLED', 'MISSED', 'REJECTED', 'DETACHED', 'DISCONNECTED'];
const ZERO_DURATION_STATES = ['CANCELLED', 'MISSED', 'REJECTED', 'DISCONNECTED'];

dialerConfig

Configuration options for SDK init method.

Properties Type Description
debug [boolean]
default: false
Print extra debug information in the browser JS console.
provider "cc" / "uc"
default: "uc"
  • CC loads Vonage Call Center ContactPad as a dialer interface /VCC/.
  • UC loads Vonage Integration Platform (VGIP) as a dialer interface /VBC, VBE/.
ccDomain (CC only) [string] Use a custom VCC region domain. Well known options are:
  • nam.newvoicemedia.com (default)
  • emea.newvoicemedia.com
  • apac.newvoicemedia.com
features (UC only) [dialerFeatures] Customize UC dialer interface (show/hide extra UI controls).

dialerFeatures

Show/Hide extra controls in the UC dialer interface.

Properties Type Description
contactsProvider [boolean]
default: false
When enabled, the dialer will execute the configured searchContactables callback when the user types in the dialpad phone number input and show the results as contacts suggestions.
openContact [boolean]
default: false
When enabled, the dialer will visualize an extra "open external link" icon near the contacts within the interface. Click on the icon executes the implemented openContact callback.
openActivity [string] The value must be the providerCode chosen for the custom integration. Vonage Integrations attaches activities from different integration sources to the interaction events. The value is used as a scope to filter only the activities generated by your custom integration provider. When enabled, the UC dialer will visualize an extra "new/open note" icon in the interaction history and during an active call. Click on the icon executes the implemented openActivity callback.
eventsHistory [boolean]
default: true
When enabled the dialer will generate an extra event of type "CALL_HISTORY" when the user clicks on a completed call from the interaction history dialog.

contactable

Unified object which represent any 3rd party entity having names and phone number and can represent an interaction party.

Properties Type Description
provider [string] (required) Custom integration code. When visualizing contacts UI decorates the contact with the registered SVG icon having the same provider code.
id [string] (required) External identifier. The custom integration contact uniqueness must be based provider+id+type.
type [string] (required) External entity programmatic type.
*Common CRM types are: Contact, Lead, Account, Candidate etc.
label [string] (required) A string representing the external entity as human readable text sufficient enough for the user to recognize that the object is the desired one.
*Usually in CRMs it is the First and Last name + some extra info specific for the integration.
phoneNumber [string] (required) Contact phone number. Recommended is E.164 format, although the system is compatible with national formats when the country code is set correctly.
phoneType [string] (optional) Extra label for visualization purposes. If the integration has a contact with 2 numbers (Home and Mobile), it must use 2 identical contactables having only different phoneNumber and phoneType.
typeLabel [string] (optional) Human label for the programmatic entity type for visualization purposes.

entityRef

Unified object which represents any 3rd party entity having integration code, unique identifier and type

NOTE: The object could be a contactable as well, but the purpose is not Visualization (it does not require a phone number). The reference is carried with the interaction events and could be used for custom logic.

Properties Type Description
provider [string] (required) Custom integration code.
id [string] (required) External identifier. The custom integration contact uniqueness must be based provider+id+type
type [string] (required) External entity programmatic type. *CRM type like: Case, Campaign, Task, etc..
label [string] (optional) A string representing the external entity as human readable text, sufficient enough for the user to recognize that the object is the desired one.
typeLabel [string] (optional) Human label for the programmatic entity type for visualization purposes.