> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # 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 `` tags. Replace `` with the name of your bot. ```html HTML ``` 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](/chat/web/getting-started#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](/generative/docs/channels/chat/chat-configuration/launch-options#website-restrictions). 2. Turn on your AI Agent by changing its [rollout percentages](/generative/docs/channels/chat/chat-configuration/launch-options). * If you're using a **scripted bot**: 1. Set up your bot's [approved domains](/scripted/docs/use-ada-with-your-website/deploy-ada-on-your-website-or-app/restrict-your-bot-to-a-list-of-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](/chat/web/sdk-api-reference) covers all of these options and more. ## Load a bot on a non-default cluster AI Agents are hosted on different Kubernetes clusters depending on region and infrastructure requirements. Most Agents run on the default US (`us`) cluster. Ada also supports several non-default clusters: * `us2`: secondary US region * `maple`: Canada * `eu`: Europe If your Agent is hosted on any of these clusters, set the `cluster` field explicitly in your embed script. This tells the SDK which hosting region to target and ensures the Agent loads from the correct domain. For example, `.us2.ada.support` instead of `.ada.support`. Failing to set the correct cluster may result in your Agent not loading or loading from the wrong environment. ```html HTML ``` If you're not sure which cluster your bot is on, reach out to your Ada team 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 HTML ``` If you encounter additional errors, consult the [RequireJS Common Errors documentation](https://requirejs.org/docs/errors.html). ## 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. ```html ``` 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. ```javascript window.adaEmbed.start({ handle: "my-bot", metaFields: { username: "Ada Lovelace", phone_number: "123-456-7890" }, chatterTokenCallback: (chatter) => console.log(chatter) }); ``` ## Use Async to Improve Page Load Times The [`async`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#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. ```html ``` 2. **Use [`adaReadyCallback`](/chat/web/sdk-api-reference#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. ```html ``` ```javascript window.adaSettings = { adaReadyCallback: () => { window.adaEmbed.toggle(); } }; ```