Creating a new Conversation
You can create a new conversation with only an email address. This is the same endpoint which powers the "Create New Conversation" functionality in the Drift UI.
A common use case is creating conversations in Drift that represent activity from other data sources, enabling Drift to be your one stop shop for contact activity. For example, if a conversation starts on Facebook - why not continue it from Drift? With this API, you can create a conversation to do that.
Note that Drift cookies will not be attached to contacts created through the endpoint.
POST https://driftapi.com/conversations/new
Requires the conversation_write
scope.
Example Request:
{
"email": "[email protected]",
"message": {
"body": "A conversation was started <a href='www.yoururl.com'>here</a>, let's resume from drift!",
"attributes": {
"integrationSource": "Message from facebook"
}
}
}
If the conversation was successfully created, you'll receive a 200
response with the ID of the contact and newly-created conversation ID.
Response:
{
"status": "open", // conversation status
"participants": [
228224 // user id's of any routed participants into the conversation.
],
"contactId": 1261122150,
"createdAt": 1548700064840,
"id": 464032472, // conversationId
"inboxId": 116983
}
Specify the source or context around the conversation
Note that the
integrationSource
is a special attribute in the message and will appear in the header of the newly started conversation. We recommend including this in each request.
The created conversation should now appear in the connected user's Drift account and be opened with the provided contact's email
.
Creating a new conversation this way can be a good way to aggregate interactions from different sources for reps. If you want to follow up with the target email automatically, we recommend the following setting as well. This will send an email after a period of the message going unread, which typically is 30 minutes.
A Note on Conversations by email
We'll attempt to find a contact in your account with the provided email, based on first created, and open up a new conversation in Drift with them.
If that visitor has been cookied (or was previously identified by an email provided via a conversation or via drift.identify), then they'll also be able to see the conversation instantly when they revisit your webpage!
If a contact with that email isn't found, then one will be created.
If no integrationSource
is provided. It will show a generic, "Conversation started from integration" message in the header.
Routing
With the new conversation API, you can assign a particular Drift user to the conversation if you have the desired Drift user ID - retrievable from the GET Users
API endpoint.
To do this, simply specify the autoAssigneeId
with the desired id value in the attributes field of the message.
Example, routing the agent "Chris" with user id 21849
to the newly created conversation.
POST https://driftapi.com/conversations/new
// Response
{
"email": "[email protected]",
"message": {
"body": "hello world",
"attributes": {
"autoAssigneeId": 21849
}
}
}
Results in the corresponding Drift user (if he/she has an active account) to be added to the conversation.
Updated 10 months ago