Developers

Directly RTM Docs

About RTM

RTM (Real Time Messaging) is a web widget tool to integrate Directly services on your website.

Getting started

  1. Signup for Directly and create a company
  2. Ask your Account Manager to setup an RTM instance for you
  3. Get the RTM widget embed code. It should look something like this:
<script>
    (function(d, i, r, e, c, t, l, y) {
        i[r] = i[r] || function () {
            (i[r].cq = i[r].cq || []).push(arguments)
        };
        l = d.createElement("script");
        l.id = "directlyRTMScript";
        l.src = e;
        l.async = 1;
        y = d.head || d.getElementsByTagName("head")[0];
        if (d.readyState === "complete" || d.readyState === "loaded" || d.readyState === "interactive") {
            y.appendChild(l);
        } else if (i.addEventListener) {
            i.addEventListener("DOMContentLoaded", function() { y.appendChild(l); });
        } else {
            i.attachEvent("onload", function() { y.appendChild(l); });
        }
    })(document, window, "DirectlyRTM", "https://app.directly.com/widgets/rtm/embed.js");
    DirectlyRTM("config", {
        id: "your-rtm-widget-uuid"
    });
</script>
  1. Paste the widget code into your website, before the closing </body> tag of your page. See below for more integration use cases.
  2. Your users can now start using RTM and sending you questions.

Advanced configuration

RTM accepts several configuration parameters:

Configuration parameters

Property name Data Type Default Value Description
id string n/a ID of the widget
active boolean true* Enables or disables the widget
displayAskQuestion boolean true Wether to display or not the RTM bubble at the bottom right corner of the browser
disableAskNewQuestionFromUi boolean true Wether to display or not any button and/or links which takes the user to the ask form
questionCategory string n/a The question category to assign
metadata object n/a Additional metadata that will be assigned to the question
userName string n/a Name of the person asking a question. This is used by our experts to address users. Use this only for your logged in users.
userEmail string n/a Email of the person asking a question
userPhone string n/a Phone number of the person asking a question
showDisclaimer boolean false* Whether to display or not a disclaimer that users have to opt-in to ask questions
forceRecaptcha boolean false* Whether to display or not a captcha before a user can ask a question
lang string "en" Language to use in the widget. It must be enabled in your company configuration
i18n object n/a Custom text to use in some labels by language in RTM

* Default value may be overwritten by server configuration.

See the full example below for usage.

Deferred configuration

You can decouple the embed widget code from the config code. In this way, you can have the widget code preloaded when you need to trigger it.

<script>
    (function(d, i, r, e, c, t, l, y) {
        i[r] = i[r] || function () {
            (i[r].cq = i[r].cq || []).push(arguments)
        };
        l = d.createElement("script");
        l.id = "directlyRTMScript";
        l.src = e;
        l.async = 1;
        y = d.head || d.getElementsByTagName("head")[0];
        if (d.readyState === "complete" || d.readyState === "loaded" || d.readyState === "interactive") {
            y.appendChild(l);
        } else if (i.addEventListener) {
            i.addEventListener("DOMContentLoaded", function() { y.appendChild(l); });
        } else {
            i.attachEvent("onload", function() { y.appendChild(l); });
        }
    })(document, window, "DirectlyRTM", "https://app.directly.com/widgets/rtm/embed.js");
</script>
DirectlyRTM("config", {
    id: "your-rtm-widget-uuid"
});

Javascript API

You can interact with Directly RTM widget programmatically using its Javascript API. Run commands or listen to events to adapt the RTM experience to your users.

Commands

Change a configuration option

DirectlyRTM("set", <option>, <value>);
DirectlyRTM("set", "displayAskQuestion", true|false)

DirectlyRTM("set", "showDisclaimer", true|false)

DirectlyRTM("set", "metadata", { "browser: "Chrome" })

DirectlyRTM("set", "questionCategory", "custom_category")

You can set any item from the table in Advanced Configurations except id, userName, userEmail and userPhone.

Open the Ask Question Form

DirectlyRTM("openAskForm");

Maximize widget

DirectlyRTM("maximize");

Minimize widget

DirectlyRTM("minimize");

Ask a question

DirectlyRTM("askQuestion", {
    questionText: "How can I merge two accounts?",
    name: "Jane",
    email: "jane@directly.com",
    questionCategory: "my-category",
});

If the user is logged in, you can ignore the name and email parameters.

DirectlyRTM("navigate", path);

Possible values of path:

  • /ask: Ask Question Form
  • /list: List of questions
  • /question/$questionId: Specific question
  • /minimized: Minimized view

Get data about current session and state

DirectlyRTM("getState", function(params) {
    // Do something
});

The callback function passed to getState will have access to the following parameters:

Parameters

Name Param Type Data Type Description
session n/a boolean Returns wether the user has a session or not
questions n/a object Returns an object with the number of open, closed and total questions

Note: you can not call this method on page load. If you need access to session and state data when the page loads, please use the onReady command.

Finish current session

DirectlyRTM("logout");

Event listeners

You can define callbacks for some events triggered by RTM.

Widget Ready

Triggered only after the RTM widget has finished loading completely.

DirectlyRTM("onReady", function() {
    // Do something
});

The callback function passed to onReady will have access to the following parameters:

Parameters

Name Param Type Data Type Description
config n/a object The configuration object passed to DirectlyRTM("config")
session n/a boolean Returns wether the user has a session or not
questions n/a object Returns an object with the number of open, closed and total questions

Question asked

Triggered when the user asks a new question.

DirectlyRTM("onAskQuestion", function() {
    // Do something
});

Triggered when the view has changed. The possible views are /minimized, /ask, /list, /question.

DirectlyRTM("onNavigate", function(path) {
    // Do something
    // path is the view path, for example `/ask` or `/list`
});

i18n

The RTM widget supports internationalization (18n). You can specify a language to use or let the widget use browser detection.

For example, to render the widget in Spanish:

<script>
    (function(d, i, r, e, c, t, l, y) {
        ...
    })(document, window, "DirectlyRTM", "https://app.directly.com/widgets/rtm/embed.js");
    DirectlyRTM("config", {
        id: "your-rtm-widget-uuid",
        lang: "es"
    });
</script>

Languages must be specified in ISO 639-1 format.

The supported languages are at the moment:

  • English - en
  • Spanish - es
  • German - de
  • Dutch - nl
  • Chinese - zh
  • Korean - ko
  • Japanese - ja
  • Italian - it
  • French - fr
  • Portuguese - pt
  • Russian - ru
  • Turkish - tr

Check with your Account Manager about adding more languages.

Text customization

You can customize the RTM texts to adapt the experience for your users.

<script>
    DirectlyRTM("config", {
        id: "your-rtm-widget-uuid",
        i18n: {
            es: {
                button: {
                    ask_our_experts: "Preguntar...",
                    send_to_our_experts: "Enviar a los expertos",
                },
                header: {
                    how_can_we_help_you: "Como podemos ayudarte?"
                }
            },
            de: {
                button: {
                    ask_our_experts: "Hilfe\nnötig?",
                    send_to_our_experts: "An unsere Experten senden",
                },
                header: {
                    how_can_we_help_you: "Wie können wir helfen?"
                }
            }
        }
    });
</script>

Check the reference for a comprehensive list of strings you can customize.

Examples

Basic integration

To get RTM working out of the box, you can just drop the following code (with your config.id) to your html page.

<script>
    (function(d, i, r, e, c, t, l, y) {
        i[r] = i[r] || function () {
            (i[r].cq = i[r].cq || []).push(arguments)
        };
        l = d.createElement("script");
        l.id = "directlyRTMScript";
        l.src = e;
        l.async = 1;
        y = d.head || d.getElementsByTagName("head")[0];
        if (d.readyState === "complete" || d.readyState === "loaded" || d.readyState === "interactive") {
            y.appendChild(l);
        } else if (i.addEventListener) {
            i.addEventListener("DOMContentLoaded", function() { y.appendChild(l); });
        } else {
            i.attachEvent("onload", function() { y.appendChild(l); });
        }
    })(document, window, "DirectlyRTM", "https://app.directly.com/widgets/rtm/embed.js");
    DirectlyRTM("config", {
        id: "your-rtm-widget-uuid"
    });
</script>

On page load, the widget will display at the bottom right corner.

Full configuration

<script>
    (function(d, i, r, e, c, t, l, y) {
        i[r] = i[r] || function () {
            (i[r].cq = i[r].cq || []).push(arguments)
        };
        l = d.createElement("script");
        l.id = "directlyRTMScript";
        l.src = e;
        l.async = 1;
        y = d.head || d.getElementsByTagName("head")[0];
        if (d.readyState === "complete" || d.readyState === "loaded" || d.readyState === "interactive") {
            y.appendChild(l);
        } else if (i.addEventListener) {
            i.addEventListener("DOMContentLoaded", function() { y.appendChild(l); });
        } else {
            i.attachEvent("onload", function() { y.appendChild(l); });
        }
    })(document, window, "DirectlyRTM", "https://app.directly.com/widgets/rtm/embed.js");
    DirectlyRTM("config", {
        id: "your-rtm-widget-uuid",
        displayAskQuestion: true,
        questionCategory: "your-question-category",
        metadata: {
            foo: "bar",
            page: {
                url: "http://example.com",
                existingUser: true
            }
        }
    });
</script>

User data prepropulated

If you are using RTM in pages where your users are already logged in, you can prepopulate the user information so RTM won't ask for it.

<script>
    (function(d, i, r, e, c, t, l, y) {
        ...
    })(document, window, "DirectlyRTM", "https://directly.com/widgets/rtm/embed.js");
    DirectlyRTM("config", {
        id: "your-rtm-widget-uuid",
        displayAskQuestion: true,
        questionCategory: "your-question-category",
        metadata: {
            foo: "bar",
            page: {
                url: "http://example.com",
                existingUser: true
            }
        },
        userName: "John Doe",
        userEmail: "john.doe@directly.com"
    }
</script>

Use your own custom form

You can send users to an RTM experience from your custom form. A common use case is sending only some categories of questions to RTM.

This can be done by calling the askQuestion command.

<!DOCTYPE html>
<html>
<head>
    <title>Sample RTM Form</title>
</head>
<body>
    <form onsubmit="submitForm()">
        <!-- Your form content -->
    </form>

    <script>
        (function(d, i, r, e, c, t, l, y) {
            i[r] = i[r] || function() {
                (i[r].cq = i[r].cq || []).push(arguments)
            };
            l = d.createElement("script");
            l.id = "directlyRTMScript";
            l.src = e;
            l.async = 1;
            y = d.head || d.getElementsByTagName("head")[0];
            if (d.readyState === "complete" || d.readyState === "loaded" || d.readyState === "interactive") {
                y.appendChild(l);
            } else if (i.addEventListener) {
                i.addEventListener("DOMContentLoaded", function() { y.appendChild(l); });
            } else {
                i.attachEvent("onload", function() { y.appendChild(l); });
            }
        })(document, window, "DirectlyRTM", "https://app.directly.com/widgets/rtm/embed.js");
        DirectlyRTM("config", {
            id: "your-rtm-widget-uuid",
            displayAskQuestion: false
        });

        function submitForm() {
            DirectlyRTM("askQuestion", {
                questionText: "How can I merge two accounts?",
                name: userName,
                email: userEmail,
                questionCategory: valueSelectedFromFormDropdown
            });
        }
    </script>
</body>
</html>

When the user submits a question on the form, it'd send that question to the RTM widget and pop it up.

Contact

If you have any questions about integrating Directly, please contact your Account Manager.