AI assistant web component configuration

This page lists the options of the AI assistant web component.

The latest URL gets each new release in one minute or less:

https://cdn.redocly.com/ai-assistant/releases/latest/main.js

To decide when you get a release, use a version URL instead, for example releases/v1.0.0/main.js. A version URL never changes. The changelog lists each version and its changes. To find the version of the script on a page, enter RedoclyAssistant.version in the browser console.

Add the script only one time on each page.

Add these attributes to the <redocly-ai-assistant> element. If you change an attribute after the page loads, the assistant applies the change, except for open.

A boolean attribute is true when the element has it, for example <redocly-ai-assistant trigger-hide>. To make it false, remove it or set it to "false".

<redocly-ai-assistant
  api-url="https://docs.acme.com"
  variant="panel"
  position="bottom-left"
  color-mode="dark"
></redocly-ai-assistant>

<redocly-ai-assistant
  api-url="https://docs.acme.com"
  trigger-text="Ask Acme"
  header-title="Acme Assistant"
  logo="https://app.acme.com/images/logo.svg"
  welcome-message="Hi! Ask me anything about Acme Payments."
  suggestions='["How do I create an API key?", "How do I test webhooks?"]'
></redocly-ai-assistant>

<redocly-ai-assistant
  api-url="https://docs.acme.com"
  product="Payments"
  version-folder="v2"
  version-label="2.0"
></redocly-ai-assistant>

The script adds the window.RedoclyAssistant object to the page. Its methods apply to all assistants on the page.

setConfig() takes an object with the keys that you want to change. A key wins over its attribute, and the other attributes stay as they are. Each call adds its keys to the keys of the earlier calls, and setConfig(null) removes them all. You can call setConfig() before you add the element to the page. setConfig() does not check the values, so use only the values from the attribute tables.

Each key is the name of an attribute in camelCase, for example apiUrl for api-url. These keys are different:

• suggestions takes an array of strings.
• version takes the version folder and label as one object, for example { folder: 'v2', label: '2.0' }.
• open, trigger-hide, resizable, and movable have no key.

These keys have no attribute:

The assistant sends these events to window. Each event.detail has element, the element that sent the event.

To change a variable, add a CSS rule for the redocly-ai-assistant element to your site.

redocly-ai-assistant {
  --button-bg-color-primary: #0f766e;
}

The rule sets the variable in both color modes. If color-mode is system, set the dark mode values in a media query:

@media (prefers-color-scheme: dark) {
  redocly-ai-assistant {
    --button-bg-color-primary: #2dd4bf;
  }
}

Use only the variables in this table, so your styles keep working after an update. The assistant also uses other variables internally, and any release can rename or remove them.

The width and height attributes win over the size variables.

The locale value also sets the language of the interface. The assistant has these languages: ar, de, en, es, fr, hi, it, ja, ko, pl, pt, pt-BR, uk, and zh (Simplified Chinese). For a regional value, the assistant uses the language part, for example es for es-ES. For other values, the interface is in English.

To change the interface text, or to add a language, set translations with setConfig():

window.RedoclyAssistant.setConfig({
  translations: {
    'aiAssistant.contactSupport': 'Talk to our team',
    'search.ai.placeholder': 'Ask about Acme Payments...',
  },
});

The keys that you do not set keep the text of the interface language. The text attributes, for example header-title, win over translations.

{
  'aiAssistant.trigger': 'Ask AI',
  'aiAssistant.triggerLabel': 'AI Assistant button',
  'aiAssistant.triggerLabel.answering': 'AI Assistant button, answering',
  'aiAssistant.triggerLabel.unread': 'AI Assistant button, new answer',
  'aiAssistant.headerTitle': 'AI Assistant',
  'aiAssistant.closeWidget': 'Close widget',
  'aiAssistant.resizeHandle': 'Drag to resize',
  'aiAssistant.contactSupport': 'Contact support',
  'aiAssistant.support.intro': 'To reach the support team, fill in the form below:',
  'aiAssistant.support.name': 'Name',
  'aiAssistant.support.email': 'Email',
  'aiAssistant.support.message': 'Message',
  'aiAssistant.support.cancel': 'Cancel',
  'aiAssistant.support.send': 'Send',
  'aiAssistant.support.sending': 'Sending…',
  'aiAssistant.support.error': 'Failed to send your request. Try again.',
  'aiAssistant.support.created': 'Your request has been sent to the support team. They will get back to you by email.',
  'search.ai.placeholder': 'Ask a question...',
  'search.ai.followUpQuestion': 'Ask a follow-up question...',
  'search.ai.generatingResponse': 'Generating response...',
  'search.ai.thinkingText': 'Thinking...',
  'search.ai.suggestionsTitle': 'Suggestions',
  'search.ai.newConversation': 'New conversation',
  'search.ai.resourcesFound.basedOn': 'Based on',
  'search.ai.resourcesFound.resources': 'resources',
  'search.ai.toolCall.executing': 'Executing',
  'search.ai.toolCall.executed': 'Executed',
  'search.ai.toolCall.usedTools': 'Used tools',
  'search.ai.feedback.title': "What didn't you like about this response?",
  'search.ai.feedback.detailsPlaceholder': 'Add specific details',
  'search.ai.feedback.more': 'More...',
  'search.ai.feedback.thanks': 'Thank you for your feedback!',
  'search.ai.error.header': 'Oops! Something went wrong.',
  'search.ai.error.description': 'We encountered an issue while processing your search. Try again later or refine your query. If the problem persists, please contact Redocly support.',
  'search.ai.error.header.forbidden': 'Feature Unavailable',
  'search.ai.error.description.forbidden': 'AI assistant is currently unavailable.',
  'search.ai.error.header.unauthorized': 'Authentication Required',
  'search.ai.error.description.unauthorized': 'You are not authorized to use AI assistant.',
}

If your site sets a Content-Security-Policy header, add the sources that the assistant needs:

Content-Security-Policy:
  script-src 'self' https://cdn.redocly.com;
  connect-src 'self' https://docs.acme.com;
  style-src 'self' 'unsafe-inline'

• AI assistant web component - Add the assistant to your site
• Answer from login-protected content - Let the assistant use protected content for the users who sign in to your site
• Configure AI assistant support escalation - Let users send a conversation to your support team