Integrating the Duffel Assistant

About

Offering a high quality post-booking experience is an essential part of selling travel. However, servicing flights is complex, management integrations are hard to build, there will likely always be support cases that can't be solved programmatically, and having a team of knowledgeable travel consultants to manage support queries is expensive.

We created the Duffel Assistant to take on the burden of servicing flights orders and stays bookings. With this product you are able to integrate a visual component into your website that will display your customers trips and give them the ability to manage their flights and stays. Where an automation is not available they can connect to our team of travel support specialists to resolve issues.

This guide walks through how to integrate Duffel Assistant into your application.

Assistant overview

The Assistant offers two main functionalities:

A trip management interface
Connection to Duffel's travel support team and API-driven support resolution

Screenshots of the pages of the Duffel Assistant

Download demo video here

Integration options

The following diagrams illustrate how your application can embed and launch the Duffel Assistant at different points in the customer journey. It shows the flow of context — such as the customer user ID and order ID — from your application to Duffel, and how the user experience continues once Duffel's scope of responsibility begins.

Each path represents a different entry point — whether from a general "Manage Travel" button, a specific booking page, or your own support chat interface — and outlines how the Assistant acknowledges context, identifies the issue type, and either guides the user through self-service options or routes the conversation to a Duffel agent. The goal is to illustrate how the Duffel Assistant integrates seamlessly into the user experience you've designed while ensuring consistent, contextual support for travellers.

Diagram of the different integration options for the Duffel Assistant

Quick start

Load script

Include the following script tag on your site

HTML
<script
  type="text/javascript"
  src="http://assets.duffel.com/assistant/custom-element.js"
></script>

Render custom element

Include the custom element anywhere on your markup.

HTML
<duffel-assistant></duffel-assistant>

Open assistant

To open the assistant you need to call openDuffelAssistant and give it a client key to authenticate the component usage. You can learn about how to retrieve the client key below.

If you don't have a client key yet, you can also use the client key below which will load a fixture used to demonstrate the component.

React
openDuffelAssistant({
  clientKey:
    'fixture_eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiaWN1XzEyMyJ9.AEC4nHMvFuOrCljQ1guQz-Sw53GsP4JPiY1N2OLtnpI',
})

Pre-requisites

Customer users

To work with assistant we need to know which orders and bookings are associated to which users. For every user of your platform that will be booking travel on Duffel you need to create a Customer User. And when an order or booking is created, the IDs of that customer user must be present in the request payload. Learn more on our API reference:

Client key

Client keys are ephemeral and unique per user, so they must be generated on demand — when the assistant is going to be used. The mode of the access token you use to create the client key will dictate its scope of access. To create a client key for a specific user you must include the user ID in the data attribute of the request payload:

JSON
{ "data": { "user_id": "icu_..." } }

Creating client keys

Showing user trips

Generate a client key for your user
Share the client key with your front-end
Load assistant script
Render the custom element
Call function to open the assistant

Find a Javascript example below, with annotations of the steps above in comments:

React
// server.ts

import express from 'express'
import { readFile } from 'fs/promises'
import { dirname, resolve } from 'path'
const app = express()
const port = 3000

const DUFFEL_API_TOKEN = '' // TODO: Add your API token here
const USER_ID = '' // TODO: Add your user ID here

const HTML_FILE_PATH = resolve(__dirname, './index.html')

async function getHTML() {
  return await readFile(HTML_FILE_PATH, {
    encoding: 'utf-8',
  })
}

async function getComponentClientKey(user_id: string) {
  const response = await fetch(
    `https://api.duffel.com/identity/component_client_keys`,
    {
      method: 'POST',
      headers: {
        'Duffel-Version': 'v1',
        'Accept-Encoding': 'gzip',
        Accept: 'application/json',
        'Content-Type': 'application/json',
        Authorization: `Bearer ${DUFFEL_API_TOKEN}`,
      },
      body: JSON.stringify({ data: { user_id } }),
    }
  )
  const { data } = await response.json()
  return data.component_client_key
}

app.get('/', async (_req, res) => {
  try {
    // STEP 1: Generate a client key for your user
    const componentClientKey = await getComponentClientKey(USER_ID)

    const template = await getHTML()

    res.writeHead(200)

    // STEP 2: Share the client key with your front-end
    res.end(template.replace('__COMPONENT_CLIENT_KEY__', componentClientKey))
  } catch (error) {
    console.error(error)
    res.writeHead(500)
    res.end((error as Error).message)
  }
})

app.listen(port, () => {
  console.log(`Listening on port ${port}`)
})

HTML
// index.html

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>Traveller support integration example</title>
  </head>
  <body style="height: 100vh">
    <h1>Traveller support integration example</h1>
    <button id="open-support" onclick="openSupport()">Open support</button>

    <!-- STEP 4: Render the custom element -->
    <duffel-assistant></duffel-assistant>
  </body>

  <!-- STEP 3: Load assistant script  -->
  <script
    type="text/javascript"
    src="https://assets.duffel.com/assistant/custom-element.js"
  ></script>

  <script type="text/javascript">
    window.addEventListener('load', () => {
      window.openSupport = () => {
        // SETP 4: Call function to open the assistant
        openDuffelAssistant({
          clientKey: '__COMPONENT_CLIENT_KEY__',
        })
      }
    })
  </script>
</html>

Assistant for single resource

You may want to take more control over the display experience of flights order and stays booking, or integrate our flight and booking management APIs. In that case, you’ll only need the assistant when human intervention is needed. To support that you’ll need the following:

Client key for resource

A resource, aka a flights order or stays booking, needs to be identified in the client key creation. So when creating the client key you must include both the user id and resource id for which your user needs support. For orders:

JSON
{ "data": { "user_id": "icu_...", "order_id": "ord_..." } }

And for bookings:

JSON
{ "data": { "user_id": "icu_...", "booking_id": "bok_..." } }

Opening the assistant

When opening the assistant, you just need to call the openDuffelAssistant function with the client key generated for the user and resource pair.

React
openDuffelAssistant({ clientKey: '...' })

If the issue type for which your user is seeking help is already known, You may specify it with the issueType parameter. Allowed values are *cancellation*, *change* or *other*.

React
openDuffelAssistant({ clientKey: '...', context: { issueType: 'other' } })

When no issue type is specified the UI will prompt the user for one. When the assistant is opened with an issue type, this step will be skipped.

Content Security Policy

By explicitly specifying trusted sources (script-src, style-src, img-src, frame-src, connect-src), the CSP ensures only required resources are loaded from trusted domains, including Duffel's assets, chat provider(Stream)'s chat APIs, and WebSocket endpoints. It restricts unnecessary connections and prevents unauthorized scripts or assets from running, thereby safeguarding the website and its users.

Directive	URL	Reason
`script-src`	`https://assets.duffel.com`	Load Duffel Assistant's custom JavaScript file.
`style-src`	`https://assets.duffel.com`	Load Duffel Assistant's custom CSS for the Assistant component.
`style-src`	`https://cdn.jsdelivr.net`	Load CSS styles for the chat provider (Stream)'s React components.
`frame-src`	`https://assets.duffel.com`	Embed the Duffel Assistant iframe in the page.
`connect-src`	`https://assets.duffel.com`	Enables the browser to use the .map.js files for the Assistant custom element.
`connect-src`	`https://api.duffel.com`	Enable HTTP requests made by the Duffel Assistant iframe.
`connect-src`	`https://chat.stream-io-api.com`	Allow HTTP requests for chat functionalities via chat provider's API.
`connect-src`	`wss://chat.stream-io-api.com/connect`	Allow WebSocket connections for real-time chat updates.
`img-src`	`https://dublin.stream-io-cdn.com`	Load image and file assets for the chat service.
`default-src`	`'self'`	Restrict loading of all other resources to the same origin by default.

Notifying users of new support messages

You may want to allow your users to hide the Assistant while using your website of mobile app. But if they are in the middle of a support conversation, it's important they are able to know when a travel consultant is trying to contact them.

To enable you to achieve this we have implemented both a webhook and a client side "new message" event.

Webhook

You can subscribe to the webhook assistant.conversation.updated to be notified when a new message is sent to the assistant. The webhook will contain the following data:

JSON
{
  "data": {
    "user_id": "icu_...",
    "resource_id": "ord_..."
  }
}

You can test and subscribe to this webhook via our webhook endpoints or through the Duffel dashboard.

Client side "new message" event

Alternatively, you can also listen to the "new message" event on the client side.

For the Web:

JavaScript
window.addEventListener('message', (event) => {
  if (event.data.type === 'duffel-assistant-new-message') {
    const { userId, resourceId } = event.data
    console.log(
      `New message received for user: ${userId} and resource: ${resourceId}`
    )
    // notify your user that new messages have been received.
    // userId and resourceId will be available to you in the event data.
  }
})

For React Native:

The onNewMessage prop is available from versions

‣ 0.3.0 of @duffel/react-native-components-assistant
‣ 2.5.0 of @duffel/react-native-components

React
<DuffelAssistant
  onNewMessage={(newMessageEvent) => {
    const { userId, resourceId } = newMessageEvent
    console.log(
      `New message received for user: ${userId} and resource: ${resourceId}`
    )
    // notify your user that new messages have been received.
    // userId and resourceId will be available to you in the event data.
  }}
/>

Passing in context

If you want to hand over a chat from your support team to the Duffel support team, you can do that using the context props. This context will be made available to our support team to enable quicker resolutions, prevent conflicting advice and reduce duplicated questions. The summary you provide will be shown to our travel support agents when they pick up the chat. You will also need to provide an issueType ("cancellation", "change" or "other").

React
openDuffelAssistant({
  clientKey,
  context: {
    summary:
      'The traveller wants to change the dates of their stay to one week later',
    issueType: 'change',
  },
})

Or in React Native:

The context prop is available from versions

‣ 0.4.0 of @duffel/react-native-components-assistant
‣ 2.6.0 of @duffel/react-native-components

React
<DuffelAssistant
  isOpen={isDuffelAssistantOpen}
  onClose={() => setIsDuffelAssistantOpen(false)}
  clientKey="<USER_CLIENT_KEY>"
  context={{
    summary: 'This traveller needs their name corrected on the booking',
    issueType: 'other',
  }}
/>

Minimising the Assistant

While your users are on a chat, you might want to give them the ability to minimise the Assistant and continue using your website or mobile app. In order to achieve this you can use the showMinimiseButton prop, to display a minimise button next to the close button. When the user clicks on the minimise button, the assistant will post a message to your page with type duffel-assistant-minimise. You can listen for this message to differentiate between the user choosing to close vs minimise and render the appropriate UI.

React
// Open the assistant with the minimise button
openDuffelAssistant({
  clientKey,
  showMinimiseButton: true,
})

// Listen for the minimise message
window.addEventListener('message', (event) => {
  if (event.data.type === 'duffel-assistant-minimise') {
    // The Assistant iframe will be hidden and you may use this callback to render the UI inidicating it has been minimised.
    console.log('Assistant minimised')
  }
})

Or in React Native:

The showMinimiseButton and onMinimise props are available from versions

‣ 0.4.2 of @duffel/react-native-components-assistant
‣ 2.10.0 of @duffel/react-native-components

React
<DuffelAssistant
  isOpen={isDuffelAssistantOpen}
  clientKey="<USER_CLIENT_KEY>"
  showMinimiseButton={true}
  onMinimise={() => {
    setIsMinimised(true)
    setIsDuffelAssistantOpen(false)
  }}
  onClose={() => setIsDuffelAssistantOpen(false)}
/>

Enabling phone support [Preview]

Screenshot of phone support initiated through Duffel Assistant

Duffel Assistant can offer phone as an additional support channel when a traveller needs help from a human agent. Phone support must be enabled by Duffel for your organisation before it can be used, so please reach out to your sales contact if you'd like to enable this option.

Once phone support has been enabled, you can choose when to offer phone to your customers by passing supportChannels when opening the Assistant:

React
openDuffelAssistant({
  clientKey: '...',
  supportChannels: {
    chat: true,
    phone: true,
  },
})

Important notes:

We do not support phone only, so when using supportChannels, chat must be set to true. If chat is set to false, the Assistant will fail to render and throw an error message back to the application.
If phone support is not enabled for your organisation, the Assistant will continue with chat only.
If supportChannels is not provided, the Assistant will continue to only use chat as the support channel.
When a traveller chooses phone, the Assistant will show a phone number to call and a temporary PIN to quickly authenticate with a support agent.