Dialpad Mini Dialer (CTI)

Introduction

Dialpad's CTI (mini dialer) provides key features of Dialpad's desktop app - calling and messaging - in a version that can be rendered on Google Chrome. The CTI can be opened in an iframe inside a logged in site. This section describes the steps in which the CTI can be setup and the JavaScript methods that can be used for communicating between your application and the CTI iframe.

Embedding the CTI

The CTI can be embedded on any webpage using the following HTML code:

<iframe src="https://dialpad.com/apps/open" title="Dialpad" allow="microphone; speaker-selection; autoplay; camera; display-capture; hid" sandbox="allow-popups allow-scripts allow-same-origin allow-forms" frameborder=0 style="width:400px; height:520px;"></iframe>

It is not necessary to contact Dialpad support to have your webpage allowlisted for this purpose, but please reach out in the case of any other issues using this feature.

Please ensure the allow attribute is included as shown. Users will also need to allow access to microphone, speakers, etc. in Chrome if prompted to do so.

On first use, the CTI iframe will display a 'log in' button. Clicking this button will log the user in autmatically, if they are already logged into the main Dialpad web application. Otherwise, the user will be prompted to enter their account credentials.

Supported JavaScript Methods

We support a few JS methods through the window.postMessage() method by using the postMessage API.

Field definition for the window.postMessage() method:

Field	Type	Required?	Description
`api`	string	true	This specifies the name of the API and should be defaulted to `opencti_dialpad`
`version`	string	true	The version of the API. It should be defaulted to `1.0`
`method`	string	true	The name of the method. We support the following methods: When message is received by the CTI: `initiate_call`, `enable_current_tab`2. When message is sent from CTI: `call_ringing`, `user_authentication`.
`payload`	JSON	false	Parameters and their values that are needed when using the JS API method. Payload is not required in method `enable_current_tab`

The methods supported by Dialpad at this time are listed below

user_authentication

This message is posted by Dialpad when the authentication state of a user in the Dialpad CTI changes. The payload parameters of this message are:

Parameter	Description
`user_authenticated`	If the user is logged in, `true` is passed, else `false`
`user_id`	Dialpad ID (long) of the user that is logged in/out

Example: Dialpad will post such message to the component that embeds the CTI through this way

window.parent.postMessage({
  'api': 'opencti_dialpad',
  'version': '1.0',
  'method': 'user_authentication',
  'payload': {
    'user_authenticated': true,
    'user_id': 1234567
  }
}, '*');

enable_current_tab

This message is posted to Dialpad. Dialpad allows only one CTI tab to be enabled at a time to make and receive calls. This method allows the tab to enable the CTI for calling. There is no payload for this method.

Example:

<CTI_iframe>.contentWindow.postMessage({
  'api': 'opencti_dialpad',
  'version': '1.0',
  'method': 'enable_current_tab'
}, 'https://dialpad.com');

initiate_call

This message is posted to Dialpad. The initiate_call method opens up the dial prompt in the CTI window and an outbound call will be made automatically if the CTI tab is enabled. If the CTI tab is disabled, this method will enable this tab. The following parameters are supported with this method

Parameter	Required	Description
`enable_current_tab`	false	Indicates whether the current tab should be enabled before initiating the call. Default to `true`
`phone_number`	true	Phone number in E.164 format
`identity_type`	false	Initiate calls through groups (Office, Department, or Call Center). The specified values are Office - `Office` Department - `OfficeGroup` Call Center - `CallCenter`
`identity_id`	false but required if `identity_type` is included	The office, department, or call centre ID
`custom_data`	false	Data to associate with the call. This data is passed back in call events. Maximum 2000 characters.
`outbound_caller_id`	false	Can be used instead of identity_type and identity_id to determine the target of the call. Defaults to Identity_id if used together.

Example:

<CTI_iframe>.contentWindow.postMessage({
  'api': 'opencti_dialpad',
  'version': '1.0',
  'method': 'initiate_call',
  'payload': {
    'enable_current_tab': false,
    'phone_number': '+15555555555',
    'identity_type': 'CallCenter',
    'identity_id': 1234567,
    'custom_data': 'any string'
    'outbound_caller_id': '+18005550970',
  }
}, 'https://dialpad.com');

call_ringing

This message is posted by Dialpad when an inbound call starts or finishes ringing. Use this message to open the CTI window for the user to answer the call. The payload of this method has the following parameter:

Parameter	Data Type	Description
`state`	string	Set to `on` when the call starts ringing and to `off` when the ringing ends. Two messages are sent per call.
`id`	int	call id - a unique number ID automatically assigned to each call
`contact`	object	This is the contact involved in the call. It will contain the following pieces of info: `phone`: phone number `type`: User/Local/Nylas/Google/Microsoft `id`: Unique contact ID `email`: Associated email `name`: Contact name
`target`	object	This is the ‘target’ that the Dialpad user dials or receives a call from. It will contain the following pieces of info: `phone`: phone number `type`: User/Office/Department/Staff/Room/Call Center `id`: Unique target ID `email`: Associated email `name`: Contact name
`internal_number`	string (E164 phone)	The phone number of the target.
`external_number`	string (E164 phone)	The phone number of the contact.

Example: Dialpad will post such message to the component that embeds the CTI.

window.parent.postMessage({
  'api': 'opencti_dialpad',
  'version': '1.0',
  'method': 'call_ringing',
  'payload': {
    'state': 'on',
    'id': 5747322335264768,
    'contact': {
        'id': 'http://www.google.com/m8/feeds/contacts/[email protected]/base/21042cfc8b367347',
        'phone': '+16043111111',
        'type': 'Google',
        'name': 'test contact',
        'email': '[email protected]'
    },
    'target': {
        'id': 5908860123456789,
        'phone': '+16010123456"',
        'type': 'User',
        'name': 'exampe user',
        'email': '[email protected]'
    },
    'internal_number': '+16010123456',
    'external_number': '+16043111111'
  }
}, '*');

hang_up_all_calls

This message is posted to Dialpad. It will end all ongoing calls targeting the user. There is no payload for this method.

Example:

<CTI_iframe>.contentWindow.postMessage({
  'api': 'opencti_dialpad',
  'version': '1.0',
  'method': 'hang_up_all_calls',
}, 'https://dialpad.com')