Getting started

To add your Ada chatbot to a website, use the Ada Web SDK, a piece of Javascript code that you can copy and paste.

If you’re not sure how to implement the script, please reach out to an Ada team member. Note that all implementations are ultimately the responsibility of your development team.

Script Tag

For all website pages where you want your bot to appear, paste the following code within the <head></head> tags. Replace <YOUR-BOT-HANDLE> with the name of your bot.

HTML
1<script
2    id="__ada"
3    data-handle="<YOUR-BOT-HANDLE>"
4    src="https://static.ada.support/embed2.js">
5</script>

Next, complete the steps below to enable your bot.

Setup Approved Domains

To get started with Ada, once you’ve added the Web SDK Script Tag, you must turn on your bot, and set up approved domains.

For security purposes, your bot won’t launch on a domain that you haven’t authorized.

  • If you’re using a generative AI Agent:
    1. Set up your AI Agent’s approved domains.
    2. Turn on your AI Agent by changing its rollout percentages.
  • If you’re using a scripted bot:
    1. Set up your bot’s approved domains.
    2. Turn on your bot. On the Ada dashboard, go to Settings > Integrations, and beside Ada Web Chat, turn the toggle to On.

That’s it!

You should now see a small chat button on the bottom right corner of your website. Click the button to toggle the chat window in and out of view.

Ada’s Web SDK also supports a rich set of actions and settings that you can use to customize the behavior of your bot. For example, you might want to delay the launch of your bot until a certain event, or set the bot language. Maybe your application is a a single-page app, and you need more control. The Web SDK reference covers all of these options and more.

Load a bot on a non-US cluster

If your bot is not on the US cluster, use cluster in the script to specify the correct cluster. The cluster can be maple, eu, or att.

HTML
1<script>
2  window.adaSettings = {
3    handle: “<YOUR-BOT-HANDLE>”,
4    cluster: “<YOUR-CLUSTER>”
5  };
6</script>
7<script
8  src=“https://static.ada.support/embed2.js”
9></script>

If you’re not sure which cluster your bot is on, please reach out to an Ada team member for assistance.

RequireJS

If you are using RequireJS as your module loader, you may encounter issues with the standard Web SDK setup. This is because RequireJS does not know how to interpret the id and data-handle attributes that Ada uses. Instead of setting these attributes, you can simply set handle in your window.adaSettings object.

HTML
1<script>
2  window.adaSettings = {
3    handle: "<YOUR-BOT-HANDLE>"
4  };
5</script>
6
7<script
8  src="https://static.ada.support/embed2.js">
9</script>

If you encounter additional errors, consult the RequireJS Common Errors documentation.

Delay Bot Loading

Use lazy mode to delay Web SDK instantiation until a certain event.

If your team is facing an implementation issue with a part of Ada that relies on the Web SDK script to be present and running, using lazy mode may mitigate the issue.

To put the Web SDK in lazy mode, add the attribute data-lazy to the Web SDK script, as in the following example.

1<script
2  id="__ada"
3  data-lazy
4  data-handle="<YOUR-BOT-HANDLE>"
5  src="https://static.ada.support/embed2.js">
6</script>

When you are ready to instantiate the Web SDK, call the start action within your code. You can pass any settings you would normally set in window.adaSettings here.

1window.adaEmbed.start({
2  handle: "my-bot",
3  metaFields: {
4    username: "Ada Lovelace",
5    phone_number: "123-456-7890"
6  },
7  chatterTokenCallback: (chatter) => console.log(chatter)
8});

Use Async to Improve Page Load Times

The async attribute for HTML script elements helps eliminate parser-blocking JavaScript, allowing the browser to load and evaluate scripts without interrupting the parsing of the rest of the page. Using this attribute with the Web SDK script can improve page load times, but there are some caveats.

If your bot implementation makes use of any actions from the global adaEmbed object, you must wait for the object to be added to your document. There are two common ways to handle this:

  1. **Use the native script onload handler. When the script has loaded, the load event will be triggered. It is safe to call adaEmbed actions from here.

    1<script
    2  async
    3  id="__ada"
    4  data-handle="<YOUR-BOT-HANDLE>"
    5  src="https://static.ada.support/embed2.js">
    6</script>

  2. Use adaReadyCallback, which you can set in window.adaSettings. Note that while in the examples provided, toggle will work effectively the same way, adaReadyCallback is triggered after adaEmbed.start(...) has executed. Meanwhile, onload is simply triggered when the Web SDK script has been loaded.

    1<script
    2  async
    3  id="__ada"
    4  onload="window.adaEmbed.toggle()"
    5  data-handle="<YOUR-BOT-HANDLE>"
    6  src="https://static.ada.support/embed2.js">
    7</script>
    1window.adaSettings = {
    2  adaReadyCallback: () => {
    3    window.adaEmbed.toggle();
    4  }
    5};