Category Archives: API

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 is

D:queue_name:callers_number_or_name

However, you can use another pattern if you wish by changing the RegEx in Dynamics Telephony Settings > Provider Configuration: DNIS RegEx.

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.
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.

– 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”}

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.

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

 

 

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)

 

 

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

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*#

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.