Widget API

Widget Events

You can listen for events to control some aspects of the widget remotely. For example, you might want to hide the widget under normal circumstances, but still have a way to notify users of incoming messages.

ready

The ready event indicates that Drift widget has been initialized and 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>

The api object supports the following actions:

Hide the Drift widget

api.widget.hide()

Show the Drift widget

api.widget.show()

Open the Drift conversation sidebar

api.sidebar.open()

Close the Drift conversation sidebar

api.sidebar.close()

Toggle the Drift conversation sidebar

This will toggle the sidebar open or closed depending on its current state.

api.sidebar.toggle()

Open the Drift sidebar to a new conversation

api.goToNewConversation()

Show the welcome message

This will open the default welcome message based on your site’s settings.

api.showWelcomeMessage()

You can also pass some additional parameters to further customize the welcome message. All parameters are optional.

api.showWelcomeMessage({
  message:undefined, // a string. replaces the default welcome message with a custom one. 
  avatarUrl:undefined // a url. replaces the default avatar with a custom one. 
})

Hide the welcome message

This will hide the welcome message and reset its state.

api.hideWelcomeMessage()

Show the welcome message or away message

This will show the proper message based on your organization's current online / offline status.

api.showWelcomeOrAwayMessage()
Note For Segment Integration Users
If you’re using the Segment integration, you can still use the Drift Widget API, but the drift object won’t be immediately available on the window. You can use the Segment’s analytics.ready function to determine when the Drift API has been installed and is ready for use.
<script> 
analytics.ready(function(){
  drift.on('ready',function(api){
    // interact with the api here
  })
})
</script>

Trigger the Scheduling Card

If you have Drift Scheduling enabled, you can use the Widget API to programmatically trigger the scheduling card flow:

<script>
drift.on("ready", function(api) {
  api.scheduleMeeting(driftUserId); /* <-- your Drift User ID here */
});
</script>

You'll need your Drift User ID to use this API. Don't know yours? Just ask us.

A more complex example, where we trigger the API when a button on the page is clicked.

<button id="schedule-meeting-button">
  Book a meeting with me
</button>
<script>
(function() {
  var driftUserId = 6;
  var $button = document.getElementById("schedule-meeting-button");
  $button.addEventListener("click", function() {
    drift.on("ready", function(api) {
      api.scheduleMeeting(driftUserId);
    });
  });
})();
</script>

message

The message event indicates that the user has received a new message. Use this to un-hide the widget so the user can see the new message. The event argument has flags to indicate the current state of the UI.

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.

<script> 
drift.on('ready',function(api){
  drift.on('message',function(event){
    if(!event.data.sidebarOpen){
      api.widget.show()
    }
  })
})
</script>

sidebarClose / sidebarOpen

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>

startConversation

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

window.drift.on("startConversation", function() {
  console.log("started a new chat!");
});

Widget Configuration

You can also control many aspect of the widget configuration at runtime. Call drift.config with one or more of the options described below to change the widget's configuration for that session...

drift.config({
  locale: 'en-US',
  messages: {
    welcomeMessage: 'Hey there!',
    awayMessage: "Hey, we're not here right now, but leave a message.",
    emailCaptureMessage: "Leave your email so we can get back to you.",
    thankYouMessage: "Thanks we'll follow up soon."
  },
  enableWelcomeMessage: false,
  enableCampaigns: false,
  enableChatTargeting: false,
  backgroundColor: '#000000',
  foregroundColor: '#ffffff',
  activeColor: '#00ff00',
  textColor: '#ffffff',
  autoAssignee: {
    name: 'Trevor Rundell',
    title: 'Engineer',
    email: 'trevor@example.com',
    avatarUrl: 'https://s.gravatar.com/avatar/...',
  },
  inboxId: 1,
  cookieDomain: '.example.com',
  welcomeMessageDelay: 5000,
})

locale - An IETF language tag (usually a combination of language and country codes). overrides the language specified in your settings.

enableWelcomeMessage - true will allow the welcome message popup to happen while you're online. false will prevent it from popping up. overrides the "show welcome message teaser" setting.

enableCampaigns - false will disable enrollment in / display of any browser targeted campaigns. Default is true.

enableChatTargeting - false will disable any chat targeting "display when" rules defined in your settings. Default is true.

backgroundColor, foregroundColor, activeColor, textColor - Override the four colors described in this help doc.

autoAssignee - Sets the default user that is shown in all welcome messages. If you specify a the emailfield new conversations will automatically be assigned to the team member with that email address. Overrides any "helping team members" defined in your settings.

cookieDomain - Change the domain that the widget will read and write identification cookies from. Defaults to the current domain, but can be used to set cookies on a more generic domain instead. See this help doc for more info.

inboxId - Override the default inbox for conversations created by the widget.

welcomeMessageDelay - The amount of time (milliseconds) to wait before popping up the welcome message teaser if it's enabled. Defaults to 5000 (5 seconds).

messages - Override any custom messages set within the app. By default these will be set to the localized default for the selected locale. Note that these will not affect any messages sent by the bot.

welcomeMessage - Text shown on the welcome message popup.

awayMessage - Text shown on the away message popup.

thankYouMessage - Text shown after the user has started a conversation via the away message.

emailCaptureMessage - Text shown on the lead email capture form.


Widget API Examples

A simple use case might be hiding the widget from users until they receive a message. The following snippet accomplishes that…

drift.on('ready',function(api){
  // hide the widget when it first loads  
api.widget.hide()
 // show the widget when you receive a message
  drift.on('message',function(e){
    if(!e.data.sidebarOpen){
      api.widget.show()
    }
  })
 // hide the widget when you close the sidebar
  drift.on('sidebarClose',function(e){
    if(e.data.widgetVisible){
      api.widget.hide()
    }
  })
})

 

Not using Drift yet? Get your free account here.


Was this article helpful?

Can’t find what you’re looking for?

Talk To Us