PostMessages

Note that this API works with the Outbound and Legacy Outbound UI modes only!

Contact support for a complete list of icons.

Controlling LeadDesk from within Customer Contact Card

A customized contact card can communicate with LeadDesk using a simple postMessage Javascript command. For example:


function hangUp() {
parent.postMessage(JSON.stringify({“action”:“hangup”}), document.referrer);

}

function selectReason(reasonId) {

parent.postMessage(JSON.stringify({“action”:“select_reason”,“params”: {“id”: reasonId}}), document.referrer);

}

Please note that as the document.referrer is used, one the user traverses to another page inside the original IFrame, the original document.referrer value must be passed to that page and also to next pages. That way the targetOrigin parameter of postMessage can be set accordingly and the messages reach the intended target. Supported commands

Supported Actions

Action (”action”)
Parameters (”params”)
Description
call 
{
  "phone_number": {phone}, 
  "call_id": {call_logs_id}, 
  "customer_id": {customers_id}, 
  "auto_call": true
}

Making a call with phone number OR call_logs.id OR customers.id

 

Calling plain number will only work when call dialog is already open. This means that the command should only be called from call dialog based applications (custom order forms and call dialog minireports)
close 
{
  "target": "call_dialog"
}
Close the call dialog
close 
{
  "target": "full_window_campaign_url"
}
Close the full window campaign URL (call dialog remains open)
continue_call_recording Continue call recording (works only with LeadDesk application)
delete_call_log 
{
  "call_log_id": <the id of the call log row>
}
Deletes row from call_logs database table by given id. Note that call state must be no_answer for this to work.
force_full_window Force full window display for the iframe immediately (even if there is no call ongoing). This should not be generally used as this can break the UI easily. Use “request_full_window” instead.
get 
{
  "id": <identifier that will be returned with the response>,
  "name": <name of the property to retrieve>
}

Generic get command for retrieving different properties from the system. See Get Properties section for more detailed instructions. Value is delivered though a getResponse post message coming back to the caller.
hangup Hang up the active call
hold_call Puts the call on hold
make_secondary_call 
{
  "phone_number": <number to make the secondary call to>
}
Opens phonebook dialog, fills given number into phonebook’s number field and makes a secondary call of active call to given phone number. If request is not valid secondaryCallFailed event will be sent back with given number. See events table for more details.
modify_contact 
{
  "first_name": "<first name>",
  "last_name": "<last name>",
  "ssc": "<social security number>",
  "title": "<title>",
  "www": "<url>",
  "birth_year": <year>,
  "gender": "<gender>",
  "address": {
    "country": "<country>",
    "city": "<city>",
    "postal_code": "<postal code>",
    "street_address": "<street address>"
  },
  "email": "<email address>",
  "other_infos": [
    {
      "id": 1,
      "value": "<value for other field 1>"
    },
    {
      "id": 2,
      "value": "<value for other field 2>"
    },
    {
      "id": 3,
      "value": "<value for other field 3>"
    },

    <... other info fields from 4 to 34... >

    {
      "id": 35,
      "value": "<value for other field 35>"
    }
  ]
}
 Modifies current contact’s details in call dialog with given values. Supported contact values are listed in parameter’s section. Only changed values needs to be provided.

 
notify 
{
  "message": <message to show to user>,
  "style": {
    "icon": <icon name from glyphicons basic set e.g. glyphicons-leaf>,
    "text_color": <css color for text and icon>,
    "background_color": <css color for notification background>
  }

}

Notify the user with a text inside a banner on the bottom of the screen. The user can dismiss the notification by him/herself. Only one notification can be visible at the same time. Latest notification will immediately replace the previous one.

Only the message parameter is mandatory. If the message is empty or omitted then nothing will be shown, but this can’t be used to dismiss the previous notification. If style is omitted then default styling will be used.

Example of what the notification can look like:
observe_events 
{
  "types": [<event types to observe or * for all>],
}
 LeadApp can use this command to start receiving events from the machine side. By default the LeadApps don’t get any events unless they request them. The first campaign URL is the only exception in this case, but more of that in the events section. A new request will overwrite any previous observer settings for the current LeadApp. So you can stop listening to events by sending an empty array of types, for example.

Available event types:

  • * – all possible events (default)
  • call_dialog – call dialog changes
  • call_line – modem line changes ok

See the events section for detailed information on different events.
open_phonebook Opens phonebook dialog. If request is not valid, then failedToOpenPhonebook event will be sent back. See events table for more details.
pause_call_recording Pause call recording (works only with LeadDesk application)
request_full_window Request full window display for the iframe (will be displayed when call dialog opens if there is a call ongoing). The iframe page can issue request this immediately after loading without any risk of breaking anything.
resize_iframe 
{
  "location": <iframe location>,
  "width": <iframe width>,
  "height": <iframe height>
}
Changes a certain iframe size. If request is not valid iframeResizingFailed event will be sent back with given location, width and height. See events table for more details. The location is given as a parameter for the iframe source. This location should be used with post command to make sure that the iframe resizing is done for the right iframe. There is currently only one location which is called “sidebar” which is done for the sidebar mini report.
select_reason 
{
  "id": <the id of the reason to set>
}
Select a call ending reason by id
start_voice_receipt_recording Start voice receipt recording
stop_voice_receipt_recording Stop voice receipt recording
transfer_call 
{
  "phone_number": <number to transfer the call to>
}
Make a blind transfer of active call to given phone number. Transfer is only supported with Application using VoIP, and Browser calling using SIPjs engine. If request is valid, then either callTransferred or CallTransferFailed event will be sent back with given number. See events table for more details.
unhold_call Unholds the call

 

 

Get Properties

LeadApp can request properties from machine by using a get action. Since post messages can’t return values immediately, the response is sent asynchronously to the requester using a getResponse type message (see responses section).

List of available machine properties that can be read with the get action:

Property Name
Property Type
Description
call_line_state string Call line state as in the events. Possible values are:

  • callLineRinging
  • callLineIdle
  • callLineOn
call_dialog_visible boolean Check whether the call dialog is currently visible (=open) or not

 

For any unknown property will be responded with a null value. Please do not make any assumptions based on this logic as the behavior can change in the future.

Responses

Responses are messages sent from machine to LeadApp in response to the a request from the LeadApp. Response is sent only to the LeadApp that sent the original request. This is the main difference between events and responses. Usually the responses include an id from the request that can be used to bind the request and response together since both are asynchronous messages.

Type
Data
Description
 
getResponse
 
{
  id: <request id. If omitted then null>,
  name: <name of the requested property>,
  value: <value of the property>
}
Response to get action. Id parameter will match the id given in the get request. See the Get Properties section for a list of supported properties.

Events

Event are messages that are sent from machine to LeadApp when something happens or some action caused an error. By default most of the events are delivered to the first Campaign URL LeadApp when it’s visible to the user (see C1 column). Other LeadApps (e.g. minireports) can start observing certain events by requesting that from the machine by using the observe_events action. Only the rows having some category in Type column are receivable by using the observer_events command.

C1 events are only delivered to the first campaign URL iframe/LeadApp when it is visible to the user!
The first Campaign URL can request events through observe_events but when visible it can get some events twice because of the implicit observer behavior. This will be changed in the future so that if an observer request is sent then no implicit events will be sent anymore.
“type”
“data”
C1*
Type*
Description
callLineRinging 
{
  call_log_id: <active call id>
}
x call_line Event sent when an outbound phone call changes to ringing state.

NOTE! If calling with full automatic, the campaign URL never gets the initial callLineRinging event. Only subsequent events are received.
callLineIdle 
{
  call_log_id: <active call id>
}
x call_line Event sent when phone call changes to idle state. This happens every time page is initialized and when hangup is called.

NOTE! If calling with full automatic, the campaign URL never gets the initial callLineOn event. Only subsequent events are received.
callLineOn 
{
  call_log_id: <active call id>
}
x call_line Event sent when phone call changes to online (answered) state.
callLineIncoming 
{
  phone_number: <phone number that is calling in>
}
 x call_line Event sent when there is an incoming phone call (direct call, queue call or robot call). The event will be sent even if the agent might be unable to answer to the incoming call (e.g. still finalizing another call in the call dialog). But the event will not be sent when there is another call online. The event will be sent if the agent is on the Call, History or Order tab.
recStarted 
{
  file: <order recording file name without extension>
}
x Event sent when order receipt recording is started
recStopped 
{
  file: <order recording file name without extension>
}
x Event sent when order receipt recording is stopped
recCancelled 
{
  file: <order recording file name without extension>
}
x Event sent when order receipt recording is cancelled
callTransferred 
{
  phone_number: <phone number given as parameter to transfer_call command>
}
x Call transfer command was successfully passed to call engine. Call transfer might not be immediate, so it’s not guaranteed that the call is already transferred when this even is received. This event is not triggered if agent manually (from the LeadDesk UI) makes the call transfer, but we reserve the right to do so in the future. Do not make any such assumptions on external code.
callTransferFailed 
{
  phone_number: <phone number given as parameter to transfer_call command>
  reason: <error text describing the reason for failure>
}
x Call transfer command could not be completed. This event is not triggered if agent manually (from the LeadDesk UI) makes the call transfer, but we reserve the right to do so in the future. Do not make any such assumptions on external code. If the transfer_call command parameters are not correct it’s possible to not receive this event at all. List of example reasons for failure. List is not exhaustive and can change in the future.

  • error_no_active_call There is not active call ongoing to be transferred
  • error_not_supported_by_call_engine Currently used call engine does not support call transfer. e.g. application with usb dongle
  • error_transfer_data_saving_failed Could not save call transfer details into backend side. This is usually a network issue.
failedToOpenPhonebook 
{
  reason: <error text describing the reason for failure>
}
x Open phonebook command could not be completed. This event is not triggered if agent manually (from the LeadDesk UI) opens phonebook, but we reserve the right to do so in the future. Do not make any such assumptions on external code. List of example reasons for failure. List is not exhaustive and can change in the future.

  • error_no_active_call There is not active call ongoing
  • error_phone_book_feature_disabled phone_book feature is disabled
  • error_divert_feature_disabled divert feature is disabled
  • error_divert_not_supported Currently used call engine does not support divert call
secondaryCallFailed 
{
  phone_number: <phone number given as parameter to make_secondary_call command>
  reason: <error text describing the reason for failure>
}
x Make secondary call command could not be completed. This event is not triggered if agent manually (from the LeadDesk UI) makes the secondary call, but we reserve the right to do so in the future. Do not make any such assumptions on external code. If the make_secondary_call command parameters are not correct it’s possible to not receive this event at all. List of example reasons for failure. List is not exhaustive and can change in the future.

  • error_no_active_call There is not active call ongoing
  • error_phone_book_feature_disabled phone_book feature is disabled
  • error_divert_feature_disabled divert feature is disabled
  • error_divert_not_supported Currently used call engine does not support divert call
  • error_assisted_call_transfer_not_supported Currently used call engine does not support assisted call transfer. e.g. application with usb dongle
iframeResizingFailed 
{
  location: <iframe location>
  width: <iframe width>
  height: <iframe height>
  reason: <error text describing the reason for failure>
}
x Resize iframe command could not be completed. List of example reasons for failure. List is not exhaustive and can change in the future.

  • error_not_valid_size width or height is not positive number
  • error_unknown_location given location does not exists
callDialogOpened 
{
  campaign_id: <call dialog's active campaign>
}
 call_dialog Called after call dialog has become visible
callDialogClosing 
{
  reason_id: <selected call ending reason or null if none selected>
}
 call_dialog Called when call dialog is closing

C1* means that the event is sent to the first campaign URL implicitly without it requesting any events by using the observe_events command.

Type* specifies which event category the event belongs to and what type you need to use with observe_events if you want to receive those events.