← view more API documentation

api.visitor.getDetails

Gets the email address, full name, geolocation, and other details for this visitor. The value will be returned to the specified returnCallback.

Be sure to check out the Rules API to help filter through your most important customers! You will have access to this specific information about your customers:

Contact Information

• details.emailAddress last-known email address of the visitor (from prechat, offline message, or api.visitor.updateEmailAddress)
• details.fullName last-known full name of the visitor (from prechat, offline message, or api.visitor.updateFullName)
• details.phoneNumber last-known phone number of the visitor (from prechat, offline message, or api.visitor.updatePhoneNumber)

Geolocation Information

• details.city approximate city location
• details.region approximate state or province
• details.country approximate country
• details.countryCode approximate country (in ISO-standard format, e.g. UK, DE, JP, etc)
• details.organization organization that this visitor might be affiliated with

Browsing Information

• details.visitCount total number of times this visitor has visited your site
• details.pageCountForThisVisit number of pages that this visitor has viewed during this visit
• details.pageCountAcrossAllVisits total number of pages that this visitor has viewed all-time on your site
• details.secondsSpentForThisVisit number of seconds that this visitor has spent on your site
• details.secondsSpentAcrossAllVisits total number of seconds that this visitor has spent all-time on your site
• details.currentPage the current page the visitor is on (has a title and URL)
• details.recentPageHistory a list of the last 10 pages seen by the visitor (each page has a title and URL)

Conversation Information

• details.conversationCount total number of times this visitor has chatted with an operator
• details.isConversing will be true if the visitor is having a conversation right now
• details.messageCountForThisVisit number of messages sent and received during this conversation
• details.messageCountAcrossAllVisits number of messages sent and received for this visitor all-time on your site
• details.secondsSinceLastMessage seconds since either the visitor or operator sent a message
• details.secondsSinceLastNotificationToOperator seconds since the operator last received a notification
• details.conversationBeginPage the URL from which the visitor began their conversation

Referral Information

• details.referrer the URL that referred this visitor to your website (e.g. a Google search, advertisement, blog post, etc)
• details.referredByPaidAdvertisingThisVisit will be true if the visitor came to your site from a paid advertisement for this visit
• details.referredByPaidAdvertisingEver will be true if the visitor came to your site from a paid advertisement at some point
• details.referredByCampaignThisVisit will be true if the visitor came to your site from an email or blogging campaign this visit
• details.referredByCampaignEver will be true if the visitor came to your site from an email or blogging campaign at some point
• details.searchTextForThisVisit search text that was typed in Google, Yahoo, or Bing to get to your site
• details.searchTextForPreviousVisits search text that was typed in Google, Yahoo, or Bing to get to your site in past visits

Machine Information

• details.browser the browser that this visitor is using (e.g. "Chrome 12.1")
• details.operatingSystem the operating system that this visitor is using (e.g. "Windows", "Mac", or "Linux")
• details.ip the raw IP address for this visitor (e.g. "123.234.234.64")

Custom Fields

• details.customFields.yourFieldNameGoesHere you can retrieve any custom fields that you set with api.visitor.updateCustomFields

Examples

Let's say you wanted to know when a particular customer (e.g. Steve Jobs) needed your attention:

olark('api.visitor.getDetails', function(details){
    if (details.emailAddress == "stevejobs@apple.com" || details.fullName == "Steve Jobs") {
        olark('api.chat.sendNotificationToOperator', {body: "this might be Steve Jobs, just sayin'"})
    }
});

Let's say you want to highlight valuable visitors in your buddy list. For example you have already paid money for a visitor to click on your AdWords campaign, or when they search for the term "buying widgets":

olark('api.visitor.getDetails', function(details){

    if (details.referredByPaidAdvertisingThisVisit) {

        olark('api.chat.updateVisitorNickname', {snippet: "AdWords Referral"})

    } else if (details.searchTextForThisVisit == "buying widgets") {

        olark('api.chat.updateVisitorNickname', {snippet: "wants to buy a widget"})

    }
});

…Don't forget to check out the Rules API to help filter through your most important customers using these details!

Let's say you are targeting customers in San José, the capital of Costa Rica (not San Jose in California):

olark('api.visitor.getDetails', function(details){
    if (details.city == "San José" && details.region != "California") {
        olark('api.chat.sendNotificationToOperator', {body: "this customer might be in San Jose, Costa Rica"})
    }
});

Let's say you are targeting customers in Japan. You can either use the country name or the country code:

olark('api.visitor.getDetails', function(details){
    if (details.country == "Japan" || details.countryCode == "JP") {
        olark('api.chat.sendNotificationToOperator', {body: "this customer might be in Japan"})
    }
});

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.