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:
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 | |
| send_dtmf |
{
"sequence": <dtmf sequence >
"delay": <delay between the DTMF tones (in ms). Defaulting to 500 ms if no delay is given. >
}
|
Sends a DTMF sequence. Supported tones are 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, *, #, A, B, C, D |
| play_audio_file |
{
"url": <URL of the audio file >
}
|
Plays the given audio file for both agent and customer. Call recording and voice receipt will contain the played audio.
Supported audio file formats depend on the used browser. In theory everything <audio> is supporting is supported. In practice it is safest to use mp3 format with 8bit 22050Hz. Note: Not supported with Firefox Note: Server serving the mp3 file must set Access-Control-Allow-Origin CORS correctly as browser will otherwise not be able to play the audio file into remote stream. |
| stop_audio_file | Stops audio file playback that was started with play_audio_file command. Does nothing if there is not currently audio playing.
Note: This requires common_callmanager and call_audio_mixing features and is supported currently only in OBv2. Note: Not supported with Firefox |
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:
|
| call_dialog_visible | boolean | Check whether the call dialog is currently visible (=open) or not |
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.
|
“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.
|
|
| 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.
|
|
| 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.
|
|
| 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.
|
|
| 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.