Receiving Information from Drift

You can use our Widget API to send Drift events to an outside platform or customize Drift using specific events.

This document covers the following events:

Getting Started

Initialize your Drift Widget

The ready event indicates that Drift widget is ready for use. It contains a single argument which is the actual API object that can then be acted upon.

<script>
drift.on('ready',function(api, payload) {
 // your code goes here
})
</script>
<script>
analytics.ready(function(){
    //interact with the api here
})
</script>

where payload is an object with metadata on the widget state when loaded for each site visitor. This object contains the following data:

{
  isOnline: (boolean), // is the widget "online"
  sidebarOpen: (boolean), // was the sidebar opened at widget launch
  teamAvailability: (object), // described below
  widgetVisible: (boolean), // is the widget visible based on the drift display settings to the user (excludes any manual css overrides)
}

Team Availability

For each team in your drift account (if teams supported in your account), we'll display the current isOnline state for each time mapped by teamId to preserve privacy - indicated within the teamAvailability field in the widget ready payload.

The corresponding teamId maps to a team in your drift account.

{
  teamId: { isOnline: boolean },
  ...
}

where each teamId is an integer and

https://app.drift.com/settings/teams/{teamId} is the corresponding home page in your drift account for that team.

ex: https://app.drift.com/settings/teams/111 if you have a team with team id 111 created.

How to track an event using our Widget API

After you initialize the Drift widget, you want to track that a user started a conversation and the corresponding conversation ID. You would use the startConversation event, which returns an object like this:

{
  conversationId, // the ID for the conversation
  inboxId,        // the ID for the inbox for this conversation
}

If you wanted to send this event to a platform like Google Analytics, you would need to add the Google Analytics tracking call. It would look something like the following:

drift.on('ready', function (api) {
  drift.on('startConversation', function (event) {
    // Enter Google Analytics function here
    ga('send', 'event', {
      eventCategory: 'Drift Conversations',
      eventAction: 'Started Conversation',
      eventLabel: event.conversationId,
    });
  })
})

You can also integrate with Google Analytics with one click via our Google Analytics Integration.

Sidebar Events

sidebarOpen is the event that fires when the sidebar opens.
sidebarClose is the event that fires when the sidebar closes.

The event argument contains the same UI flags as the message event.

Event attributes:

event.data.sidebarOpen is true if the sidebar is in the open state. false if it's closed.
event.data.widgetVisible is true if the widget is visible. false if it's hidden.
event.data.isOnline is true if your organization is currently online.

The following shows an example: when the sidebarClose event is triggered, if the widget is visible, we call the hide() method.

<script> 
drift.on('ready',function(api){
  drift.on('sidebarClose',function(e){
    if(e.data.widgetVisible){
      api.widget.hide()
    }
  })
})
</script>
Conversation Sidebar

Conversation Sidebar

Welcome Message Events

welcomeMessage:open is the event that fires when the welcome message is open.
welcomeMessage:close fires when the welcome message is closed.

<script>
drift.on('welcomeMessage:open', function() {
  console.log('Welcome Message is open 🌞')
})
drift.on('welcomeMessage:close', function() {
  console.log('Welcome Message is closed 🌞')
})
</script>
Welcome Message

Welcome Message

Away Message Events

awayMessage:open is the event fired when an away message opens.
awayMessage:close is the event fired when an away message closes.

<script> 
drift.on('awayMessage:open', function() {
  console.log('Away Message is open 🌝')
})
drift.on('awayMessage:close', function() {
  console.log('Away Message is closed 🌝')
})
</script>

Campaign Events

The Drift widget fires events for the campaign interactions that you see in your Playbook Reports.

Your Playbooks are your targeted messages. They differ from your welcome message, which is the catch-all message that you've customized in your settings.

A note on Campaign event listeners

Campaign event listeners fire for single time campaigns only (non bot-based playbooks) such as the slider or email capture messages.

If you are looking to listen for leadbot playbooks starting, you should use the conversation:playbookFired event described on this page.

campaign:open fires when campaign begins.
campaign:dismiss fires when a user closes a campaign message.
campaign:click fires when a call to action (CTA) is clicked.
campaign:submit fires when a user starts a chat or submits an email capture.

window.drift.on("campaign:dismiss", function(data) {
  console.log("User dismissed campaign", JSON.stringify(data));
});

Example Payload:

// User dismissed campaign 
{
  "data": 
  {
    "sidebarOpen":false,
    "widgetVisible":true,
    "isOnline":true
  },
 "campaignId":111593
}

Slider Message Events

Slider Message Close- sliderMessage:close

Slider Message Close

The sliderMessage:close event fires when the slider message is closed.

window.drift.on("sliderMessage:close", function(data) {
  console.log("User closed slider the slider");
});

The sliderMessage:close handler will receive an object with this shape:

{
  botMessage,                     // if the message closed was a bot message
  userInteractedWithConversation, // if the user has interacted with the conversation the slider message is coming from
  playbookId: (optional int),     // if part of a playbook
  interactionId: (optional int),  // if part of a playbook
  campaignId: (optional int)      // if part of a playbook
}

Alternatively, you can track this as a playbook-specific event with Playbook Dismissed (conversation:playbookDismissed)

Conversation Events

Conversation Started - startConversation
Conversation Selected - conversation:selected
Message Sent - message:sent
Message Received - message
Email Captured - emailCapture
Phone Number Captured - phoneCapture
Meeting Request Sent - scheduling:requestMeeting
Meeting Booked - scheduling:meetingBooked
Playbook Fired - conversation:playbookFired
Playbook Clicked - conversation:playbookClicked
Playbook Dismissed - conversation:playbookDismissed
Button Clicked - conversation:buttonClicked
First Interaction - conversation:firstInteraction

Conversation Started

The startConversation event fires when the user starts a new chat.

startConversation is only intended for non-playbook conversations

This event tracks when a site visitor starts a conversation, not the bot.

We recommend and provide the First Interaction client event for tracking first messages in all conversations (included the ones initiated by a bot playbook).

window.drift.on("startConversation", function(data) {
  console.log("User started a new conversation " + data.conversationId);
});

The startConversation event handler will receive an object with this shape:

{
  conversationId, // the ID for the conversation
  inboxId		      // the ID for this conversation's inbox
}

Conversation Selected

The conversation:selected event is triggered when the user selects a conversation from the inbox.

The conversation:selected event handler will receive an object with this shape:

{
  conversationId: (int),          // the ID for the conversation
  playbookId: (optional int),     // the ID when selecting a playbook
  interactionId: (optional int),  // the interaction ID when selecting a playbook
  campaignId: (optional int)      // the campaign ID when selecting a playbook
}

User Sent a Message

The message:sent event fires when the user replies to a conversation.

window.drift.on("message:sent", function(data) {
  console.log("User replied to conversation " + data.conversationId);
});

The message:sent event handler will receive an object with this shape:

{
  conversationId: (int),          // the ID for the conversation
  inboxId: (int),                 // the ID for this conversation's inbox
  playbookId: (optional int),     // the ID when selecting a playbook
  interactionId: (optional int),  // the interaction ID when selecting a playbook
  campaignId: (optional int)      // the campaign ID when selecting a playbook
}

User Received a Message

the message event fires when the user receives a message from a team member.

window.drift.on("message", function(data) {
  console.log("User received a message from ' + data.teamMember.name + ' in conversation " + data.conversationId);
});

The message event handler will receive an object with this shape:

{
  conversationId: (int),  // the ID for the conversation
  inboxId: (int),         // the ID for this conversation's inbox
  teamMember: {           // the team member that messaged the user
    id: (int),            // the team member's Drift ID
    name: (string),       // the team member's name
  },
  playbookId: (optional int),     // the ID when part of a playbook
  interactionId: (optional int),  // the interaction ID when part of a playbook
  campaignId: (optional int)      // the campaign ID when part of a playbook
}

Email Captured

The emailCapture event fires when the user identifies through an Email Capture Campaign, completes an email capture form inside the Widget, or if they simply type their email into a message.

window.drift.on("emailCapture", function(e) {
  console.log("user identified as: " + e);
});


/*
ex:
user identified as:
{"data":{"email":"q@q.com","conversationId":583998469,"interactionId":XXX, "campaignId": XXX, "playbookId": XXX}}
*/

We'll include as many of the present id values as possible - interactionId, playbookId, and campaignId.

{
  data: {
    email: (string),
    conversationId: (int),
    playbookId: (optional int),
    interactionId: (optional int),
    campaignId: (optional int)
  }
}

Phone Number Captured

The phoneCapture event fires whenever a user provides a phone number in chat. Currently, it only works for US phone numbers. You'll receive a payload like the following:

window.drift.on("phoneCapture", function(data) {
     console.log("User provided a phone number: " + JSON.stringify(data))
 })

/*
ex:

User types: "Hi, my number is 555-444-5555" anywhere in chat.

User provided a phone number: {"conversationId":3215047,"messageId":3003184162,"createdAt":1552946646658,
"authorId":3000192098,"phone":"555-444-5555"}
*/

The phoneCapture event handler will receive an object with this shape:

{
  conversationId: (int),
  messageId: (int),
  createdAt: (int),
  authorId: (int),
  phone: (string), // The phone number formated as XXX-XXX-XXXX
  playbookId: (optional int),
  interactionId: (optional int),
  campaignId: (optional int)
}

HowTo: Setting a phone number from anywhere

Note the phone capture event won't automatically set the property on the end user, but with a simple extension this is possible:

Using the phone capture event in combination with setUserAttributes, you'll be able set the number from anywhere in a conversation thread on the end user object. Once the user provides an email the phone number should be present on the contact record!

window.drift.on("phoneCapture", function(data) {
     drift.api.setUserAttributes({phone: data.phone})
})

Meeting Request Sent

The scheduling:requestMeeting event fires when the Schedule Meeting card is pushed to a conversation.

This can happen when you call the api.scheduleMeeting method, when the user tries to book a meeting through a Drift Profile, or when a member of your team shares a calendar to a conversation.

window.drift.on("scheduling:requestMeeting", function(data) {
  console.log("user wants to schedule a meeting with " + data.teamMember.name);
});

The scheduling:requestMeeting event handler will receive an object with this shape:

{
  teamMember: {  // the team member the user wants to schedule a meeting with
    id,          // your team member's Drift ID
    name,        // your team member's name
  }
}

Meeting Booked

The scheduling:meetingBooked event fires when the user books a meeting with a member of your team.

window.drift.on("scheduling:meetingBooked", function(data) {
  console.log("user booked a meeting with " + data.teamMember.name);
});

The scheduling:meetingBooked event handler will receive an object with this shape:

{
  teamMember: {  // the team member the user booked a meeting with
    id,          // your team member's Drift ID
    name,        // your team member's name
  },
  meeting: {
    time,        // the meeting's start time as a <a href="http://www.unixtimestamp.com/" target="_blank">UNIX timestamp</a>
    duration,    // the meeting duration in minutes
    timeZone,    // the timezone for the meeting's start time
  },
  conversationId: (int),
  playbookId: (optional int),
  interactionId: (optional int),
  campaignId: (optional int)
}

Playbook Fired

The conversation:playbookFired event will fire whenever a leadbot playbook fires for the first time in a new conversation session with a site visitor.

window.drift.on("conversation:playbookFired", function(data) {
    console.log("Playbook fired: " + JSON.stringify(data))
})


/*
ex: 
Playbook fired: {"conversationId":583998469,"messageId":1430463200,"createdAt":1553021092581,
"authorId":2487803352,"interactionId":XXX, "playbookId": XXX, "campaignId": XXX}
*/

We'll include as many of the present id values as possible - interactionId, playbookId, and campaignId.

The conversation:playbookFired event handler will receive an object with this shape:

{    
  messageId: (long), // id of initial playbook message
  createdAt: (long), // time of initial playbook message
  authorId: (long), // typically the anonymous end user id.
  conversationId: (int),
  playbookId: (optional int),
  interactionId: (optional int),
  campaignId: (optional int)
}

A note on testing the "Playbook Fired" event

Subsequent launches or opens of the same playbook without a site visitor message will not re-trigger the conversation:playbookFired event.

Playbook Clicked

The conversation:playbookClicked event is triggered when the user interacts with a playbook from a greeting by clicking on the message or the widget button.

The conversation:playbookClicked event handler will receive an object with this shape:

{
  converationId: (int),
  playbookId: (optional int),
  interactionId: (optional int),
  campaignId: (optional int)
}

Playbook Dismissed

The conversation:playbookDismissed message is clicked when the user dismisses a message from a playbook by clicking on the close button next to the message.

The conversation:playbookDismissed event handler will receive an object with this shape:

{
  converationId: (int),
  messageId: (int),
  playbookId: (optional int),
  interactionId: (optional int),
  campaignId: (optional int)
}

Button Clicked

The conversation:buttonClicked event fires when the user clicks on a button as a response to a question. Will capture events like those shown in the following gif: https://cl.ly/cf1f04581909.

As an example, you could use this for custom event tracking in an external system or triggering a particular event on your website in response to a button press with certain text during a conversation.

window.drift.on("conversation:buttonClicked", function(data) {
  console.log("user clicked a button with text: " + data.buttonBody);
});

The conversation:buttonClicked event handler will receive an data object with the following shape:

{
  conversationId: (int), // conversation id this button was clicked in
  messageId: (long),      // the message id this button click created
  createdAt: (long),      // the time this button was clicked (timestamp)
  authorId: (long),       // the authorId (end user or contact id) of the user clicking the button
  questionId: (int),     // id of the question in the playbook (internal value)
  buttonBody: (string),      // the text the button displayed
  playbookId: (optional int),
  interactionId: (optional int),
  campaignId: (optional int)
}

First Interaction

the conversation:firstInteraction event fires for the first site visitor message in each unique conversation thread, or each distinct conversation id, associated with a bot playbook.

window.drift.on("conversation:firstInteraction", function(data) {
    console.log("First interaction: " + JSON.stringify(data)
})
    
/*
ex: 
First interaction: {"messageId":1441152633,"conversationId":587543841,
"createdAt":1553118597159,"authorId":2488443669,
"playbookId":XXX,"interactionId":XXX,"campaignId":XXX}
*/

We'll include as many of the present id values as possible - interactionId, playbookId, and campaignId.

The firstInteraction event handler will receive an data object with the following shape:

{    
  messageId: (long), // id of initial playbook message
  createdAt: (long), // time of initial playbook message
  authorId: (long), // typically the anonymous end user id.
  conversationId: (int),
  playbookId: (optional int),
  interactionId: (optional int),
  campaignId: (optional int)
}

GDPR Events

GDPR clicked

The gdprClicked event works with the Drift GDPR consent form at https://app.drift.com/settings2/consent and will fire whenever a site visitor clicks on the yes or no consent buttons as part of the form prior to starting a conversation.

 window.drift.on("gdprClicked", function(data) {
   console.log("GDPR button clicked: " + JSON.stringify(data))
 })
 
 /*
ex when fired: 
GDPR button clicked: {"accepted":true,"endUser":3007081549}
*/

You'll receive a payload of the following form:

{
  accepted: (boolean), // consent granted? true or false
  endUser: (long) // id of the site visitor
}

Script example

This example shows listening to a variety of Drift client side events and logging their contents whenever they happen.


<!-- Import Drift snippet above this -->
<script>

    drift.on('ready', function (api, eventData) {
     // eventData content described on the "Configuration and Settings" page.
      
     window.drift.on("startConversation", function (data) {
       console.log("User started a new conversation " + JSON.stringify(data))
     })
     window.drift.on("gdprClicked", function(data) {
       console.log("GDPR button clicked: " + JSON.stringify(data))
     })
     window.drift.on("campaign:open", function (data) {
       console.log("User opened campaign", JSON.stringify(data))
     })
     window.drift.on("campaign:click", function (data) {
       console.log("User clicked campaign", JSON.stringify(data))
     })
     window.drift.on("campaign:dismiss", function (data) {
       console.log("User dismissed campaign", JSON.stringify(data))
     })
     window.drift.on("campaign:submit", function (data) {
       console.log("User submitted campaign", JSON.stringify(data))
     })
     window.drift.on('sidebarOpen', function (e) {
       console.log('sidebar open', JSON.stringify(e))
     })
     window.drift.on('sidebarClose', function (e) {
       console.log('sidebar close', JSON.stringify(e))
     })
     window.drift.on("conversation:playbookFired", function(data) {
       console.log("Playbook fired: " + JSON.stringify(data))
     })
     window.drift.on("phoneCapture", function(data) {
       console.log("User provided a phone number: " + JSON.stringify(data))
     })
     window.drift.on("conversation:firstInteraction", function(data) {
       console.log("First interaction: " + JSON.stringify(data))
     })
     window.drift.on('welcomeMessage:open', function () {
       console.log('Welcome Message is open 🌞')
     })
     window.drift.on('welcomeMessage:close', function () {
       console.log('Welcome Message is closed 🌞')
     })
     window.drift.on("conversation:buttonClicked", function (data) {
       console.log("user clicked a button: " + JSON.stringify(data))
     })
     window.drift.on("emailCapture", function (e) {
       console.log("user identified as: " + e.data.email)
     })

 })
</script>

Receiving Information from Drift


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.