Custom MAP/CRM Integration

Is your current Marketing Automation Platform (MAP) or Customer Relationship Management (CRM) not listed as an existing integration with Drift? Fear not, with Drift’s API you can build your own integration. This article explains the general process for building a custom integration. Where available, links have been provided to resources with additional details.

In the simplest terms, a Drift integration sends out signals from Drift to a designated URL when particular events occur (webhooks) within your Drift org. The receiving system then parses the data sent, collects additional data from Drift if needed, formats the data so that it can be ingested by a MAP/CRM, and finally, sends the data to the MAP/CRM.

The top-level steps required to build your own integration include:

Decide where to host the code for this integration
Create a custom App within the developer console of your Drift Org
Collect the required data via Drift’s API
Format and send the data as required for your custom MAP/CRM

1. Decide where to host the code for this integration

Many options exist for services to host your integration code. Depending on your company’s development capabilities, size, budget, timeline, etc. you’ll need to choose a backend server that provides a public endpoint (URL) and can handle the expected volume of events your integration will process.

An example solution could be to host your integration in Amazon Web Services (AWS) as a Lambda function triggered by a request to an AWS API Gateway URL. Other options include:

2. Create a custom App within your Drift Org

Once you’ve decided where to host your integration, the next step is to configure your Drift org to push the necessary information from Drift to your integration when certain events occur. To do this, you need a custom App in your Drift Org. Follow the instructions here to create an app.

Pay close attention to the OAuth & Scopes section. Depending on your situation, be sure to authorize your new app with the appropriate scopes (aka permissions) to perform all the needed actions for your integration. For a MAP/CRM integration, we’re generally pushing Data from Drift into your custom system and therefore need only read permissions within Drift. As a baseline, you can configure your new app with the following scopes:

Additionally, ensure you capture which events you want Drift to send to this custom App. Under the Webhooks >> Subscribe to Webhook Events section, select the events you wish to monitor.

For the purpose of a custom MAP/CRM integration, be sure to select the conversation_push as the baseline webhook subscription. This event will fire whenever a conversation is closed-- either manually or from a playbook rule-- or manually synced using the button within the Drift App.

This behavior is similar to our existing integrations with popular MAP and CRM systems. Other webhooks that may be of particular interest are gdpr_delete_requested and app_disconnected-- just be sure to update your scopes as necessary when adding new webhook subscriptions. Depending on what you select, your Drift org will broadcast events to the URL you enter in the Request URL field in the form of POST requests with payloads described in our Dev Docs.

While developing your custom integration, it may be useful to test your code locally. You can trigger webhooks from within your Drift org and send them to a locally running server using a tool called NGROK. Refer to our help doc for more information on testing locally.

When you’re ready to push your integration into production, be sure to update the Request URL within your integration app’s configuration to ensure Drift is sending data to the correct endpoint.

Lastly, grab your app’s OAuth Access token from the Installing to Drift section. You’ll need this to make API calls back to Drift. Please note, if you change any scopes after your token has been generated, you’ll need to uninstall then reinstall your app in order to generate a new token.

3. Collect the required data via Drift's API

If you subscribed to the conversation_push webhook, Drift will begin sending POST requests to the URL you designated whenever a conversation is closed. The request.body from a conversation_push payload will look similar to the following:

{
 orgId: 5000883,
 type: "conversation_push",
 data: {
   source: "conversation_manual_push",
   data: {
     conversationId: 3275727977,
     userId: 2322756,
     pushedAt: 1632349419751,
   },
 },
 token: "EM00VfyJofNgMqeWMpUWDeW4qjFMZr",
}

Conversations are the main object within the Drift App and as such, retrieving the conversationId will allow you to gather additional information from Drift depending on your needs. The following examples describe one possible approach and sequence to gathering information from Drift and will follow the path shown in the diagram above. However, feel free to modify as necessary to meet the needs of your integration.

Retrieve the Conversation

After parsing the conversation Id from the conversation_push payload, use the Id to query Drift’s API and gather information about that particular conversation. The response will provide additional data about who participated in the conversation, when it started, when it was last updated, it’s current status, and the associated playbook (if present).

Use Drift’s API to retrieve the conversation.

curl --location --request GET 'https://driftapi.com/conversations/'
--header 'Authorization: Bearer ::your token here::'

{
 data: {
   status: "closed",
   participants: [
     2322756,
   ],
   contactId: 11409060726,
   createdAt: 1632240461843,
   id: 3275727977,
   relatedPlaybookId: 2310900,
   inboxId: 642330,
   updatedAt: 1632240490684,
 },
}

Sample payload of the conversation model returned by the Drift API.

Retrieve the contact

From the returned conversation, collect the contactId from the conversation payload and retrieve the contact data.

curl --location --request GET 'https://driftapi.com/contacts/'
--header 'Authorization: Bearer ::your token here::'

The request will return the contact model for the site visitor who participated in the conversation. Notice the contact model includes a list of a contact’s Drift attributes. Use this, in conjunction with your playbooks, to ensure you are collecting the desired information about your site visitors who engage with Drift.

{
 "data": {
     "id": 11751623441268736,
     "createdAt": 1627616677362,
     "attributes": {
         "country": "United States",
         "_END_USER_VERSION": 104,
         "recent_entrance_page_title": "test site",
         "employment_seniority": "executive",
         "city": "Boston",
         "_calculated_version": 104,
         "timezone": "America/New_York",
         "employment_role": "owner",
         "latitude": 42.3600825,
         "original_conversation_started_page_title": "test site",
         "last_context_location": "{\"city\":\"Los Angeles\",\"region\":\"California\",          
                                \"country\":\"US\",\"countryName\":\"United States\"}",
         "linkedin_handle": "in/gregg-parker",
         "original_entrance_page_url": "https://drift.me/admin",
         "employment_name": "Camp Waziyatah",
         "recent_conversation_started_page_title": "test site",
         "recent_conversation_started_page_url": "drift.me/admin",
         "state": "Massachusetts",
         "first_name": "Gregg",
         "email": "[email protected]",
         "events": {},
         "start_date": 1627616677362,
         "longitude": -71.0588801,
         "original_ip": "172.112.190,3.229.120",
         "display_location": "Boston, MA, US",
         "_end_user_version": 104,
         "recent_entrance_page_url": "https://drift.me/admin",
         "avatarUrl": "https://d1ts43dypk8bqh.cloudfront.net/v1/avatars/573792f1-cbc3-49ce",
         "ip": "172.112.190,3.229.120",
         "externalId": "5239c583-cc8e-4617-353-79681622839e",
         "timeZone": "America/New_York",
         "last_name": "Parker",
         "display_name": "Gregg Parker",
         "original_conversation_started_page_url": "drift.me/admin",
         "tags": [],
         "last_contacted": 1628025353187,
         "avatar_url": "https://d1ts43dypk8bqh.cloudfront.net/v1/avatars/573792f1-cbc3-49ce",
         "original_entrance_page_title": "test site",
         "employment_title": "Owner, Director",
         "socialProfiles": {},
         "name": "Gregg Parker",
         "last_active": 1627621324929
     }
 }
}

Retrieve the Users

It may be important for your integration to know which Drift user participated in the conversation. At this point, you already have an array of user Ids from the conversation model returned earlier under the participants key. However, you may need more than a Drift ID in your MAP/CRM. Use the Drift API to gather additional information such as name and email about each user. Note: this requires users_read scope.

curl --location --request GET 'https://driftapi.com/users/list'
--header 'Authorization: Bearer ::your token here::'

[
 {
   id: 5028476,
   orgId: 5000883,
   name: "A Simon",
   email: "[email protected]",
   role: "member",
   availability: "OFFLINE",
   verified: false,
   bot: false,
   createdAt: 1630082419824,
   updatedAt: 1630082419824,
 }
]

Retrieve the transcript

If desired, use Drift’s API to retrieve the conversation transcript. Passing the transcript to your MAP/CRM will allow downstream users to quickly gather the context of each site visitor. Use the conversation_id gathered earlier and the Drift API to retrieve a formatted text string of the transcript.

curl --location --request GET 'https://driftapi.com/conversations//transcript'
--header 'Authorization: Bearer ::your token here::'

Sep 21,
09: 07: 46 AM PDT Bot (Agent): Hey there!  Would you like to speak with a human?
Sep 21,
09: 07: 49 AM PDT [email protected]: No thanks!
Sep 21,
09: 07: 50 AM PDT Bot (Agent): Ok. Would you like to book a meeting with a sales rep instead?
Sep 21,
09: 08: 00 AM PDT [email protected]: Yes please!
Sep 21,
09: 08: 03 AM PDT Bot (Agent): You can grab a time on Agent's calendar here.
Sep 21,
09: 08: 10 AM PDT Bot (Agent): All set! I've sent an email confirmation to [email protected].

By now, you have collected a basketful of data from Drift. Use the patterns described above to accumulate more data, or move on to the next step.

4. Format and send the data

Format the data accumulated thus far into the proper shape and data type required by your custom MAP/CRM. Once you’ve sliced, diced, and smashed together the bits and pieces of information, POST your data to your MAP/CRM’s proper endpoint.