Integrating Talk to a web page

LeadDesk Talk extends LeadDesk voice to any tool you use. If you are working daily with a CRM, for example, you can accompany it with Talk to make it easy to call to your customers with clear voice quality. Talk’s minimal footprint fits nicely into any UI, so it is a great partner when your work is mainly done with other tools and you want voice on top of them.

LeadDesk Talk iframe

First, LeadDesk Talk needs to be added to the webpage as an iframe.

  • – The iframe element must have a unique id and allow the use of the microphone.
  • – The iframe source (src) can be set to any LeadDesk login URL that the agent can use to log in. The agent must have an account that has the Talk profile enabled.
  • – The recommended dimensions for the iframe are 400px x 800px, but the user interface will adjust to any iframe size.

 <iframe
    id="LD_talk"
    title="LD_talk"    
    allow="microphone *"
    src="https://login-ce2.leaddesk.com/"
    width="400"
    height="800"
  ></iframe>

Window: postMessage() Web API

LeadDesk Talk can be integrated to any website using postMessage Web API (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). This API lets any web application communicate with Talk application.

Supported messages sent from Talk via postMessage API:


const MessagesFromTalk = {
  Login: 'login',
  Logout: 'logout',
  Call: 'call',
  Connected: 'connected',
  Disconnected: 'disconnected',
  Completed: 'completed',
  Sms: 'sms',
  Error: 'error',
  Jwt: 'jwt'
};

 

Message name Purpose and Payload
Login Add a listener inside your application to be called when a login event happens. Can be used to enable click-to-call inside your application or to resize the iframe window.


{
  action: MessagesFromTalk.Login;   // e.g. 'login'
  language: string;                 // e.g. language code ('en')
  origin: string;                  // e.g. https://login-ce2.leaddesk.com/
}
Logout Add a listener inside your application to be called when a logout event happens. Can be used to disable click-to-call inside your application. Agent is logged out and cannot make calls.


{
  action: MessagesFromTalk.Logout; // 'logout'
}
Call Add a listener inside your application to receive information about a new ringing call. The call is in ringing state.


{
  action: MessagesFromTalk.Call;    // 'call'
  id: number;                       // 123
  number: number | string;          // phone number
  direction: string;                // 'in' or 'out'
  ringStart: string;                // call ringing start time in format “yyyy-mm-dd hh:mm:ss”
}
Connected Add a listener inside your application to receive information about an answered call. The call is in connected state.


{
  action: MessagesFromTalk.Connected; // 'connected'
  callStart: string;                  //  call talk start time in format “yyyy-mm-dd hh:mm:ss”
}
Disconnected Add a listener inside your application to receive information about a disconnected call. If the call was never connected, the call was not answered (no callStart time). The call is in disconnected state.


{
  action: MessagesFromTalk.Disconnected; // 'disconnected'
  callEnd: string;                       //  call talk end time/hang-up time in format “yyyy mm-dd hh:mm:ss”
  recordUrl?: string; // (optional)      //  URL to the voice recording of the ended call
}
Completed Add a listener inside your application to receive information about the completed call. All post-call handling is done and the call is finalized.


{
  action: MessagesFromTalk.Completed; // 'completed'
  call: {
    id: number;                       // 123 
    direction: string;                // 'in' or 'out'
    to: string | null;                // phone number
    from: string | null;              // phone number
    answered: boolean;                // true/false
    callStart: string | null;         // call talk start time in format “yyyy-mm-dd hh:mm:ss”
    talkStart: string | null;         // talk start time in format “yyyy-mm-dd hh:mm:ss”
    callEnd: string | null;           // call end time in format “yyyy-mm-dd hh:mm:ss”
    duration: number | null;          // call duration in seconds
    comment: string | null;           // comment if added from the Agent
    recordUrl: string | null;         // URL to the voice recording of the ended call
    reason: {
      name: string;                   // selected call ending reason
      logicalName: string | null;     // selected call ending reason
    } | null;
}
SMS Add a listener inside your application to receive information about a sent SMS.


{
  action: MessagesFromTalk.Sms; // 'sms'
  sms: string;                  // text message
  callId: number | undefined;   // call id if sms is related to call
}
Error Talk does not specifically send back return values when sending actions to Talk, and error handler should be used to determine if these actions were unsuccessful. These will be printed to the developer console as default.


{
  action: MessagesFromTalk.Error;  // 'error'
  message: string;                 // 'general' or 'unknown error'
}
JWT Add a listener inside your application to receive an authentication token that is signed with audience of ‘cti’ if needed.


{
  action:  MessagesFromTalk.Jwt; // 'jwt'
  jwt: string;                   // jwt token 
}

Supported messages that can be sent to Talk via postMessage API


const MessagesToTalk = {
  UseSettings: 'useSettings',
  Call: 'call',
  Answer: 'answer',
  Hangup: 'hangup',
  Reset: 'reset',
  SetStatus: 'setStatus',
  SetMetadata: 'setMetadata',
  GetJwt: 'getJwt'
};

Message name Purpose and Payload
UseSettings Configures how Talk application behaves with custom settings. Talk is ready to receive these settings at any time when the user has logged in. Between the login and logout events. Sets some specified settings for Talk that alters the functionality. Only settings that are provided are used, otherwise the functionality is default.


{
  action: MessagesToTalk.UseSettings; // 'useSettings'
  preventManualCalling: boolean;      // true/false => Makes the number input field disabled
                                      //               so that user cannot manually enter a number.
}
Call Make a new call in Talk or alternatively only insert the number to the input field. Unsuccessful call will send an error event. Inserts a number to the input field and then makes a call if parameter ‘autocall’ is set true. Number will be converted to string.


{
  action: MessagesToTalk.Call;   // ' call'
  number: string;                // phone number
  autocall: boolean;             // true/false for auto calling the number 
}
Answer If there is a ringing inbound call, answers it.


{
  action: MessagesToTalk.Answer;  // 'answer'
}
Hangup Hang up an incoming, ringing or currently ongoing call.


{
  action: MessagesToTalk.Hangup; // 'hangup'
}
Reset Resets talk to a default state: clears the number input field and set agent availability to the previous setting if changed with setStatus message. It is recommended to use reset message to remove the disabled state after the call if it is used. Otherwise, this can be used to just clear the number input.


{
  action: MessagesToTalk.Reset; // 'reset'
}
SetStatus Sets the agent availability so that it cannot receive or make calls.


{
  action: MessagesToTalk.SetStatus;  // 'setStatus'
  enabled: boolean;                  // true/false for enable/disable Talk application
}
SetMetadata Set a metadata object that contains information coming outside the Talk such as contact information. Used in SMS to fill in contact information.


{
  action: MessagesToTalk.SetMetadata;  // 'setMetadata'
  metadata: {
    [key: string]: any;                // any key/value pairs
  }
}
GetJwt Request an authentication token that is signed with audience of ‘cti’. It is returned in the ‘jwt’ event.


{
  action: MessagesToTalk.GetJwt;  // 'getJwt'
}

Example

1. Embed the LeadDesk Talk iFrame

First, you’ll need to embed the LeadDesk Talk iframe into your web application. Make sure to set the following details for the iframe:

  • – ID: Assign a unique ID to the iframe (e.g., ‘LD_talk’).
  • – Title: Set an appropriate title for the iframe.
  • – Allow Microphone Permission: Ensure that the iframe has permission to access the user’s microphone.
  • – Source (src): Specify the source URL for the iframe.
  • – Width and Height: Define the dimensions of the iframe.

 <iframe
    id="LD_talk"
    title="LD_talk"    
    allow="microphone *"
    src="https://login-ce2.leaddesk.com/"
    width="400"
    height="800"
  ></iframe>

2. Log in to your LeadDesk account

Make sure you have a valid LeadDesk account. Log in using your credentials.

3. Listen for the ‘Login’ message

Once the iframe is loaded and the user logs in, LeadDesk Talk will send a ‘login’ message. This message contains information such as the user’s preferred language and origin.

4. Send messages to LeadDesk Talk

To interact with LeadDesk Talk, you can send messages from your web application. First, obtain a reference to the iframe using JavaScript:


const iframe = document.getElementById('LD_talk').contentWindow; // Replace 'LD_talk' if another id is set on the iframe

Next, send a message for example to start a call (adjust the parameters as needed):


iframe.postMessage(
    {
        action: 'call',
        number: '+123456789', // Replace with the desired phone number
        autocall: true,
    },
    'https://login-qed-fi1.leaddesk.com' // Replace with the correct origin
);

The first argument to postMessage is the payload (in this case, the call action), and the second argument is the origin (retrieved from the ‘login’ message in step 3).

Remember to replace placeholder values (such as phone numbers and URLs) with actual data relevant to your use case. With these steps, you’ll successfully integrate LeadDesk Talk into your web application!