Category Archives: API

API, CRM, IT Guide

Scripting Pane: Display Phonecall

You can display the current phonecall activity in the Scripting Pane. This is useful to be able to enter phonecall notes and result without having to switch away from the main customer record in CRM.

scriptingPanePhonecall

You do this by defining the script URL as a custom HTML page that will receive all phonecall ID and then redirect to the phonecall itself. There is a sample of that initial custom page code here (view page source when it opens): dtAssociatedPhonecall. Also, this is included in the CRM Solution now so you can simply use https://yourcrmdomain.crmXX.dynamics.com//WebResources/cts_dtAssociatedPhonecall

TIP: If you want to display some other entity, for example the regarding entity, then you can use the parameters passed to the splitscreen page to re-direct to it. the full list of parameters passed to the splitscreen page is HERE

The script URL is defined on a per DNIS (inbound) or queue (dialer outbound) basis, as shown below

scriptingPansDnisUrl

NOTES

  • You will want to customise the phonecall form to improve legibility as the Scripting Pane is fixed at 33% of the parent window width.
  • Alternatively, you could make a special phonecall form and specify the formid in the extraqs parameter of the URL you redirect to. You might also consider adding navbar=off&cmdbar=false to the URL to hide the navigation and command bars to give you more space.
  • Test with your users to make sure autosave is working correctly, or they are happy to use a SAVE button.
  • Using the Dynamics Telephony Client API, it is possible to make a Save & Close button that would save the phonecall and close the DT window.
  • If users will enter notes, then define the default Phonecall Description as blank ( DT Menu > Settings > Advanced Configuration : Phonecall Description )
  • Similarily the Phonecall Subject. ( DT Menu > Settings > Advanced Configuration : Phonecall Subject )

API, CRM, IT Guide

Use Custom Forms

Dynamics Telephony allows you to specify a Custom URL to use for your outbound or inbound calls. So, if you have designed a custom form for users to process inbound or outbound calls, then you can have Dynamics Telephony pop that form for the user.

You can specify different Custom URLs for inbound and outbound. And you can also specify a set of conditions for when to use the Custom URL, such as only when no match for the caller is found in CRM, or only when the caller is a contact, etc.  You can specify multiple Custom URLs, each with a different set of conditions attached.

In addition, Dynamics Telephony will pass a set of parameters to your page at the Custom URL. These are described below.

How to set up a custom URL

You configure the URL to pop, along with the conditions for the pop, as a dialerKVTable entry, with these values:

Owner. This can be any owner.
Scope. Only “global” has been tested. This means it applies to all users. In future, we may support putting a users name here to make it specific only to that user.
Parent. Leave blank always
Name. Always customURL_Rule. It is case sensitive so type as shown.
Key. A number. Start at 1 for the first rule, 2 for the second etc. The rule with the lowest Key number that the condition (next section) yields TRUE will determine the pop. If no rule yields TRUE, then the default contact, lead etc. is popped. NOTE: the sorting is text based so you should use 2 digits for all numbers, like 01 or 12 etc.
Value. Format condition=>url-to-pop
url-to-pop can be any valid URL. Only webresources served by the CRM have been thoroughly tested. The keyword default can be used instead of a URL to pop the default CRM form for the matched entity.
condition is one or more conditions where you specify such things as applicable entity (fromParty.Key=contact, lead, account.), number of matches (lookupCount=0 or 1), DNIS (dnis=1234), and direction (inbound or queue)

See next section for examples of Value

Some examples of Value

direction=queue=>file:///C:/_cts/Fast%20n%20Lite/page.html

direction=inbound&&fromParty.Key=contact&&lookupCount=1=>https://yourCrm.crm.dynamics.com//WebResources/dot_/CPO/CP.html

direction=inbound&&lookupCount=0=>https://yourCrm.crm.dynamics.com//WebResources/dot_/CPO/CP.html

direction=inbound&&fromParty.Key=account&&lookupCount=1=>https://kotsovolosdev.crm4.dynamics.com//WebResources/dot_/CPO/CP.html

direction=inbound&&dnis=1234=>default

Parameters passed to the Custom URL

TIP: When you run a test call, check the Dynamics Telephony log file (DT Menu > Log File) to see the URL and it’s parameters. Search in the log file for oCustomUrlRules and you will see the URL a line or two after that.

Parameters
Data=
state, e.g. incoming
type, e.g. phonecall. Only phonecall supported
phoneCallID, e.g. 7e2a5311-be86-e911-a84d-000d3ab0d976
direction, e.g. inbound, or queue (outbound)
telephoneNo, e.g. 00353868561713
dnis, e.g. 1234
dnisName, e.g. DEV
agentType, e.g. systemuser
agentId, e.g. dbe7f238-1d8d-e911-a819-000d3aba212d
customerType, e.g. contact
customerID, e.g. dbe7f238-1d8d-e911-a819-000d3aba212d
ReType, e.g. contact
ReId, e.g. dbe7f238-1d8d-e911-a819-000d3aba212d
dtCallId, e.g. e8393a0f-be86-e911-a847-000d3ab0d281
agent, e.g. Test+Agent06
fullName, e.g. My full name
description, e.g. description+text+from+phonecall
customText, e.g. text from a phonecall custom field called new_customtext
subject, e.g. inbound+call+with+DNIS+DEV

Sample URL popped with parameters
CP.html?Data=state%3Dstart%26type%3Dphonecall%26phoneCallID%3D30240805-03be-e911-a82f-000d3ab71acc%26direction%3Dqueue%26telephoneNo%3D6946186715%26dnis%3D%26dnisName%3D%26agentType%3Dsystemuser%26agentId%3Da661cc8a-eb7a-e911-a824-000d3ab70af3%26customerType%3Dcontact%26customerID%3De79beb12-998b-e911-a825-000d3ab70627%26ReType%3Dcontact%26ReId%3De79beb12-998b-e911-a825-000d3ab70627%26dtCallId%3D7f22a4f1-7fe6-e911-a838-000d3ab713ee%26agent%3DDyn+Crm06%26fullName%3D%CE%9D%CE%95%CE%9A%CE%A4%CE%91%CE%A1%CE%99%CE%91+%CE%9A%CE%95%CE%A6%CE%91%CE%9B%CE%9F%CE%9D%CE%99%CE%9A%CE%91%26description%3D%26  %3D%26subject%3D%CE%95%CE%9A%CE%A3-06441+-+MRKT-0010324

API, CRM, IT Guide

Asterisk Queue-names Integration

Dynamics Telephony can get and use the name of the Asterisk Queue that an inbound call came in on. Example use cases are:

  • You want to pop a particular form based on the Queue-name
  • You want to auto-populate the Queue-name into a custom field – e.g. in a phonecall, lead or case (incident)
  • You want per-queue statistics in CRM
  • You want to filter the customer search using Queue-name (e.g., if you have a queue per “brand”)
  • You want to search one of multiple CRM instances based on queue name.

Setting up Asterisk to pass queue-name

You have to set up Asterisk so that the queue-name is passed to Dynamics Telephony. You do this by pre-pending the queue-name to the callers name. You do this with a pattern so that Dynamics Telephony can parse out the queue-name. The standard pattern Dynamics Telephony accepts from Asterisk is D:queuename:number, for example

D:Support:070989887889

However, you can use another pattern if you wish by changing the RegEx in Dynamics Telephony Settings > Provider Configuration: DNIS RegEx. For the above pattern, use DNIS RegEX   D:(.+?):

For example, in freePbx, you set the prefix in Applications > Queues > [pick a queue] >General > CID Name Prefix = D:My Test Queue:
asterisk_queue_CID_prefix

Setting up Dynamics Telephony to accept Queue-name

Dynamics Telephony will parse the queue-name, set up in above section, to a DNIS in Dynamics Telephony. DNIS stands for Dialed Number Identification Service. So it identifies the destination the caller reached. The queue in this case.

Set up a DNIS in Dynamics Telephony with the same DNIS and Label as the queue-name (case sensitive), as shown below.

NOTE: If the incoming queue-name does not have a matching DNIS definition, the incoming queue-name will still be saved in the DNIS field of the phonecall.
dnis_setup

Now what can you do?

Some of these require use of the Dynamics Telephony API – See here for more

– The inbound call dialog will show the DNIS name when a call arrives via that queue. You can also have a per-DNIS color and logo.

– To pop a particular form, your JavaScript running in the originally popped form can query Dynamics Telephony via the API to get the DNIS and change the form.

– You can show a different script in the Dynamics Telephony Scripting Pane depending on the DNIS.

– To auto-populate a custom field, your JavaScript running in the originally popped form can query Dynamics Telephony via the API to get the DNIS and populate the field

– The Dynamics Telephony Entity for statistics (dialerCall) will now have the DNIS as a field

– You can auto-populate the phonecall Description field, or the auto-added Note, by using the placeholder <<dnis>> in Dynamics Telephony Settings > General : Phonecall Description or Other Party Note

– You can direct the CRM search on inbound call to a particular CRM by picking from the list in the DNIS configuration.

– You can filter inbound call search results to only those where queue-name matches any field in the entity. You set this in Dynamics Telephony Settings > Inbound > DNIS Filter, with a value something like {“entity”:”contact”, “attribute”:”new_brand_name”, “type”:”string”}

API

Simple API example – walk-through

This simple example will popup a window that displays the DT events as they happen. It works in conjunction with a phonecall form.

IMPORTANT: You MUST call RegisterForEvents() first, to be able to use any of the Dynamics Telephony functions, and get the events.

1.  Make a file with Notepad called dt_SimpleEG.js and paste in the following code:

var wndEvents = null; // A variable to hold the popup window reference.
var fnDTEventHandler = function (ev) { //Our DynamicsTelephony Event Handler.
 try {
 if (wndEvents == null) {
 //first time per call, wndEvents will be null, and the popup window will need to be re-created
 wndEvents = window.open('', 'dtEventsWindow', 'menubar=1,resizable=1,status=1,width=750,height=250');
 wndEvents.document.body.innerHTML = '<h1>Dynamics Telephony Events</h1>';
 }
 // add this event to the list...
 wndEvents.document.body.innerHTML += '<div>' + ev.dtEventArgs.toString() + '</div>';
 } catch (e) { }
};
// Register for Events with DynamicsTelephony using our Handler 'fnDTEventHandler'.
DynamicsTelephony.RegisterForEvents(fnDTEventHandler);

2.  Go to CRM > Settings > Customizations > Customize the system and add the above file as a Webresource, per this snap:

simple_api_new_ws

3. Add the above javascript library, and the core DT javascript library to the phonecall form, per this snap:

simple_api_form_libraries

4. Publish all customizations

5. Run DT and do a click-to-dial or take an inbound call or an outbound campaigncall. NOTE these need to be configured to pop the phonecall form for the javascript to run.

simple_api_dt_events_page

API

DT Server Entities for integration

The following entities can be used for reports or triggered on for server-side integration.

cts_dialerCall – one entry for each phone call processed by DT. The same entry is used for the lifetime of the phone call. Can be linked to the associated CRM phone call. Fields include: agent (CRM user), calls, no answers, busies, connects, didConnect, direction, phone number, phone call ID, status (open, retry, closed), subject (e.g. campaign name), to (full name), computedOutcome (for your use – to change the outcome), aborts (selected an outcome that did not connect and isConnectXorAbort true on the selected outcome)

cts_dialerCallEvent – one entry for each event including: talk, ring, idle, error on dial, busy, no answer,  with fields: direction, duration, event name, phone number and dialer call ID in cts_dialerCall.

cts_dialerCallResult – one entry every time a call gets an outcome with fields including: agent (CRM user), dialer call ID in cts_dialerCall, direction, phone number, result (outcome as chosen by agent or automatically), and subject (e.g. campaign name)

 

 

API

DT Client API Overview

Dynamics Telephony Client includes an API that can be used for such use cases as:

  • Trigger a CRM workflow based on outcome/disposition chosen for an outbound call
  • Display a particular Form in CRM based on the queue the customer called in on
  • Auto-populate a field in the From with the queue name
  • Change the CRM form based on the outcome/disposition chosen for an outbound call
  • Auto-promote a lead to an opportunity based on the outcome/disposition chosen for an outbound call
  • Control the wrap time / end of wrap from Javascript in the CRM form
  • Allow a CRM form to set the Outcome in Dynamics Telephony.

For a quick get-started with a simple API walk-through, see here

The following can be used by javascript running in any DT call tab. Any data refers to the call currently (or most recently) active in that call tab. All method calls are pre-pended with “DynamicsTelephony.”  For example to register for DT events:

// Create a Callback Function to be triggered 
// on call events
var fn = function (evtData) {
var oCall = DynamicsTelephony.parseEventArgs(evtData)
/*  
   TODO: implement your code here
*/
};

// Register for events...
DynamicsTelephony.RegisterForEvents(fn);

Or to get the details of the current call:

var oCall = DynamicsTelephony.GetCallDetails();
Dynamics Telephony Methods
DynamicsTelephony.RegisterForEvents(fnEventHandler)

Registers to receive telephony callbacks from DT in the function “fnEventHandler”. “fnEventHandler” should have the format:

var fn = function (evtData) {};

Where the evtData is the event payload passed from DT which can be objectified using the method “parseEventArgs()” below.

DynamicsTelephony.parseEventArgs(e)

Convert an events payload (evtData in the above EG)  into a javascript object with the following properties:

  • state – The current state of the call
  • stateTime – The Datetime this state occurred
  • type – always “phonecall” at present
  • id – the guid of the CRM phonecall for this call
  • direction – one of  inbound, outbound, clicktocall, transfer or ccOutbound
  • phone – The phone number associated with the current call
  • outcome – No Answer, Voice Mail, etc. Any configured outcome
  • fromType – agent, lead, contact, account, case etc…
  • fromId – ID for above
  • toType – agent, lead, contact, account, case etc…
  • toId – ID for above
  • dtCallId – ID to link to dialerCalls table to get attempts, for example
  • isCallback – true or false, indicating where the call is a callback.
  • retryDatetime – The retry date/time of the call (Format “YYYY-MM-DDTHH:MM:SSZ”)
  • dnis – ^The number the customer originally dialed
  • queueDn – ^The phone number of the queue in the Contact Center
  • agentId – ^The agent ID in the Contact Center
  • extension – ^When available, the agents phone number that the call is on.

^When Available

DynamicsTelephony.GetCallDetails()
Returns data on the current call,  in an object the same as described in parseEventArgs() above.
DynamicsTelephony.dial(number)

Dials the “number” passed on the current call tab.

DynamicsTelephony.holdresume()

Holds / Resumes the call on the current call tab.

DynamicsTelephony.transferBlind(number)

Blind transfers the call on the current call tab to the “number” provided.

DynamicsTelephony.transferConsult(number)

Consult transfers the call on the current call tab to the “number” provided.

DynamicsTelephony.transferComplete(callTab)

Completes the transfer of the call on the current call tab to the call on the call tab provided. The current call tab must have a call in the active (not held) state and the call on the provided call tab must be on hold for successful transfer.

DynamicsTelephony.conference(callTab)

Conferences the call on the call tab provided to the call  on the current call tab. The current call tab must have a call in the active (not held) state and the call on the provided call tab must be on hold for successful conference.

DynamicsTelephony.answer()

Answer the call on the current call tab.

DynamicsTelephony.release()

Release / Hang-up  the call on the current call tab.

DynamicsTelephony.agentReady()

Put the agent in ready state.

DynamicsTelephony.agentNotReady()

Put the agent in not ready state.

DynamicsTelephony.playWaveFile(filename)

Plays the file “filename” into the call on the current call tab.

DynamicsTelephony.sendDTMF(digit)

Sends the DTMF tone(s) in “digit” into the call on the current call tab. “digit” can be one or more of the following: 0123456789*#

DynamicsTelephony.logThis(text)

Sends the text to the Dynamics Telephony log file. Useful for debugging. Please remove when in production.

DynamicsTelephony.setOutcome(outcome_name)

Sets the outcome in Dynamics Telephony as if the agent had clicked on it in the outcome list in Dynamics Telephony. The outcome_name is the same as the defined outcome name – case-sensitive.

DynamicsTelephony.setCallEnd()

Fast-forwards Dynamics Telephony to the end of the call. This is the same as if the agent clicks FFWD during Wrap time. If the windows are set to auto-close, then the window will close.

Telephony Events

The event handler is triggered for each of the following telephony state changes:

  • preview – DT or CC Dialer call presented to agent and preview timer started
  • incoming – Inbound call or CC Dialer call presenting to agent
  • ringing – An outbound call is dialed and waiting for the customer to answer
  • talk – the call is active
  • idle – The call has been released, wrap timer may be running
  • end – The wrap time has expired or agent has manually moved on to the next call

The event payload contains the same data as returned from DynamicsTelephony.GetCallDetails() and this can be parsed to a javascript object using:

var oCall = DynamicsTelephony.parseEventArgs(evtData);

 

See here for code samples.