Webhooks integration guide

NOTE: This help article is intended for customers on our self-serve level of service. If you are an Olark Pro customer, your integration likely will work differently. Please reach out to pro@olark.com for help with setting up your integration.

Using a webhook is a simple way to take the content of an Olark chat transcript and process it for use on your own server. For example, you could add it to your own custom CRM, push it into your marketing automation platform or even perform additional analytics on every conversation.

Setting up a webhook integration

Create a webhook endpoint. A webhook endpoint is a URL on your server that will receive each transcript when a conversation completes, e.g. http://www.yourhost.com/olark_endpoint.php
When you finish a live chat, Olark makes HTTP POST to the endpoint you specified. The POST has a single data field containing the JSON-encoded transcript.

‍

JSON encoded transcript

Here is an example of what a JSON-encoded transcript might look like. You can populate the customFields data using our Javascript custom fields API:


{
    "kind": "Conversation",
    "id": "EV695BI2930A6XMO32886MPT899443414",
    "tags": ["olark", "customer"],
    "items": [{
        "kind": "MessageToVisitor",
        "nickname": "John",
        "timestamp": "1307116657.1",
        "body": "Hi there. Need any help?",
        "operatorId": "1234"
    },
    {
        "kind": "MessageToOperator",
        "nickname": "Bob",
        "timestamp": "1307116661.25",
        "body": "Yes, please help me with billing."
    }],
    "visitor": {
        "kind": "Visitor",
        "id": "9QRF9YWM5XW3ZSU7P9CGWRU89944341",
        "fullName": "Bob Doe",
        "emailAddress": "bob@example.com",
        "phoneNumber": "(555) 555-5555",
        "city": "Palo Alto",
        "region": "CA",
        "country": "United State",
        "countryCode": "US",
        "organization": "Widgets Inc.",
        "ip": "123.4.56.78",
        "browser": "Chrome 12.1",
        "operatingSystem": "Windows",
        "conversationBeginPage": "http://www.example.com/path",
        "customFields": {
            "myInternalCustomerId": "12341234",
            "favoriteColor": "blue"
        },
        "chat_feedback": {
            "comments": "Very helpful, thanks",
            "friendliness": 5,
            "knowledge": 5,
            "overall_chat": 5,
            "responsiveness": 5
        }
    },
    "operators": {
        "1234": {
            "kind": "Operator",
            "id": "1234",
            "username": "jdoe",
            "nickname": "John",
            "emailAddress": "john@example.com"
        }
    },
    "groups": [{
        "name": "My Sales Group",
        "id": "0123456789abcdef",
        "kind": "Group"
    }]
}

Simulating a POST

You can use curl to simulate a POST from our webhook integration to your endpoint like this:


curl -X POST --data-urlencode 'data={"kind": "Conversation", "tags": ["olark", "customer"], "items": [{"body": "Hi there. Need any help?", "timestamp": "1307116657.1", "kind": "MessageToVisitor", "nickname": "John", "operatorId": "1234"}, {"body": "Yes, please help me with billing.", "timestamp": "1307116661.25", "kind": "MessageToOperator", "nickname": "Bob"}], "operators": {"1234": {"username": "jdoe", "emailAddress": "john@example.com", "kind": "Operator", "nickname": "John", "id": "1234"}}, "groups": [{"kind": "Group", "name": "My Sales Group", "id": "0123456789abcdef"}], "visitor": {"ip": "123.4.56.78", "city": "Palo Alto", "kind": "Visitor", "conversationBeginPage": "http://www.example.com/path", "countryCode": "US", "country": "United State", "region": "CA", "chat_feedback": {"overall_chat": 5, "responsiveness": 5, "friendliness": 5, "knowledge": 5, "comments": "Very helpful, thanks"}, "operatingSystem": "Windows", "emailAddress": "bob@example.com", "organization": "Widgets Inc.", "phoneNumber": "(555) 555-5555", "fullName": "Bob Doe", "customFields": {"favoriteColor": "blue", "myInternalCustomerId": "12341234"}, "id": "9QRF9YWM5XW3ZSU7P9CGWRU89944341", "browser": "Chrome 12.1"}, "id": "EV695BI2930A6XMO32886MPT899443414"}'

Offline message JSON

Olark can also send offline messages collected while you're logged out of chat. Here is what a JSON-encoded offline message may look like:


{
    "kind": "Conversation",
    "id": "EV695BI2930A6XMO32886QPT899443414",
    "items": [{
        "kind": "OfflineMessage",
        "timestamp": "1307116667.1",
        "body": "Hi there."
    }],
    "visitor": {
        "kind": "Visitor",
        "id": "9QRF9YWM5XW3ZSU7P9CGWRU89944341",
        "fullName": "John Doe",
        "emailAddress": "foo@example.com",
        "phoneNumber": "(555) 555-5555",
        "city": "Palo Alto",
        "region": "CA",
        "country": "United States",
        "countryCode": "US",
        "organization": "Widgets Inc.",
        "ip": "123.4.56.78",
        "browser": "Chrome 12.1",
        "operatingSystem": "Windows",
        "customFields": {
            "myInternalCustomerId": "12341234",
            "favoriteColor": "blue"
        }
    },
    "groups": [{
        "name": "My Sales Group",
        "id": "0123456789abcdef",
        "kind": "Group",
    }]
}

Enter the address to your webhook endpoint on our integration page, and click Save.

Testing

Click the Send test button to ensure your endpoint is configured properly.

You're all set! Now you can type !lead while chatting to post the conversation to your webhook endpoint. If a conversation continues after you send !lead, we'll do another POST to your endpoint when the conversation finishes. The conversation will have the same ID. Alternatively, you can select the option to have all transcripts sent automatically without needing to type a command into chat.

Return JSON

Your endpoint can then return JSON containing the link generated by your CRM. For example:

{ "integrationUrl": "http://www.yourhost.com/issue/1"}

This is the URL that is shown to the agent when using the !webhook or !lead or !case commands.

Extra Events Extension

Aside from the webhook calls outlined above, we also support some additional events. Since existing webhooks might not expect these extra events, they are only triggered when explicitly enabled on https://www.olark.com/settings/integrations/webhooks.

These new events will include the field "eventType" at the top level of their JSON payload to identify the type of event.

Start Event

Description: Triggered once when a conversation starts.

Event Type Value: start

Example Payload: Same as a normal payload (omitting information not yet available), but including the appropriate eventType field. Example:


 {
        "kind": "Conversation",
        "id": "EV695BI2930A6XMO32886MPT899443415",
        "eventType": "start",
        "items": [],
        "operators": {
            "1234": {
                "kind": "Operator",
                "id": "1234",
                "username": "jdoe",
                "nickname": "John",
                "emailAddress": "john@example.com"
            }
        },
        "groups": [{
            "name": "My Sales Group",
            "id": "0123456789abcdef",
            "kind": "Group"
        }]
    }

Expected return value: Either empty or a JSON dictionary indicating the integrationUrl.

Example:

{"integrationUrl":"http://CONTEXTUAL_URL_FOR_THIS_CONVERSATION"}

‍

Whitelist IP's

Although it's generally not necessary, you can filter using these IP's:

35.223.151.68
34.67.70.29
35.188.143.172

‍

Please note that these addresses are in CIDR notation

104.197.12.97/32104.197.30.74/32104.197.10.10/3235.184.42.86/32146.148.105.32/3235.192.239.225/3235.193.38.104/32

‍

Thank you! Your submission has been received and you'll hear from us shortly!

Oops! Something went wrong while submitting the form.