Legacy scripts

This guide outlines the legacy Talkative scripts. As of 9th August 2021, we recommend you use the brand new widget editor within Talkative. The widget editor is designed to be self-service, but please contact support with any queries. Documentation will continue to be updated throughout 2021 as the legacy scripts are phased out.


Introduction

Your web page will need to include the Talkative scripts as well as an HTML element. 

You can generate the scripts from within your Talkative account here: https://eu.engage.app/script-generator (change EU for the appropriate server instance).


The scripts below are an illustrative example of what needs to be included in a page to enable the Talkative solution:


<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="stylesheet" href="https://files.talkative.uk/1.15.2/talkative-engage.css">
<talkative-engage id="talkative-engage" company-uuid="123e4567-e89b-12d3-a456-426655440000" queue-uuid="123e4567-e89b-12d3-a456-426655440000" primary-color="249,176,61" :voice=true :ga=true :email=true :chat=true :offline-email=true :callout=true position="right: 10%" :content-strings="{ mainTitle: { offline: 'Please leave us a message', default: 'Talk to us' }, options: { description: 'Click to talk with us!'}, cobrowse: {description: 'Get in touch and tell us the following reference number to start cobrowsing:'}, callout:{line1:'Want to',line2:'learn more?'}}"></talkative-engage>
<script src="https://files.talkative.uk/1.15.2/talkative-engage.js"></script>


Content String Defaults

AttributeTypeDefaultDescription
company-uuidString-This is the unique ID for your company. This can be found in your Talkative account.
group-uuidString-This is the unique ID for the group you want to target. This can be found in your Talkative account.
:chatBooleanFalseAllows web chat to be shown as an option to the customer.
:cobrowseBooleanFalseAllows cobrowsing to be shown as an option to the customer.
:voiceBooleanFalseAllows voice calls to be shown as an option to the customer.
:videoBooleanFalseAllows video calls to be shown as an option to the customer.
:emailBooleanFalseAllows email to be shown as an option to the customer.
:offline-emailBooleanFalseAllows an email contact form to be displayed to the customer outside of assigned business hours.
primary-colorRGB66,140,204Primary UI colour.
positionStringright:10%Specify the position along the bottom edge of the viewport. The side (right or left) as well as the value and units (px or %) must be specified. E.g. left:25% or right:200px
:calloutBooleanFalseShows a speech bubble above the UI with additional text to help draw a customer's attention. Text can be set using the :content-strings attribute.
:numpadBooleanFalseShows a numpad during calls to allow customers to navigate an IVR navigation.
:ignore-bandwidthBooleanFalseStops Talkative from monitoring for bandwidth as part of the QoS checks. While this is not advised for voice/video calling deployments, it can reduce page load times.
:gaBooleanFalseAllow dispatching of feature initiation events to Google Analytics. Events by default are marked as follows; Event Category: Talkative-Engage, Event Action: chat | cobrowse | webcall | video | email | offline-email
:third-party-trackingBooleanFalseAllows for custom tracking to be plugged in to the app. This will then be triggered whenever a interaction feature is used, similar to :ga.
:content-stringsObjectSee BelowThis object will determine the strings used within the app. It is possible to only set a few, those which are not specified will be set to default.
:interaction-dataArray of ObjectsEmptyProvide an array of custom variables and their labels which are to be passed to the agent console UI. See below for examples and options.
:collect-dataObjectsEmptySpecify which features should collect customer data before start. Please note, this adds an extra step to before an interaction is started.
:chat-wait-messagesArray of ObjectsSee BelowProvide an array of objects containing the message and and time it should be displayed.
:file-transferBooleanFalseAllows website visitors to send image attachments within the chat session.
:email-fieldsArray of ObjectsEmptyAllows you to add additional fields to the email form.
:api-featuresArray[]Specify the API features which will be used by the page. Options: chat, cobrowse, voice, video, email please note email includes both email and offline-email interaction types.
privacy-policy-urlStringTalkative PolicyAllows you to add a link to your own privacy policy. If one is not specified, the UI will use Talkative's default privacy policy: https://support.talkative.uk/security/privacy-policy


Attributes

You can adjust visual and functional aspects of the system within the scripts. This can be done by setting attributes within the <talkative-engage> element. Below is a list of the attributes:

AttributeTypeDefaultDescription
company-uuidString-This is the unique ID for your company. This can be found in your Talkative account.
group-uuidString-This is the unique ID for the group you want to target. This can be found in your Talkative account.
:chatBooleanFalseAllows web chat to be shown as an option to the customer.
:cobrowseBooleanFalseAllows cobrowsing to be shown as an option to the customer.
:voiceBooleanFalseAllows voice calls to be shown as an option to the customer.
:videoBooleanFalseAllows video calls to be shown as an option to the customer.
:emailBooleanFalseAllows email to be shown as an option to the customer.
:offline-emailBooleanFalseAllows an email contact form to be displayed to the customer outside of assigned business hours.
primary-colorRGB66,140,204Primary UI colour.
positionStringright:10%Specify the position along the bottom edge of the viewport. The side (right or left) as well as the value and units (px or %) must be specified. E.g. left:25% or right:200px
:calloutBooleanFalseShows a speech bubble above the UI with additional text to help draw a customer's attention. Text can be set using the :content-strings attribute.
:numpadBooleanFalseShows a numpad during calls to allow customers to navigate an IVR navigation.
:ignore-bandwidthBooleanFalseStops Talkative from monitoring for bandwidth as part of the QoS checks. While this is not advised for voice/video calling deployments, it can reduce page load times.
:gaBooleanFalseAllow dispatching of feature initiation events to Google Analytics. Events by default are marked as follows; Event Category: Talkative-Engage, Event Action: chat | cobrowse | webcall | video | email | offline-email
:third-party-trackingBooleanFalseAllows for custom tracking to be plugged in to the app. This will then be triggered whenever a interaction feature is used, similar to :ga.
:content-stringsObjectSee BelowThis object will determine the strings used within the app. It is possible to only set a few, those which are not specified will be set to default.
:interaction-dataArray of ObjectsEmptyProvide an array of custom variables and their labels which are to be passed to the agent console UI. See below for examples and options.
:collect-dataObjectsEmptySpecify which features should collect customer data before start. Please note, this adds an extra step to before an interaction is started.
:chat-wait-messagesArray of ObjectsSee BelowProvide an array of objects containing the message and and time it should be displayed.
:file-transferBooleanFalseAllows website visitors to send image attachments within the chat session.
:email-fieldsArray of ObjectsEmptyAllows you to add additional fields to the email form.
:api-featuresArray[]Specify the API features which will be used by the page. Options: chat, cobrowse, voice, video, email please note email includes both email and offline-email interaction types.
privacy-policy-urlStringTalkative PolicyAllows you to add a link to your own privacy policy. If one is not specified, the UI will use Talkative's default privacy policy: https://support.talkative.uk/security/privacy-policy

For additional changes to the UI, please contact Talkative at support@talkative.uk and we will accommodate your request.

Note: Talkative requires cookies and JavaScript to be enabled in the browser, and the <!DOCTYPE html> declaration must be made in each page.

To avoid any rendering delays, it is advised that these scripts are included at the bottom of the page, below your other higher priority scripts.

The scripts must be added to each page within your website in order to allow functionality of the Talkative solution on those pages.

Content String Default

:content-strings

The content below can be adjusted and put into the :content-strings attribute to change the text that is displayed to the customer.

{
    mainTitle: 'Talk to an Expert',
    options: {
        description: 'Please choose a method of communication:',
        chat: 'Chat',
        voice: 'Voice Call',
        cobrowse: 'Cobrowse',
        email: 'Email',
    },
    cobrowse: {
        description: 'Please call us and give the agent the following reference number:',
    },
    callout: {
        line1: 'Need help with',
        line2: 'our Services?'
    },
    email: {
        description: 'Please use the form below to leave us a message and we will get back to you as soon as possible.',
        offlineDescription: 'We are currently offline, please leave an email and we will get back to you as soon as possible.',
        email: 'Email...',
        name: 'Name...',
        message: 'Message...',
        submit: 'Submit',
        cancel: 'Cancel',
        required: '* are required fields',
    },
    feedback: {
        description: 'The interaction has ended, how did we do?',
        placeholder: 'Tell us more... (optional)',
        submit: 'Done',
    },
    chat: {
          emailDescription: 'You can come back to the chat at any time by pressing cancel.',
          emailSent: 'Thank you for your email, we will get back to you as soon as possible',
          emailReturn: 'Return',
    },
    offers: {
        chat: 'Would you like to add chat?',
        cobrowse: 'Would you like to start cobrowsing? ^^agentName^^ will be able to securely assist you around our website. We cannot see your desktop, sensitive information, or any other tab.',
        voice: 'Would you like to start a voice call?',
        agentVideo: 'Would you like to see ^^agentName^^ in a video call? Don\'t worry, they can\'t see you!',
        customerVideo: 'Would you like to share your video with ^^agentName^^? This will use your video camera.',
        twoWayVideo: 'Would you like to start a 2 way video call with ^^agentName^^? This will use your video camera.',
        documentShare: '^^agentName^^ would like to share a document, would you like to view it?',
        pagePush: 'Would you like to let ^^agentName^^ automatically direct you to new web pages?',
    },
}

Automated Queue Messages

:chat-wait-messages

Automated queue messages send updates to customers while waiting for an agent to pick up the chat. You can specify any amount of messages to appear after stated time (measured in seconds) intervals. Messages MUST be in descending order of time.

Example:

[{
    time: 45,
    message:'We apologise that our agents aren\'t able to pick up your chat right now. If you\'d like to leave your contact details we\'ll get back to you as soon as we can or please try again later.',
    showEmail: true,
    showWait: true,
    showLeave: true
},
{
    time: 15,
    message:'We\'re sorry to keep you waiting. One of our Travel Specialists will be with you shortly.'
},
{
    time: 0,
    message:'Please wait for a Travel Specialist.'
}]

Each of the following options will display a button with that particular queue message.
showEmail: true displays a button that turns the chat session into an email-form.
showWait: true displays a button that allows the website visitor to remain in the queue.
showLeave: true displays a button that ends the interaction when clicked.

Google Tag Manager implementation

To add queue wait messages to GTM tags, please format the queue wait messages as follows within the talkative-engage element:

var chatWaitMessages = [
    {
        time: 60,
        message: 'Sorry for the delay, we will be back with you as soon as possible',
    },
    {
        time: 0,
        message: 'We are now connecting you to a member of the team',
    },
];
talkativeAppElement.setAttribute(':chat-wait-messages', JSON.stringify(chatWaitMessages));

Showing position in queue

To display the position in queue, please include the following option:

:chat-wait-queue-statistics="{
                    enabled: true,
                    limit: 10
                }"

Interaction Data

:interaction-data

Interaction data (formerly called custom variables) allows you to pass through information from the customer's website session into the agent. Interaction data must be provided in the form of an array of objects, each object needs to have the following attributes:

AttributeDescription
labelA descriptive label for the data.
dataData payload.
typeType of data. Options: string or url

Example:

[{
    label: 'Username',
    data: 'talkative',
    type: 'string'
},
{
    label: 'Tradeforce CRM Record',
    data: 'https://tradeforce.com/talkative/',
    type: 'url'
}]

Please see the GTM script example for a second example.

Collect Data

:collect-data

Data collection can be added on individual features. Data collection forces the customer to enter their details before starting an interaction.

Data collection is currently supported for web call and web chat.

Setting the attribute to true will ask the customer for Name and Email, as shown below:

Example:

:collect-data="{chat: true}"
:collect-data="{chat: true, voice: true}"

To only ask the customer for one piece of information (Name or Email), this must be specified, as shown below:

To collect the customer's name:

:collect-data="{chat:['name']}"

To collect the customer's email:

:collect-data="{chat:['email']}"

The full list of pre-chat form options are as follows:

:collect-data="{
                    chat: [
                        'caseExists',
                        'email',
                        '1stLineDispo',
                        'phone',
                        'firstName',
                        'lastName',
                        'dob',
                        'postcode',
                        'comments',
                        'name',
                        'requiredCheckbox',
                        'question'
                    ],
                    voice: ['name'],
                    fields: [
                        // Valid keys:
                        // name: this is used as reference between these values and where it is used above.
                        // It is also used to refer to preset data from the api or :interaction-data (should be camel case name)
                        // dataLabel: this is the full string label for this piece of information (not translatable)
                        // type: type of input element
                        // label: text which will show up in the form to describe the input field
                        // required: boolean
                        // regex: regex to check the data
                        {
                            name: 'email',
                            dataLabel: 'Email',
                            type: 'text',
                            label: 'Email',
                            required: true,
                            regex: '^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$',
                        },
                        {
                            name: 'caseExists',
                            dataLabel: 'Case Exists',
                            type: 'text',
                            label: 'Does your case already exist?',
                        },
                        {
                            name: 'phone',
                            dataLabel: 'Phone',
                            type: 'text',
                            label: 'Phone number',
                            required: false,
                        },
                        {
                            name: 'firstName',
                            dataLabel: 'First Name',
                            type: 'text',
                            label: 'First name',
                            required: true,
                        },
                        {
                            name: 'lastName',
                            dataLabel: 'Last Name',
                            type: 'text',
                            label: 'Last name',
                            required: true,
                        },
                        {
                            name: 'dob',
                            dataLabel: 'Date of Birth',
                            type: 'text',
                            label: 'Date of Birth',
                        },
                        {
                            name: 'postcode',
                            dataLabel: 'Postcode',
                            type: 'text',
                            label: 'Postcode / ZIP Code',
                        },
                        {
                            name: 'comments',
                            dataLabel: 'Comments',
                            type: 'textarea',
                            label: 'Comments',
                            rows: 4,
                        },
                    ],
                }"

File Transfer

Optionally enable website visitors with file transfer. Currently only images are supported with a max size of 10MB. To enable, please ensure customer scripts (both .js and .css files) are on version 1.19.0 or higher.

Translation

When translation is enabled, you can also show the original messages to the website visitor (in addition to the translated messages) with the following:

:translation="{ showOriginalMessage: true, }"

Email Fields

:email-fields

Additional fields can be added to the email form using this attribute. Additional fields must be an array of objects as shown below:

:email-fields="[
    { type:'text', name:'Phone Number' },
    { type:'checkbox', name:'I would like to receive news & offers' },
    { type:'select', name:'Example Selector', options:['red', 'blue', 'green', 'yellow'] }
]"

Google Tag Manager

If you are using Google Tag Manager you will need to build up the app element using Javascript as GTM does not yet allow for custom elements to be added as tags. Here is an example with the GTM modification:

<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="stylesheet" href="https://files.talkative.uk/1.15.2/talkative-engage.css">
<script>
    var talkativeAppElement = document.createElement('talkative-engage');
    talkativeAppElement.id = 'talkative-engage';
    talkativeAppElement.setAttribute('company-uuid', '123e4567-e89b-12d3-a456-426655440000');
    talkativeAppElement.setAttribute('queue-uuid', '123e4567-e89b-12d3-a456-426655440000');
    talkativeAppElement.setAttribute(':chat', true);
    talkativeAppElement.setAttribute(':voice', true);
    talkativeAppElement.setAttribute('primary-color', '0,100,90');
    talkativeAppElement.setAttribute(':interaction-data', "[{label: 'Customer Account', data: '456789', type: 'string'}]");
    talkativeAppElement.setAttribute(':collect-data', "{chat: ['name']}");
    talkativeAppElement.setAttribute(':content-strings', "{mainTitle: { offline: 'Please leave us a message', default: 'Talk to us' }, options: {description: {voice:'Click the button to securely call us from your browser!',},}, callout:{line1:'Need advice from',line2:'an expert?'}}");
    document.body.appendChild(talkativeAppElement);
</script>
<script src="https://files.talkative.uk/1.15.2/talkative-engage.js"></script>

Escaping problematic characters in GTM

Adding \\ before characters like ' is compulsory or will break the script. Here is an example:

{mainTitle: { offline: 'We\\'ll be back soon !', default: 'We\\'re available right now !' },

Scripts Size

The Talkative scripts are approximately 300kB. The loading of the scripts and QoS testing happens after the web page has been loaded. Scripts are only loaded once. Scripts are cached across page changes.