Webhooks integration guide

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.

1. 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, and containing the 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"
           }
       },
       "operators": {
           "1234": {
               "kind": "Operator",
               "id": "1234",
               "username": "jdoe",
               "nickname": "John",
               "emailAddress": "john@example.com"
       	}
       }
   }

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

   curl -X POST -d 'data=%7B%22items%22%3A%20%5B%7B%22body%22%3A%20%22Hi%20there.%20Need%20any%20help%3F%22%2C%20%22timestamp%22%3A%20%221307116657.1%22%2C%20%22kind%22%3A%20%22MessageToVisitor%22%2C%20%22nickname%22%3A%20%22Bob%22%2C%20%22operatorId%22%3A%20%221234%22%7D%2C%20%7B%22body%22%3A%20%22Yes%2C%20please%20help%20me%20with%20billing.%22%2C%20%22timestamp%22%3A%20%221307116661.25%22%2C%20%22kind%22%3A%20%22MessageToOperator%22%2C%20%22nickname%22%3A%20%22John%22%7D%5D%2C%20%22kind%22%3A%20%22conversation%22%2C%20%22tags%22%3A%20%5B%22olark%22%2C%20%22customer%22%5D%2C%20%22operators%22%3A%20%7B%221234%22%3A%20%7B%22emailAddress%22%3A%20%22bob%40example.com%22%2C%20%22kind%22%3A%20%22Operator%22%2C%20%22nickname%22%3A%20%22Bob%22%2C%20%22id%22%3A%20%221234%22%7D%7D%2C%20%22id%22%3A%20%22EV695BI2930A6XMO32886MPT899443414%22%2C%20%22visitor%22%3A%20%7B%22countryCode%22%3A%20%22US%22%2C%20%22ip%22%3A%20%22123.4.56.78%22%2C%20%22emailAddress%22%3A%20%22john%40example.com%22%2C%20%22fullName%22%3A%20%22John%20Doe%22%2C%20%22id%22%3A%20%229QRF9YWM5XW3ZSU7P9CGWRU89944341%22%2C%20%22city%22%3A%20%22Palo%20Alto%22%2C%20%22kind%22%3A%20%22Visitor%22%2C%20%22country%22%3A%20%22United%20State%22%2C%20%22region%22%3A%20%22CA%22%2C%20%22organization%22%3A%20%22Widgets%20Inc.%22%2C%20%22customFields%22%3A%20%7B%22favoriteColor%22%3A%20%22blue%22%2C%20%22myInternalCustomerId%22%3A%20%2212341234%22%7D%2C%20%22operatingSystem%22%3A%20%22Windows%22%2C%20%22conversationBeginPage%22%20%3A%20%22http%3A%2F%2Fwww.example.com%2Fpath%22%2C%20%22browser%22%3A%20%22Chrome%2012.1%22%7D%7D'

   Olark can also send any offline messages for your site. 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"
           }
       }
   }
   

2. Enter the address to your webhook endpoint on our integration page.

3. Click the "Send Test" button to ensure your endpoint is configured properly.
4. Now you have the ability to type !lead 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.