← view more API documentation

api.rules.defineRule

Provides a simple interface for triggering particular actions, like:

• initiating chat with a visitor who has been browsing for more than 30 seconds
• notifying an operator when a visitor lands on the page from a Google AdWords campaign
• highlighting important visitors in your buddy list

Be sure to check out the Visitor API to learn how to access detailed customer information for making awesome rules. To define a new Rule, all you need to do is give these arguments:

Describe the rule

• options.id unique identifier for this rule, e.g. "important_visitor_rule_1"
• options.description human-readable description of what this rule does, e.g. "notifies the operator about important visitors"

Define when and what to trigger

• options.condition function that evaluates a condition and calls pass when true (see examples below)
• options.action function that performs the action, e.g. notifying the operator (see examples below)

Make sure not to trigger too many times

• options.perPage make this true if the action is only supposed to trigger once per page
• options.perVisit make this true if the action is only supposed to trigger once per visit
• options.perVisitor make this true if the action is only supposed to trigger once per visitor

Examples

Let's say you wanted to auto-initiate with any visitor who has visited 5 pages without talking to an operator, since maybe he is confused:

    olark('api.rules.defineRule', {

        // Specify a unique ID for this rule.  This helps the API to keep your
        // rules separate from each other.
        id: '1',

        // The description is a good way to summarize what this rule is doing
        description: "offer help to a visitor after he has browsed 5 pages and hasn't chatted yet",

        // The condition will be checked whenever there is a relevant change
        // in the chat, just call pass() whenever it meets the criteria
        condition: function(pass) {

            // you can use the Visitor API to get information like page count
            olark('api.visitor.getDetails', function(details){

                if (details.pageCountForThisVisit >= 5 && !details.isConversing) {
                    // we have met the condition of visiting over 5 pages,
                    // and the visitor hasn't started chatting yet,
                    // so mark this condition as passed
                    pass();
                }

            });

        },

        // The action will be executed whenever the condition passes.  You can
        // automatically limit the number of times this action will trigger by
        // using the perPage, perVisit, and perVisitor options.
        action: function() {
            olark('api.chat.sendMessageToVisitor', {
                body: "hi, have any questions about our products?"
            });
        },

        // Restrict the action to execute only once per visit, that way offering
        // help doesn't happen over and over for the same visitor
        perVisit: true

    });

Maybe you would like to hide the chatbox on certain pages, but only if the visitor is not already chatting:

    olark('api.rules.defineRule', {

        // Specify a unique ID for this rule.  This helps the API to keep your
        // rules separate from each other.
        id: '2',

        // The description is a good way to summarize what this rule is doing
        description: "hide the chatbox when the visitor is not chatting and is viewing an unimportant page",

        // The condition will be checked whenever there is a relevant change
        // in the chat, just call pass() whenever it meets the criteria
        condition: function(pass) {

            // we care whether the visitor is already conversing, and
            // what page he is currently on
            olark('api.visitor.getDetails', function(details){

                // determine whether this page is important
                var isImportantPage = (details.currentPage.url.indexOf('/important-page') >= 0);

                if (!details.isConversing && !isImportantPage) {
                    // the visitor is not chatting yet, and he or she
                    // is viewing an unimportant page
                    pass();
                }

            });

        },

        // The action will be executed whenever the condition passes.  You can
        // automatically limit the number of times this action will trigger by
        // using the perPage, perVisit, and perVisitor options.
        action: function() {
            olark('api.box.hide');
        },

        // Restrict the action to execute only once per page, that way
        // the box doesn't accidentally get re-hidden if it expanded at
        // some point on this page (due to another rule)
        perPage: true

    });

Again, don't forget to look at the Visitor API to learn about all of the visitor details you have available...like name, geolocation, time spent on page, etc. Tell us if you'd like to see more!

Discussion

Feel free to propose good uses for this method, or even drop us some suggestions for improvement! You can also join our mailing list to collaborate with other developers and get updates from us.