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.