Talk messenger methods

When the Talk messenger widget is enabled on your website, you can choose to control it’s behavior programmatically.

Depending on your needs, the messenger methods described on this page can be:

• added to your website’s JavaScript and called when the Talk messenger widget has loaded.
  Or
• added to your website’s tracking code, to execute the commands when the capture script (and the Talk messenger widget) is loaded.

A full list of the available methods and events is located at Talk JavaScript API.

Prerequisites

Firstly, ensure that the Talk messenger widget is turned ON in Ortto, via Settings > Talk messenger.

Add Talk messenger methods to your website’s JavaScript

Any of the available Talk methods and events can be added to your website’s JavaScript.

The Talk messenger widget loads asynchronously, so you may wish to use the talk.ready flag to check whether it is already loaded:

javascript
 
//talk.ready flag
window.ap3c.talk.ready;

//print to notify when ready
const notifyWhenReady = () => {
  console.log('ready');
};

then, to be notified, listen for the ready event:

javascript
 
//notify when ready
window.ap3c.talk.addEventListener('ready', notifyWhenReady);
//stop notifying
window.ap3c.talk.removeEventListener('ready', notifyWhenReady);

When the widget is ready, you can add any of the following methods to your site’s JavaScript to modify the widget’s behavior:

javascript
 
//open the widget
window.ap3c.talk.execute('open');
//close the widget
window.ap3c.talk.execute('close');
//hide the widget
window.ap3c.talk.execute('hide');
//show the widget
window.ap3c.talk.execute('show');

Start a Talk conversation with an initial message

You can configure the Talk messenger widget to start a conversation using a predefined message sent by the customer or visitor. 

For example, you might want to have website visitors click a button which requests a call from your Sales or Support team. In this example, the button text says “Call me”. You can bind a click handler to the button to call the following command:

javascript
 
ap3c.talk.execute('start-conversation', {initialMessage: '<initial message>'})

Using our “Call me” example, the command would look like:

javascript
 
ap3c.talk.execute('start-conversation', {initialMessage: 'Call me'})

When a customer or visitor clicks on the “Call me” button, it will start a conversation where the initial message is “Call me”. From there, your Sales or Support agent can carry on the conversation as usual.

Add Talk messenger commands to your tracking code

If you are using commands that include ap3c.talk.execute, e.g. window.ap3c.talk.execute('show');, you may want to run those commands in your tracking code instead. This might be necessary if the Talk messenger widget is loading slowly on your website and ap3c.talk.execute() is not yet available (undefined).

Adding commands to the tracking code will ensure that your commands are called when our capture script (and therefore the Talk messenger widget) is loaded, and avoids calling non-existent Talk methods.

You can add commands to the push method of the ap3c.cmd array of the tracking code.

For example, you want to change the chat icon to have a seasonal theme. You can add a set:style command to ap3c.cmd.push, similar this:

javascript
 
ap3c.cmd.push(() => ap3c.talk.execute('set:style', { <add styling here> }));

Another example shows commands to notify when the Talk messenger widget is ready:

javascript
 
      ap3c.cmd.push(() => {
        const setReady = () => {
          const readyStateEl = document.getElementById("js-ready-state");
          readyStateEl.textContent = "ready";
        };
        if (window.ap3c.talk.ready) {
          setReady();
        } else {
          window.ap3c.talk.addEventListener("ready", setReady);
          window.addEventListener("beforeunload", () => {
            // to remove event listener, use window.ap3c.talk.removeEventListener()
            window.ap3c.talk.removeEventListener("ready", setReady);
          });
        }
      });

Hide the Talk messenger widget by default

You can set the Talk messenger widget to be hidden by default, so you can programmatically open it when ready.

To do so, add the hiddenOnLoad: true option to the talk field of your tracking code’s ap3c.init method. For example:

javascript
 
ap3c.init('<Your capture key>', 'https://capture-api-us.ortto.app/', {
    talk: { hiddenOnLoad: true },
});

You can then run the show and hide methods when you want to show/hide the Talk messenger widget on the page:

javascript
 
//show the widget
window.ap3c.talk.execute('show');
//hide the widget
window.ap3c.talk.execute('hide');


Modify the Talk messenger widget icon container

If required, you can modify the Talk messenger widget icon container like so:

javascript
 
  container: {
    backgroundColor: 'red',
    border: '1px solid blue',
  },
});

You can also customize the chat icon by using the following CSS selector and applying your own styling. 

css
 
#ap3-talk-widget-ui::part(chatButton) {
/*** CSS here ***/
}