FAQs

How do I get started with the Drift API?

https://devdocs.drift.com/docs/quick-start

Is it free?

Full API use is available to all customers free of charge.

Drift Applications use Oauth - what is Oauth?

There's a ton of resources searchable on the web that describe Oauth and how to authenticate applications for use. We describe how it's used for Drift applications in more detail here: https://devdocs.drift.com/docs/authentication-and-scopes

Do I need to implement Oauth for my app?

No! This is only required if you want to create a public app that other customers can use. For private apps you can simply use the private token, which is specifically for your Drift account, generated through the quick start guide: https://devdocs.drift.com/docs/quick-start.

How do I know which Drift user connected my app?

Connections to Drift apps are done by admins on an organization level. Once you have a token, you'll have access to the scopes for accessing the information in that organization's account.

I'm not receiving any webhooks even though I have them turned on?

Is your app connected? Verify by going to https://app.drift.com/settings/apps. If you're not sure how an app is installed, refer to: https://devdocs.drift.com/docs/quick-start. Alternatively if you added new webhooks after previous connecting, in the last section "Installing to Drift", you can try reconnecting your app to refresh the settings.

I'm still getting permissions errors for a scope even though I added it to the app token. What's wrong?

If you need to change scopes after a token(s) have already been granted, you'll need to regenerate those token(s) to be able to access the functionality / endpoints for the new scopes. This check is to prevent apps from declaring weak scopes and changing them after an app is connected. This applies to both your personal token, and tokens granted to you by other Drift accounts for public apps, so we recommend being deliberate when choosing your scopes.
The short solution: Try disconnecting and reconnecting your app, and using the new token generated.

What are the rate limits for the API? Couldn't seem to find these in the documentation.

Rate limits/usage caps are returned in the headers of our web responses. Generally these are pretty high though to accommodate bulk updates and pulls from the Drift platform (default is 600/min) unless otherwise stated as lower in the documentation. We do log volume from tokens/apps, so please use the APIs with intent!

I'm receiving duplicate webhook requests.

Do you have multiple apps connected here? https://app.drift.com/settings/apps. Active apps eligible to access your Drift info, based on granted scopes, and/or receive webhooks will be shown here.

drift.api.hideWelcomeMessage or drift.api.showWelcomeMessage methods aren't working.

You'll need to make sure no other playbooks are configured to fire and at that point you'll be able to manipulate the default welcome message. The alternative is to use CSS to force hide/show the widget, which would take precedence over display rules of playbooks (i.e. if a playbook is firing you can still hide with CSS): https://devdocs.drift.com/docs/widget-start

drift.identify is creating a bunch of users that don't have emails or names.

Make sure the usage is correct. drift.identify is always designed to be used with a email address and a unique ID (provided by the customer) per user. Typically this method is used in tandem with a login event to synchronize the logged in user with Drift, i.e. don't call drift.identify(userId), but call drift.identify(userId, { email: [email protected] })

I created a bunch of contact attributes via the API - can I delete or change them?

Custom attributes are currently immutable, we do this for indexing reasons - so you can do range queries on contacts with certain attribute values and create segments. For example, if you created a segment based on a numeric attribute and then tried to send the value "qualified" to that field through identify, the set request would be rejected and you would end up with the field being blank or the previous value. We are working on possibilities for removing created attributes, but in the meantime we recommend using another name if you've already added or indexed attributes to contacts with that previous name and no longer wish to use it.

Can I use the API to pull all contacts?

Not available publicly yet. We recommend doing a CSV dump of contacts first and then using the contact_identified and contact_updated webhooks to stay in sync with Drift. https://devdocs.drift.com/docs/webhook-events-1

The Drift widget is causing extended load time for my website - I'm worried this may be affecting SEO.

While not related to the API, this page should give additional info: https://help.salesloft.com/s/article/Drift-Drift-Load-Time. We've been reducing front end bundle sizes quite a bit, but this loading is asynchronous and shouldn't impact the TTI score (described in the document). There are examples of deferring the Drift widget in that link, as well.

I seem to be running into an issue where a returning visitor to the site will not create a "New" conversation. Instead, Drift "opens" a previously closed conversation. The issue here is that the conversationId is the same. Any ideas here?

This is expected. The same conversation thread continues as long as it's from the same initiating event. In the following scenarios, a new conversation and ID would be generated: the site visitor clicks "New Conversation" from the widget conversation history if you have this option enabled, the site visitor engages from a new playbook, or the site visitor visits from an incognito browser. This user is considered unknown again.
For the integrations we've built in house, we generally record whenever a conversation closes as a sign of new user activity - and push the conversation closed event along with the transcript, including the new messages, to your external system.

The new_conversation webhook isn't firing for my connected app.

The new_conversation webhook only fires for conversations initiated by the site visitor - not for bot playbooks as these would be too frequent. If you want to capture all conversations, we recommend listening for either the new message client side event https://devdocs.drift.com/docs/drift-events#section-user-received-a-message, or using the conversation_status_updated webhook https://devdocs.drift.com/docs/webhook-events-1#section-conversation-status-update and filtering for distinct conversation IDs there.

The contact_identified webhook isn't firing for all contacts.

The contact_identified webhook will only fire for contacts that have provided their email in chat. This hook will not fire for contacts uploaded via CSV or created manually in the Drift UI.

Is there a JavaScript library to pull in contact attribute information that lives in Drift client side?

Short answer: Not at this time.
Technical workaround: create a proxy that queries the Drift backend API's and returns this to the browser.

Do you guys have any SDK's for developing with the API?

Not publicly, but we have one for python here: https://github.com/Driftt/drift-python. We recommend
making the REST http calls elsewhere for now.

📘

Note: This is a page of common solutions or answers

It may not fit your exact situation or potential issue! Let us know either by chatting through the widget at help.drift.com or posting a question to our developer community.

👍

Are we missing any key insights, or do you have a good FAQ addition?

Suggest an edit on this page!