Using Drift Events - Widget API

Updated 21 days ago ​by Alexa Nguyen

If you'd like to send Drift events to an outside platform or customize Drift using specific events, you can use our Widget API.


First, check that the Drift widget is initialized and ready for use.

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) {
 // interact with the api here
})
</script>
Here is an example using our Widget API
Note for Segment Integration Users, follow along here to determine when the Drift API is ready for use

Here is a code sample, showing how to track an event using our Widget API

Let's say, you want to track that a user started a conversation & the corresponding conversation ID. 

You'd want to use  the startConversation event, which returns an object with this shape:

{
  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,
    });
  })
})

More info on sending events to Google Analytics here.

  • Open- sidebarOpen
  • Close- sidebarClose

The sidebarClose and sidebarOpen events are fired when the sidebar is opened or closed. The event argument contains the same UI flags as the message event.

event.data.sidebarOpen

true if the sidebar is in the open state, false if it’s closed.

event.data.widgetVisible

true if the widget is visible, false if it has been hidden.

event.data.isOnline

...true if your organization is currently online.

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

Welcome Message events

  • Open- welcomeMessage:open
  • Close- welcomeMessage:close


You can listen for welcomeMessage:openwelcomeMessage:close

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

Away Message events

  • Open- awayMessage:open
  • Close- awayMessage:close



You can listen for the awayMessage:open, and awayMessage:close events.

<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

We fire events for the campaign interactions that you see in your Campaign Reports. Your campaigns are your targeted messages. They differ from your welcome message, which is the catch-all message that you've customized in your settings

  • Open- campaign:open
  • Dismiss- campaign:dismiss
    • When a user closes a campaign message
  • Click- campaign:click
    • When a CTA is clicked
  • Submit- campaign:submit
    • When a user starts a chat or submits an email capture


You can listen to the campaign events.

window.drift.on("campaign:open", function(data) {
  console.log("User opened campaign " + data.campaignId);
});

Your function will receive an object  with the following shape:

{
  campaignId,  // the Drift ID for the campaign
}


Conversation events

  • Conversation started- startConversation
  • Message Sent - message:sent
  • Message Received - message
  • Email captured-  emailCapture
  • Meeting request sent- scheduling:requestMeeting
  • Meeting-  scheduling:meetingBooked


Conversation started

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

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

Your event handler will receive an object with this shape:

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


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);
});

Your event handler will receive an object with this shape:

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


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);
});

Your event handler will receive an object with this shape:

{
  conversationId, // the ID for the conversation
  inboxId,        // the ID for this conversation's inbox
  teamMember: {   // the team member that messaged the user
    id,           // the team member's Drift ID
    name,         // the team member's name
  }
}


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.data.email);
});


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);
});

Your function will receive an object  with the following 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);
});

Your function will receive an object  with the following 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
  },
}


Looking for our documentation on customizing Drift

Was this article helpful?


Can’t find what you’re looking for?

Talk To Us