Web Chat

Implement your Voiceflow Web Chat agent using our install code and JavaScript API.

Suggest Edits

With the Web Chat integration in Voiceflow it’s easy to implement and push your agent to production. Our Web Chat widget and JavaScript API allows you to customize the appearance UI elements, specify between development and production versions of your design, pass data upon launch, programmatically show and hide the widget, and more.

Installation Code

The Web Chat integration page in the Creator Tool provides code snippet you can use in your website / web app to start sharing your agent with users.

Within this page, you can set general settings like chat persistence but also customize the appearance of the chat widget.

Supported HTML elements (in the text step)

All of the below tags are supported when used in the text step on Web Chat. 

['a','audio','b','blockquote','br','code','dd','del','details','div','dl','dt','em','h1','h2','h3','h4','h5','h6','hr','i','img','input','ins','kbd','li','ol','p','picture','pre','q','rp','rt','ruby','s','samp','section','source','span','strike','strong','sub','summary','sup','table','tbody','td','tfoot','th','thead','tr','tt','ul','var','video']

Note: By default, dangerous HTML elements such as Iframe require additional configuration.

Enabling dangerous HTML elements

Disclaimer: Enabling dangerous HTML elements enables cross-site scripting vulnerabilities (XSS). This means that if you are using someone else's code, it may provide them full access to your private information. Do this at your own risk and only use your own code. You can read more on XSS vulnerabilities and how to prevent them here.

To enable dangerous HTML elements such as Iframe's, set the following configuration to true on your Web Chat installation code. By default this value is false.

window.voiceflow.chat.load({
  ...
  allowDangerousHTML: true
});

In your own code

You can go a bit further and use your own front-end code to interact with the Web Chat widget as you might also want to populate a specific user ID and/or use the available API to do the following actions:

  • Load a specific agent
  • Set configuration settings when the Web Chat widget loads
  • Open or close the Web Chat widget
  • Show or hide the Web Chat widget launch bubble
  • Interact with the Dialog Manager API and show the result within the Chat Widget
  • Show or clear proactive text messages above your widget launch bubble

Configuration

As you can see in the default snippet code available in your Web Chat agent's integration page, we use the chat.load() function to load a agent by setting the project ID, the runtime URL and a version ID.

Below is an example of the default code snippet.

window.voiceflow.chat.load({
  verify: {
    projectID: "63906a46223f6a0007741929"
  },
  url: "https://general-runtime.voiceflow.com",
  versionID: "production"
});

You can add additional settings on top of the above configuration to further customize the Web Chat experience for your users.

Pass a userID (optional)

Below is an handy way to identify the user and share that info with your agent. If you pass a userID, the value will be set as the built-in {user_id} variable in your Voiceflow agent.

/**
* [optional] userID to track users and persist/continue sessions
*/

userID: "string"

Pass user info for the Transcripts view (optional)

Here you can set a name and an image that will be used in the transcripts linked to that user. Note: this will not populate any variables or entities in your agent.

/**
* [optional] user metadata for transcripts
*/

user: {
  name: "string",
  image: "string"
}

Pass default variable values (optional)

You can pass values to the last_event system variable upon load(). Use the JavaScript Code step to validate the payload values and set existing variables with default values at the start of each new conversation.

Please note:

  • The last_event variable is set upon each new user event in the conversation (e.g. widget loaded, intent triggered, button clicked). If you want to set variables with default values, set them immediately after the Start intent in your agent's design.
  • Code Steps cannot be used to create new variables. Any variables that you want to use after the Code Step is executed must already exist before being referenced in the Code Step. For example, in the screenshot below, the user_name and user_email variables would need to be created in your agent before you could set them using values from the last_event payload.
/**
* [optional] pass data to set variables with default values upon load()
*/

launch: {
  event: {
    type: "launch",
    payload: {
      user_name: "Mary",
      user_email: "[email protected]"
    }
  }
}

Pass a versionID value or alias (optional)

By default, versionID is set to development but if you use the code snippet in the Web Chat integration page, this is set to production. You can also use this to force a specific agent's projectID.

Setting versionID to development is useful when you want to test a dev version of your agent or make changes to your Voiceflow project without impacting your actual agent on production. To see any changes you make in the Creator Tool in your Web Chat widget, click the "Run" button or use the R keyboard shortcut in the Creator Tool so the updates get populated.

Note: If the versionID is set to production before you publish your agent, the Web Chat widget will not render any system messages.

/**
* [optional] the versionID of your agent, defaults to 'development'
* can be a 'development' or 'production' alias or a specific versionID
*/

versionID: "string"

Pass a url (required for for Private Cloud customers)

The url setting is for Enterprises on Private Clouds as they need to use their dedicated runtime endpoint.

/**
* [optional] voiceflow dialog management runtime endpoint
* defaults to https://general-runtime.voiceflow.com
*/

url: "string"

Override agent settings and styles (optional)

The below can be used to override the listed agent configuration settings. You can also add a link to your self-hosted stylesheet.

If you use custom CSS to style your Web Chat, target elements that begin with .vfrc. You can find the list of classes in our react-chat repository on GitHub.

/**
* [optional] override configured agent definitions on integrations tab
*/

assistant: {
  title: "string",
  description: "string",
  image: "string",
  // color: "string",
  stylesheet: "string" //link to your self-hosted stylesheet
}

Example configuration

With all this in mind, you can now customize the snippet code or your front-end code to launch a specific agent / version with the options you need.

Here is an example of the chat.load() call we are using in our own agent in the Creator Tool.

window.voiceflow.chat.load({
  verify: { projectID: `${vfa_projectID}` },
  versionID: `${vfa_version}`,
  userID: `${vfa_userID}`,
  user: {
    name: `${vfa_userName}`,
    image: "https://support.voiceflow.fr/assets/logouser.png",
  },
})

Web Chat API

When the Web Chat widget script is loaded it will register an API as window.voiceflow.chat with the following methods:

load

load({config}) loads a specific Voiceflow agent on a webpage. See above for the configuration options.

open and close

open() opens the Web Chat widget window.

close() closes the Web Chat widget window.

show and hide

show() renders the Web Chat launch bubble. If the Web Chat widget was previously closed using hide(), a subsequent show() will render the Web Chat widget.

hide() hides the Web Chat launch bubble. If the Web Chat widget is open, hide() will hide the Web Chat widget.

interact

interact({action}) sends a request to the Dialog API and updates the conversation in the widget. See the interact endpoint documentation for more detail about the accepted actions.

Proactive text message bubbles

Create custom proactive text messages to draw attention to your Web Chat agent.

proactive.clear() clears any previous proactive messages.

proactive.push(...messages) renders one or more proactive text messages:

// one message  
window.voiceflow.chat.proactive  
  .push({ type: 'text', payload: { message: 'hello world' } })

// multiple messages  
window.voiceflow.chat.proactive  
  .push(  
    { type: 'text', payload: { message: '1!' } },  
    { type: 'text', payload: { message: '2!' } }  
  )

For example, you can render a proactive message bubble when your customer reaches a particular page on your website:

<script>
...
  window.voiceflow.chat.load({ ... }).then(() => {
    if (window.location.href.includes('https://store.com/products/fire_sneakers') {
      window.voiceflow.chat.proactive.clear(); // clear all previous messages
      window.voiceflow.chat.proactive.push({ 
        type: 'text', 
        payload: { message: 'Are you interested in some 🔥🔥🔥 sneakers?' }
      }, { 
        type: 'text', 
        payload: { message: 'Click on the chat to learn more!' }
      })
    }
  })
...
</script>

Additional example calls

Open the Web Chat widget with after 1s

window.voiceflow.chat.load({
  verify: { projectID: "63906a46223f6a0007741929" },
  url: "https://general-runtime.voiceflow.com",
  versionID: "production"
}).then(() => {
  setTimeout(function () {
    window.voiceflow.chat.open();
  }, 1000)
});

Open the Web Chat widget and trigger a specific intent

window.voiceflow.chat.load({
  verify: { projectID: '63906a46223f6a0007741929' },
  url: 'https://general-runtime.voiceflow.com',
  versionID: 'production'
}).then(() => {
  setTimeout(function () {
    window.voiceflow.chat.open();
  }, 1000);
  setTimeout(function () {
    window.voiceflow.chat.interact({
      type: "intent",
      payload: {
        intent: {
          name: "account_services"
        },
        entities: []
      }
    })
  }, 2000);
});

Events

Once loaded, the Web Chat widget also send messages (events) you can monitor to trigger a specific action in your front-end code.

window.addEventListener('message', (event) => {
  console.log(event);
}, false);

Note: the event.data value is a JSON string if it contains a voiceflow:* event type (e.g. data: '{"type":"voiceflow:open"}').

event.data type voiceflow:* values that may be useful include:

voiceflow:open - widget is opened

voiceflow:save_session - message is sent by the user

voiceflow:close - widget is minimized or closed

Updated 10 days ago

What’s Next