# Oniroco documentation Welcome to Oniroco's developer docs, where you can learn more about Oniroco's API, SDK and developer tooling. You can use Oniroco's SDK to embed our projects into your apps and websites. {% hint style="info" %} Stay up to date with the [latest updates in Oniroco documentation](/whats-new-in-the-oniroco-docs). {% endhint %} ## Get started


Chathive SDK	Start with embedding a Oniroco project into your projects
API documentation	Learn how to work with the Oniroco API	https://documenter.getpostman.com/view/21518222/2s9YC31uAP
Crawler configuration	Learn how to create advanced crawlers	/pages/npD5rZxQDvoT2rmcXmbI
Tools	Enhance enhance your AI with custom tools	/pages/gbJuIzVnTXVdcTBeOStc
Triggers	Trigger your agent when changes happen in your apps	/pages/iNY8EOGQQJJGiaZUItGq

# What's new in the Oniroco docs? The most recent updates includes file upload to both Chatbot and AI form. ## January 2026 * [Tool timeouts](/tools/overview#timeout) * [Tool response body limit](/tools/overview#response-size) ## September 2025 * Fetch private projects through API * Configure conversation timezone * [Agent triggers api](/triggers/api-trigger) * [Custom SDK events](/sdk/custom-tool-events) ## June 2025 * Allow file upload in the chatbot or AI form * Layout changes to accommodate the file upload changes * Crawler config changes * New config * **followRedirect** let's the crawler follow a redirected url and not see it as deleted * Updated config * **pathsToMatch** has been changed to a array to allow for more simpler regex patterns * **pathsToExclude** has been changed to a array to allow for more simpler regex patterns * Crawler will now log any errors with incorrectly configured **pathsToMatch** or **pathsToExclude** regex patterns * [Analytics REST API](/api/rest-api#analytics-endpoints) * Get conversation statistics ## May 2025 * [Crawler login playbook](/crawler/crawler-config/login#playbook) * Extended [Tools template variabels](/tools/overview#template-variabels) with conversation object ## April 2025 * Manage tags through the API ## February 2025 * [Oniroco tools](/tools/overview) * **Link** field add to customer ## November 2024 * [Crawler overview page](/crawler/overview) * Fixed user agent * List with approved IP addresses * Crawler can now crawl documents * Excel * Microsoft Word, Google Docs and LibreOffice * PDF * Powerpoint * Text, Markdown, richText * Crawler config has been expended * documentsToExclude * documentsToInclude ## October 2024 * [Sessions REST API](/api/rest-api#session-endpoints) * AI form SDK [static methods](/sdk/ai-form/methods#static-methods) ## September 2024 * Updated Oniroco's developer documentation * [AI form SDK](/sdk/ai-form) ## August 2024 * [Crawler config](/crawler/crawler-config) added ## April 2024 * [Embed widget](/sdk/chatbot#embed-in-your-page) into your app * Open widget on init * Provide [customer data](/sdk/attributes#customer-data) to the SDK to identify you customers * Provide [context](/sdk/chatbot/methods#context) to the SDK to give the agent where information about the current customer ## March 2024 * New mobile design, Widget is now fullscreen when opened * Add new SDK methods to [enable or disable notifications](/sdk/chatbot/methods#notifications) # REST API {% embed url="" %} ## Analytics endpoints Get analytics from your Oniroco organisations {% embed url="" %} ## Chat endpoints Build custom solutions on top of our API when the [SDK](/sdk/getting-started) doesn’t quite hit the mark. {% hint style="info" %} The chat endpoint uses the public API key that can be found under\ ***project > Implementation*** {% endhint %} {% embed url="" %} ## Document endpoints Push and edit your data to your Oniroco organisation with ease {% embed url="" %} ## Session endpoints Get and update AI form sessions {% embed url="" %} ## Tag endpoints Get, create, update and delete tags {% embed url="" %} # Overview The Oniroco crawler retrieves content from your website, internal knowledge bases, or other online documentation and processes it for your AI assistant. By providing a list of start URLs or a sitemap, the crawler will: 1. Visit each specified page. 2. Identify and follow additional links within your defined URL range. 3. Remove irrelevant data to focus on essential content. 4. Save or update your data in the knowledge base. The crawler is included in all [pricing plans](https://chathive.co/pricing) although advanced configuration options are only available in higher-tier plans. ### Verify Oniroco crawler To verify that a web crawler accessing your servers is genuinely the Oniroco crawler, you can check its user agent or IP address agains our [list of IP addresses](https://chathive.app/ipranges/crawler.json). #### User agent By default, we use the following user agent `OnirocoCrawler/1.0`. However if you have specific requirements, you can customise the user agent that will be used by the crawler. [
](https://www.algolia.com/doc/tools/crawler/getting-started/create-crawler/) # Crawler config ### Parameters


schedule	How often a complete crawl should be performed. once monthly `growth` weekly `advanced` workDays `professional` daily `professional`
executeAt	At which time the crawler should be executed. Formatted `hh:mm` Example: `executeAt: 18:30`
startUrls	Array of URLs the crawler uses as entry points. Example:`startUrls: ["https://example.com"]`
sitemaps	Array of URLs pointing to a sitemap. URLs found in these sitemaps will be used as entry points. Example: `sitemaps: ["https://example.com/sitemap.xml"]`
ignoreQueryParams	Filters out specified query parameters from crawled URLs. This can help you avoid indexing duplicate URLs. Example: `ignoreQueryParams: ["key", "q"]`
ignoreAllQueryParams	Filters out all query parameters from crawled URLs, defaults to true. Example:`ignoreAllQueryParams: true`
extractUrls	Crawlers will extract urls from crawled data and continue to crawl these urls. Only urls that match with any of the start urls will be extracted. default to true. Example: `extractUrls: true`
concurrency	Number of concurrent tasks the crawler can run. Running multiple concurrent tasks may let your server throw 429 error. Excepts a value between 1 and 5, default to 1. Example:`concurrency: 1`
ignoreNoFollowTo	Whether the Crawler should follow links with the `rel=”nofollow”`defaults to true. Example:`ignoreNoFollowTo: true`
followRedirect	Wether the crawler should follow a redirect url or not. If redirect is disabled the current url will be seen as deleted `followRedirect` default to true Example:`followRedirect: true`
maxDepth	Limits how deep we can crawl into the website. `maxDepth: 1` For example, you have a max depth of three: http://example.com depth = 1 ✅ http://example.com/products depth = 2 ✅ http://example.com/products/category depth = 3 ✅ http://example.com/products/category/detail depth = 1 ❌
maxRetries	How many times the crawler should retry a failed url. Excepts a value between 0 and 8, default to 5. Example: `maxRetries: 5`
maxUrls	Limits the number of urls the crawler will process, also applies to the startUrls. Excepts a value greater or equal to 1 Example: `maxUrls: 1`
characterLimit	Limits the number of characters the crawler can use. Can be helpful to keep your costs under control. Excepts a value greater then 500 Example: `characterLimit: 10000`
delay	Time, in milliseconds, the crawler waits before crawling the next URL. This can help to avoid 429 errors. Value between 0 or 30 000 `delay: 4000` Range `delay: {min: 500, max: 30000}` Range will randomly generate a delay between your set range on each new crawl.
timeout	Time, in milliseconds, the crawler waits to get a response from each URL. When the timeout period expires, document will be marked as failed. Accepts a value between 0 and 30 000, default to 30 000. Example: `timeout: 30000`
renderJavaScript	When enabled all web pages are rendered with a chrome headless browser. This is slower but crawls pages in the most realistic form. Defaults to true Example: `renderJavaScript: true`
pathsToMatch	Only urls that match with one of the regex pattern defined in the array will be crawled. Urls must also match with any of your startUrls Example: `pathsToMatch: ["/products\//i"]` the regex must be enclosed in a string* and can contain flags
pathsToExclude	Urls that match with one of the regex pattern defined in the array will not be crawled. Example: `pathsToExclude: ["/products\//i"]` the regex must be enclosed in a string* and can contain flags
documentsToInclude	Documents will only be crawled if it's extension, content-type, mime-type or document type is included in the list. If provide a empty array all documents will be ignored Example: `documentsToInclude: ["word", "text/plain", "csv"]`
documentsToExclude	Documents will only be crawled if it's extension, content-type, mime-type or document type is not included in the list. Example: `documentsToExclude: ["word", "text/plain", "csv"]`
htmlParser	Define how the html of your webpage should be parsed. The parsing process might impact the performance of your agent. Default to smart. Example: `htmlParser: smart` Parser types: `plain`: dumb html parser `smart`: Perserve document structure which can be important for context
headers	HTTP headers that will be added to every request your crawler makes. Example: `headers: { "authentication": "JWT token" }` Only available for `renderJavaScript: true`
userAgent	Customize the userAgent for the crawler. Example: `userAgent: OnirocoCrawler/1.0` Only available for `renderJavaScript: true`
languages	Crawl only webpages that match your configured languages. Languages: Array of languages `ISO6391` codes Strict: if false documents that don't have a language will be crawled if true only documents that have a language that matches your list will be crawled Example: `languages: {languages: ["nl", "en"],strict: false}`
restoreDeletedPages	Defines if the crawler must restore a document that has been crawled previously but has been deleted in Oniroco. default to false. Example: `restoreDeletedPages: false`
acceptCookieConsent	Accept cookie consent policy to prevent it from being crawled. Uses html querySelector to accept the cookie policy. Example: `acceptCookieConsent: { selector: "#buttonId" }` Only available for `renderJavaScript: true`
localStorage	Crawler will pre-fill the webpage local storage on crawl. Example: `localStorage: { "key": "value" }` Only available for `renderJavaScript: true`
sessionStorage	Crawler will pre-fill the webpage session storage on crawl. Example: `sessionStorage: { "key": "value" }` Only available for `renderJavaScript: true`
cookies	Crawler will set cookies for the webpage on crawl, can be helpful to crawl behind a login wall. Example: `cookies: [{ name: "key", value: "value", domain: "example.com" }]` Only available for `renderJavaScript: true`
credentials	Provide HTTP authentication credentials to the crawler, can be helpful to crawl behind a login wall. Example: `credentials: { username: "name", password: "pass" }` Only available for `renderJavaScript: true`
login	Configure complex login methods to crawl behind a login wall. Only available for `renderJavaScript: true`
projectIds	Define to which project the crawler must save the crawled documents. Id can be found in the url of your project. Example: `projectIds: ["66769ce07734ec30a64090e2"]`
advancedLogs	Log more steps and actions your crawler did. Is helpful for debugging or beter understanding your crawler but might make the log files harder to navigate. Example: `advancedLogs: false`
dryRun	In dry run mode crawled documents will not be saved, this setting is purely for debugging/testing your config without wasting resources. Example: `dryRun: false`
debug	In debug mode the crawler will run as dryRun mode. But it will only crawl 5 documents and log the contents of the documents. Can be helpful to debug your parser or other settings that depend on the document content. Example: `debug: false`

# Login This property defines how the crawler can authenticate it self to protected websites. Currently only the playbook is supported our must versatile and flexible authentication option. ## Playbook In the playbook you define a step by step guide how the authentication needs to be completed. ### Playbook types #### GOTO Go to a specific url during authentication or start the authentication at a specific url #### TYPE Type in the value into a input field or type in a generated value * Selector: HTML query selector to select the specific field * Value: Field value * Action: Action that must be taken on the value (generate TOTP) #### CLICK Click on element on the page to continue example the submit button of a form * Selector: HTML query selector to select the element that must be clicked #### WAIT Wait for a specific event to be completed before continuing to the next step * waitForSelector: Wait for a specific element to be visible on the page * waitForNavigation: Wait until crawler has navigated to another page * waitForTimeout: Wait for a pre set timeout ### Examples Simple login form without field id's {% code overflow="wrap" %} ```jsonp { "login": { "playbook": [ // Navigate to the login page { "type": "goto", "url": "https://example.com/login" }, // Type in the required fields { "type": "type", "selector": "input[type='email']", "value": "developers@oniroco.app", }, { "type": "type", "selector": "input[type='password']", "value": "Your_password", }, // Submit form { "type":"click", "selector": "input[type='submit']", }, // Wait until form submit is completed { "type": "wait", "action": "waitForNavigation" } ] }, } ``` {% endcode %} With TOTP token beining asked on a next page {% code overflow="wrap" %} ```jsonp { "login": { "playbook": [ // Navigate to the login page { "type": "goto", "url": "https://example.com/login" }, // Type in the required fields { "type": "type", "selector": "#username", "value": "developers@oniroco.app" }, { "type": "type", "selector": "#password", "value": "Your_password" }, { "type": "click", "selector": "#submitForm" }, // Wait until form is submitted and TOTP field becomes visible { "type": "wait", "action": "waitForSelector", "selector": "#totpToken" }, { "type": "type", "selector": "#totpToken", "action": "generateTOTP", "totp": { "secret": "TOTP_SECRET", "algorithm": "SHA-1" } }, { "type": "click", "selector": "button[type=\"submit\"]" }, // Wait until form submit is completed { "type": "wait", "action": "waitForNavigation" } ] } } ``` {% endcode %} ### Best practices * Always specify a goto url as first step * Use **wait** step as last to be sure login succeeded and credentials are provided # Attributes This page outlines the attributes that can be used to configure your crawler. ## Document types Use these types to support multiple extensions and content types

Type	Extension	Content type
excel	xls, xlsx, csv	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/csv
html	html	text/html
pdf	pdf	application/pdf
powerPoint	ppt, pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint
richText	rtf	text/richtext, text/rtf
text	md, txt	text/markdown, text/plain
word	doc, docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/msword

# Getting started The Oniroco JavaScript SDK provides functions that allow you to easily embed Oniroco projects into your apps or websites and manage their behavior. ## 1. Install To install the SDK on your website, copy and paste the snippet below right before the closing `` tag on every page where you want the SDK and widget to appear. ```html ``` {% hint style="info" %} **Good to know:** If you have a single page app make sure this script is loaded before your try to accessing the SDK {% endhint %} ## 2. Get your API key You can find your api key in your dashboard under the `implementation` tab. ## 3. Init your project Follow the initialization steps for the project type that matches your project.


Chatbot project	Learn how to add a Chatbot project onto your website	/pages/0kTCSfbZHE6Bhp4FBzHP
AI Form project	Learn how to embed a AI form into your website or app	/pages/OJdrXA2UCzBewslND5xv#installation
Triggers	Learn how you can use the SDK to execute a trigger from within your website or app

# Chatbot A chatbot project can be added to your app or website in 2 ways. 1. [As a widget](#initialise-as-widget) 2. [Embedded](#embed-in-your-page) ## Initialise as widget After[ installing the Oniroco SDK](/sdk/getting-started), you’ll need to start up the Widget. Use the code snippet below to make sure the Widget launches every time the page is refreshed. Place this code in the `` tag on every page where you want to show the widget. ```html ``` {% hint style="info" %} **Good to know:** If you have a single page app make sure this is executed after the SDK has been loaded {% endhint %} ## Embed in your page Sometimes a widget doesn't fit into your design. for these purposes we also made it possible to embed the widget into your page. Once you’ve [installed the Oniroco SDK](/sdk/getting-started), you’ll need to specify which HTML tag should contain the widget. Place the following code just before the `` tag, making sure it comes after the HTML tag where you want to embed the widget." ```html ``` ### Example ```markup

``` ## Limitations * Currently only 1 chatbot project can be added to your app or website. # Methods The Oniroco JavaScript SDK provides an JavaScript object with a few methods. These allow you to interact with the widget and customize it's behaviour ## Widget ### Chathive.widget.init The primairy use-case of the SDK is to show the Oniroco widget on your website. This can be done by calling the init method. By default we will immediately show the widget trigger on your website if you don't want this you can provide the hide attribute to hide the widget by default. ```typescript Chathive.widget.init({ apiKey: "YOUR_API_KEY", // Optional attributes language: "en", hide: false, config: { notificationsEnabled: true } }) ``` *see more init options in the* [*attributes*](/sdk/chatbot/attributes#widget-init-attributes) *section.* ### Chathive.widget.embed Instead of showing a widget on your screen, this method will embed your widget into your app.

Chathive.widget.embed({
    apiKey: "YOUR_API_KEY",
    selector: "YOUR_HTML_TAG",
    // Optional attributes
    language: "en",
    hide: false,
})

*see more init options in the* [*attributes*](/sdk/chatbot/attributes#widget-embed-attributes) *section.* ### Chathive.widget.isWidgetLoaded Check if the widget has been initialised and is ready to be used. This will return a boolean ```typescript Chathive.widget.isWidgetLoaded(); ``` ### Chathive.widget.open This will open the widget, if the widget was hidden it will be shown. ```typescript Chathive.widget.open(); ``` If you want to keep the widget hidden, set show attribute to false. ```typescript Chathive.widget.open({ show: false }); ``` ### Chathive.widget.close This will close the widget and keep the trigger visible. ```typescript Chathive.widget.close(); ``` If you also want to hide the widget set hide attribute to true. ```typescript Chathive.widget.open({ hide: true }); ``` ### Chathive.widget.hide Hide the widget from your website ```typescript Chathive.widget.hide(); ``` ### Chathive.widget.isHidden Check if the widget is hidden. This will return a boolean ```typescript Chathive.widget.isHidden(); ``` ### Chathive.widget.show Show the widget on your website ```typescript Chathive.widget.show(); ``` ### Chathive.widget.destroy Remove the widget from your website.\ f you want to re-enable the widget you need to recall the init method. ```typescript Chathive.widget.destroy(); ``` ## Messages ### Chathive.widget.sendMessage Send a message as the website visitor. ```typescript Chathive.widget.sendMessage("YOUR MESSAGE"); ``` ## Language ### Chathive.widget.getCurrentLanguage Get the current language that is used in the widget. By default we will use the language that is marked as default in your dashboard ```typescript Chathive.widget.getCurrentLanguage(); ``` ### Chathive.widget.setLanguage Set or change the language of the widget. We support all [ISO 639-1 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). ```typescript Chathive.widget.setLanguage("nl"); ``` ## Text Most static text that you see in the form can be customised #### getText Get the text configuration that has been set ``` Chathive.widget.getText(); ``` #### setText Set or change the text of your interface. *More info about* [*text configuration*](https://developers.chathive.app/sdk/ai-form/configuration#text-customization) ``` Chathive.widget.setText(TextObject); ``` ## Settings ### isFileUploadAllowed Check if file upload has been allowed ```javascript Chathive.widget.getIsFileUploadAllowed() ``` ### setIsFileUploadAllowed Change if customers are allowed to upload files into the conversation. Will only work if file upload has been enabled in the project. ```javascript Chathive.widget.setIsFileUploadAllowed(allowed: boolean); ``` ## Timezone Customize the timezone for your conversation. By default, the project's timezone will be used. ### getTimezone Returns the current timezone ```typescript Chathive.widget.getTimezone(); ``` ### setTimezone Set or update timezone for the current form interface. ```typescript Chathive.widget.setTimezone("Europe/Brussel"); ``` ## Notifications ### Chathive.widget.disableNotifications Don't get notifications when the widget is closed. Is usefull on mobile devices ```typescript Chathive.widget.disableNotifications(); ``` ### Chathive.widget.enableNotifications Allow notifications to be shown when widget is closed. ```typescript Chathive.widget.enableNotifications(); ``` ## Context ### Chathive.widget.getContext Get the current context of the conversation ```typescript Chathive.widget.getContext(); ``` ### Chathive.widget.setContextField Set or update a new key in the conversation context.\ If you set a value to `undefined` this key will be removed from the context ```typescript Chathive.widget.setContextField({ key: string; value: Boolean | number | string | undefined, }); ``` ## Customer data ### Chathive.widget.getCustomerData Get the data from the current customer ```typescript Chathive.widget.getCustomerData(); ``` ### Chathive.widget.updateCustomerData Set or update the customer data for the current session. This will help you to identify the customer behind a conversation ```typescript Chathive.widget.updateCustomerData(CustomerData| undefined); ``` *More info about* [*customerData*](/sdk/attributes#customer-data) # Events You can listen for emitted events by subscribing to them using the on method with your custom callback. For example, your function can be executed every time the widget is opend ## Chathive.widget.on Subscribes to emitted events, which are described below.\ This function returns a subscription id that can be used to unsubscribe. ```typescript Chathive.widget.on(eventName, () => void); ``` ## Chathive.widget.off Unsubscribes from emitted events, which are described below. ```typescript Chathive.widget.off(subscriptionId); ``` ## Events list

Event name	Description
widget.init	Widget has been initialised and is ready to be used
widget.opened	Widget is opened
widget.closed	Widget is closed
message.inbound	New message is received. Messages are send partially and need to be reconstructed
message.outbound	Message is send by the user
tool.called	Event is emitted when ever a tool is called or ended
tool.custom.event	Event is emitted when ever your custom event emitter tool is called
typing.started	Is typing is triggered by the agent
typing.stopped	Is typing stopped

# Attributes This page details the possible attributes that can be used when Installing the widget ## Widget ### Widget init attributes These attributes will modify the behaviour of the widget and how the agent will respond to messages.

Attribute	Type	Description
apiKey	string	The API key of your project can be found in your project/implementation page.
language	ISO 639-1 language code	The current language of your website visitor. Must be ISO 639-1
open	boolean	Standard open the widget
hide	boolean	Hide or show the widget on your website.
config	config attribute	Widget specific configuration. This will change the behaviour of your widget
context	record<string, Boolean \| number \| string \| undefined>	Extra context that should be used by the agent to provide accurate answers.
customerData	customer data	Data to identify the current customer.
useNewDomain	boolean	opt-in to our new domain names to prevent cookie tracking, but can be blocked by strict enterprise firewalls

### Widget embed attributes These attributes will modify the behaviour of the widget and how the agent will respond to messages.

Attribute	Type	Description
apiKey	string	The API key of your project can be found in your project/implementation page.
selector	string	Select the HTML tag where in the widget must be embedded. Works the same as `document.querySelector`
language	ISO 639-1 language code	The current language of your website visitor. Must be ISO 639-1
context	record<string, Boolean \| number \| string \| undefined>	Extra context that should be used by the agent to provide accurate answers.
customerData	customer data	Data to identify the current customer.

### Config attribute These attributes are used to change the behaviour of your widget

Attribute	Type	Description
notificationsEnabled	boolean	Allow notifications to be shown when widget is closed. Default this is enabled.

## Text customization Most of the static text displayed in the form can be customized. However, text that is set in the form configuration or generated by your assistant cannot be altered. The following text options can be customized during initialization or using `setText()`: #### Text object | launcherAriaLabelClose | Close chat widget | ARIA label for the button that closes the chat widget (when the widget is open). | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | launcherAriaLabelOpen | Open chat widget | ARIA label for the button that opens the chat widget (when the widget is closed). | | closeAriaLabel | Close chat widget | ARIA label for the primary close button inside the chat window header. | | clearNotifications | Close chat notifications | Text or ARIA label for dismissing or clearing notification badges. | | leadGenerationTitle | Talk to a real person | Title of the lead generation or "Contact Me" form/modal. | | leadGenerationDescription | Provide your email address and one of our colleagues will reach out to you. | Description or instructional text for the lead generation form. | | leadGenerationCloseAriaLabel | Close contact me modal | ARIA label for the close button of the contact form modal. | | leadGenerationSubmitButton | Contact me | Text for the submission button on the lead generation form. | | leadGenerationNotificationFailed | We were unable to process your request at this time. Please try again later or explore our available resources for immediate assistance. | Error message shown when the lead generation submission fails. | | leadGenerationButton | Contact me | Text for the button that triggers/opens the lead generation flow. | | isOptionalLabel | (optional) | Label appended to form fields that are optional. | | errorIsRequired | This field is required | Error message displayed when a required field is left empty. | | errorMaxLength | Text cannot be longer then {maxLength, plural, =1 {# character} other {#characters}} | Error message when text input exceeds the maximum length. (`{maxLength}` is a placeholder). | | errorUnsafeNumber | Number is to big | Error message for number inputs that exceed safe JavaScript limits. | | errorInvalidEmail | It seems like the email address you've entered is invalid | Error message for invalid email format validation. | | messageToLong | Your message is too long. Please try to shorten it. | Warning message when a user attempts to send a chat message that is too long. | | sendButtonAriaLabel | Send message | ARIA label for the message send button. | | sourcesLabel | Sources | Label displayed above the list of knowledge sources/citations. | | sourcesShowMoreAriaLabel | Show all sources | ARIA label for the button to expand and show all hidden sources. | | positiveVoteAriaLabel | This answer is helpful | ARIA label for the positive (e.g., thumbs-up) feedback button. | | negativeVoteAriaLabel | This answer is not helpful | ARIA label for the negative (e.g., thumbs-down) feedback button. | | dropzoneTitle | Add files | Title displayed in the file upload dropzone area. | | dropzoneDescription | Drop any file here to add it to the conversation | Description displayed in the file upload dropzone area. | | fileErrorLimitReached | Only {limit} files can be uploaded | Error message when the file count limit is reached. (`{limit}` is a placeholder). | | fileErrorSizeLimit | You've reached the {sizeLimit} upload limit for this message. | Error message when the message's total file size limit is reached. (`{sizeLimit}` is a placeholder). | | fileErrorOrganizationLimitReached | We're unable to accept file uploads at the moment. Please check back soon. | Error message when file uploads are disabled due to organization limits. | | fileErrorUnsupportedType | File type is not supported. | Error message when an unsupported file type is uploaded. | | fileErrorCloseButtonAriaLabel | Hide error | ARIA label for the file upload error banner close button. | | fileFailedAriaLabel | Failed to upload file | ARIA label for the failed file upload icon/status. | | fileIsUploadingAriaLabel | Uploading file | ARIA label for the file uploading status indicator. | | fileDeleteAriaLabel | Delete file | ARIA label for the button to delete an uploaded file. | | uploadAttachmentButtonAriaLabel | Upload attachment | ARIA label for the button to open the file upload dialog. | | carouselPreviousControlAriaLabel | View previous file | ARIA label for the control to view the previous file in a file carousel. | | carouselNextControlAriaLabel | View next file | ARIA label for the control to view the next file in a file carousel. | | messageToolCallFailedTooltip | Failed | Tooltip text displayed when an agent's tool call fails. | | messageToolCallFailedScreenReader | Failed | Screen reader text for a failed agent tool call status. | | messageToolCallSucceededTooltip | Succeeded | Tooltip text displayed when an agent's tool call succeeds. | | messageToolCallSucceededScreenReader | Succeeded | Screen reader text for a successful agent tool call status. | | conversationErrorContentFilter | Your request couldn't be processed due to our content guidelines. Please try a different question. | Error message when a user's message is blocked by content filters. | | conversationErrorUnknown | An unexpected error stopped me from responding. Please try again. | Generic error message for an unexpected conversation failure. | | conversationErrorNotResponding | {name} is currently experiencing some technical difficulties and can't provide an answer at the moment. Please try again in a few minutes. | Error message when the AI assistant is temporarily unavailable. (`{name}` is a placeholder). | | conversationErrorMessageLimitExceeded | An unexpected error stopped me from responding. Please try again. | Error message displayed when the user/session has exceeded a message limit. | | errorApiOverloaded | The agent is temporarily busy, please try again in a few minutes. | Error message when the AI model is temporarily overloaded. | # AI form The AI Form SDK makes it easy to embed your AI form into your application. It offers powerful features to customize the look and feel, ensuring the form blends seamlessly with your app. ## Installation The AI form is already included with the Oniroco SDK. If you haven't installed it into your application, first follow the [SDK installation guide](/sdk/getting-started). ## Setup To setup the AI form, call the constructor to initialise your AI form. There are many options you can pass to the constructor. See the [configuration documentation](/sdk/ai-form/configuration) for more details. ```typescript const aiForm = new Chathive.AIForm({ apiKey: "YOUR_API_KEY" }); ``` {% hint style="info" %} **Good to know:** For single-page apps, ensure this is executed after the SDK has fully loaded. {% endhint %} After initializing your AI form, you can embed it into your application. Ensure this is done after the `selector` element has rendered. The `selector` is a required parameter and uses `document.querySelector` to locate the HTML tag where you want to embed the form. {% code overflow="wrap" %} ```typescript aiForm.embed({ selector: "#embed" }) .then(() => console.log("AI form is embedded")); ``` {% endcode %} # Configuration Learn about general AI form configuration fields. Embedded AI form The embedded AI form offers plenty of customization options to help it blend seamlessly into your application. The following options can be configured in the constructor:

Key	Type	Description
apiKey	`string`	The API key of your project can be found in your project/implementation page.
language	ISO 639-1 language code	The current language of your website visitor. Must be ISO 639-1.
colorScheme	`auto` \| `light` \| `dark`	Shows the color theme choices. `auto` will use your OS color scheme.
context	`record<string, Boolean\|number \|string\|undefined>`	Extra context that can be used to pre-fill the form with data from your customer.
customerData	customer data	Data to identify the current customer.
theme	`Partial<Theme>`	Customise the theme of your form.
text	`Partial<Text>`	Customise the text you see in the form.
useNewDomain	boolean	opt-in to our new domain names to prevent cookie tracking, but can be blocked by strict enterprise firewalls

## Theme customization You can customize the theme of your AI form either during initialization or at any time throughout its lifecycle. The example below demonstrates how to override the default background colors for both light and dark themes.

aiForm.setTheme({
    light: {
        background: "#DCDCDC",
    }
    dark: {
        background: "#1F1F1F",
    },
});

### Theme object

Key	Default light	Default dark	Description
accentColor	#002140	#215E8A	Background color for the button and user message bubbel (overrides color configured in dashboard).
accentFontColor	#ffffff	#ffffff	Text color when background has accent color (overrides color configured in dashboard).
background	#ffffff	#1F1F1F	Background color
cardBackground	#ffffff	#181818	Background message bubble assistant and input field.
borderColor	#e5e7eb	#424242	Border color used in header and around message bubble assistant.
errorColor	#e03131	#fa5252	Color used for error related components.
fontColor	#000000	#ffffff	Text color
warningColor	#ffa500	#fab005	Color used for warning related components.
excelIconColor	#40c057	#40c057	Color used in the Excel file icon
pdfIconColor	#e03131	#e03131	Color used in the PDF file icon
presentationIconColor	#ffa500	#ffa500	Color used in the Presentation file icon
wordIconColor	#228BE6	#228BE6	Color used in the Word file icon
textIconColor	#002140	#002140	Color used in the Text file icon

### Theme priority Theme settings applied during initialisation or by `setTheme()` will override the theme configured in your project's dashboard. However, if you have custom CSS configured in your dashboard, it will always take precedence over any theme settings applied through the SDK or dashboard. The priority order is as follows: 1. Custom CSS 2. `setTheme()` 3. Project theme ## Text customization Most of the static text displayed in the form can be customized. However, text that is set in the form configuration or generated by your assistant cannot be altered. The following text options can be customized during initialization or using `setText()`: ### Text object

Key	Default	Description
errorNotResponding	{name} is currently experiencing some technical difficulties and can't provide an answer at the moment. Please try again in a few minutes.	The message displayed when no response can be generated or connection is lost. ({name} will be replaced with the name of your AI assistant)
errorMessageLimitExceeded	{name} is currently not available at the moment. Please try again in a few minutes.	Error message displayed when no response can be generated because you have exceeded your message limit
errorMaxResponseCredits	{name} currently stopt responding, please try again.	Error message displayed when the agent stopt responing because it hit your credit limit
errorProfanity	Your request couldn't be processed due to our content guidelines. Please try a different prompt.	Error message displayed when the AI models detects the user requested harmful or illegal content or other malicious message.
errorApiOverloaded	The agent is temporarily busy, please try again in a few minutes.	Error message when the AI model is temporarily overloaded.
fallbackTitle	Currently Unavailable	The title of the fallback page when AI form cannot be loaded
fallbackDescription	The AI form isn't available at this time	The message displayed on fallback page
replyFieldTip	TIP: Press enter to send	Tip displayed under reply field
sendButtonAriaLabel	Send reply	The ARIA label of the send button
sourcesShowMoreButtonAriaLabel	Show all sources	The aria label of the show more source button. Once clicked will show all hidden sources
sourcesLabel	Sources	Title above the sources
warningInputToLong	Your input is a bit too long. Please shorten it and try again.	The message displayed when user input is to long
continueButtonLabel	Continue	Button shown when the assistant's last message is not fully typed. By error or by threshold timeout.
dropzoneTitle	Add files	Title in dropzone area when user uploads a file
dropzoneDescription	Drop any file here to add it to the conversation	Description in dropzone area when user uploads a file
fileErrorLimitReached	Only {limit} files can be uploaded	Error message when user tries to upload more then 5 files per message.
fileErrorSizeLimit	You've reached the {sizeLimit} upload limit for this message.	Error message when user tries to upload a file that is bigger then 25MB or the sum of all uploaded files sizes in the message is bigger then 25MB
fileErrorUnsupportedType	File type is not supported.	Error message file is uploaded with unsupported file type
fileErrorOrganizationLimitReached	We're unable to accept file uploads at the moment. Please check back soon.	Error message when user cannot upload any files because organisation has reached it's storage limit
fileErrorCloseButtonAriaLabel	Hide error	File error banner close button ARIA label.
fileFailedAriaLabel	Failed to upload file	File failed to upload icon ARIA label.
fileIsUploadingAriaLabel	Uploading file	File is uploading icon ARIA label.
fileDeleteAriaLabel	Delete file	File delete button ARIA label.
uploadAttachmentButtonAriaLabel	Upload attachment	Upload button ARIA label.
carouselPreviousControlAriaLabel	View previous file	ARIA label carousel back button
carouselNextControlAriaLabel	View next file	ARIA label carousel next button
messageToolCallFailedTooltip	Failed	Tooltip message when tool call has failed
messageToolCallFailedScreenReader	Failed	Screen reader message when tool call has failed
messageToolCallSucceededTooltip	Succeeded	Tooltip message when tool call has succeeded
messageToolCallSucceededScreenReader	Succeeded	Screen reader message when tool call has succeeded

[^1]: # Methods The AI form instance offers various methods to help you interact with and customize it. ## Instance ### Embed Embed the AI form instance into your application. The **selector** is required, and is document querySelector to find the HTML-tag into which you want to embed the form.

aiForm.embed({ selector: "#embed" })

### isLoaded Returns `true` if the instance has been loaded and embedded into your application.

aiForm.isLoaded()

### getVersion Returns the current version of the SDK ```typescript aiForm.getVersion() ``` ### destroy Remove the form interface from your application. ```typescript aiForm.destroy(); ``` ## Styling ### getColorScheme Get the current colorScheme. ```typescript aiForm.getColorScheme(); ``` ### setColorScheme Sets your preferred color theme choices. `auto` will use your OS color scheme. ```typescript aiForm.setColorScheme("auto" | "light" | "dark"); ``` ### getTheme Get the theme configuration that has been set ```typescript aiForm.getTheme(); ``` ### setTheme Set or change the theme of your interface. *More info about* [*theme configuration*](/sdk/ai-form/configuration#css-customization) ```typescript aiForm.setTheme({ light: ThemeObject, dark: ThemeObject, }); ``` ## Settings ### isFileUploadAllowed Check if file upload has been allowed ```javascript aiForm.isFileUploadAllowed ``` ### setIsFileUploadAllowed Change if customers are allowed to upload files into the conversation. Will only work if file upload has been enabled in the project. ```javascript aiForm.setIsFileUploadAllowed(allowed: boolean); ``` ## Text Most static text that you see in the form can be customised ### getText Get the text configuration that has been set ```typescript aiForm.getText(); ``` ### setText Set or change the text of your interface. *More info about* [*text configuration*](/sdk/ai-form/configuration#text-customization) ```typescript aiForm.setText(TextObject); ``` ## Language ### getLanguage Get the current language that is used. By default we will use the language that has been set as default in your project ```typescript aiForm.getLanguage(); ``` ### setLanguage Set or change the language of your interface. We support all [ISO 639-1 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). ```typescript aiForm.setLanguage("nl"); ``` ## Context Context allows you to supply pre-existing information to the form, helping the assistant avoid asking your customer unnecessary questions. ### getContext Get the context that have been set in the form instance. ```typescript aiForm.getContext(); ``` ### updateContextField Set or update a new key in the form instance context. \ If you set a value to `undefined` this key will be removed from the context. ```typescript aiForm.updateContextField( { key: "value" }: Record ); ``` ## Customer data Customer data helps you to identify the customer behind a form session. ### getCustomer Returns the data we known about your customer. ```typescript aiForm.getCustomer(); ``` ### setCustomer Set or update customer data for the current form interface. ```typescript aiForm.setCustomer(CustomerData | undefined); ``` *More info about* [*customerData*](/sdk/attributes#customer-data) ## Timezone Customize the timezone for your conversation. By default, the project's timezone will be used. ### getTimezone Returns the current timezone ```typescript aiForm.getTimezone(); ``` ### setTimezone Set or update timezone for the current form interface. ```typescript aiForm.setTimezone("Europe/Brussel"); ``` ## Static methods ### generateSessionId Generate a unique session id ```typescript Chathive.AIForm.generateSessionId() ``` # Events You can listen for emitted events by subscribing to them using the on method with your custom callback. For example, your function can be executed every time a new message is received ## on Subscribes to emitted events, which are described below.\ This function returns a subscription id that can be used to unsubscribe. ```typescript aiForm.on(eventName, (payload) => void); ``` ## off Unsubscribes from emitted events, which are described below. ```typescript aiForm.off(subscriptionId); ``` ## Events list

Event name	Description
`initialized`	AI form has been initialised and is ready to be used
`error`	Unexpected error has occurred
`message.inbound`	New message is received. Messages are send partially and need to be reconstructed
`message.outbound`	Message is send by the user
`session.completed`	User has filled in all necessary fields. Form session has been marked as completed
`tool.called`	Event is emitted when ever a tool is called or ended
`tool.custom.event`	Event is emitted when ever your custom event emitter tool is called
`typing.started`	Is typing is triggered by the agent
`typing.stopped`	Is typing stopped

# Custom tool events Your AI agent can emit custom events to the SDK whenever it determines an action needs to be handled. By creating a custom tool, you can give your agent the ability to trigger these events. With the event emitter you can give your AI agent the tools to interact with the website it's embedded on. Give it the ability to navigate to open popups, navigate to product details or even open your dedicated live chat. ## Create event tool * In your project's **Tools** section, select **Create Tool**. * Choose `build your own tool`

### Tool setup In this step, you’ll provide the core details of your tool: * **Name**: A unique name (within the project). This name will also be used when the event is emitted, allowing you to identify which event was triggered. * **Description**: A short explanation of the tool’s purpose. * **When to Call Instructions**: Guidance for the agent on when it should call the tool, giving it the context needed to use the tool correctly.

### Tool parameters in the [parameters](/tools/parameters) section you can use JSON schema to define the data your agent should request from the user before emitting the event. * If parameters are defined, the agent will prompt the user for that data. * If left empty, no additional user input will be required. All defined parameters will be included in the emitted event. ### Configure action After setting up the tool and its parameters: 1. Select **Emit Event** as the action type. 2. Save your tool. Your agent can now emit this custom event to your SDK.

## Receive event How you listen for events may vary slightly depending on whether you’re using the [chatbot](/sdk/chatbot/events) or [AI from](/sdk/ai-form/events) SDK, but the process is essentially the same. Once the SDK is initialized, create a subscription to `tool.custom.event`.\ Each time the event is emitted, your callback function will receive the following data: * **Name**: The unique tool name you defined. * **Parameters**: All user-provided parameters plus system parameters. * **Context**: The current conversation context. * **Customer**: Customer information related to the conversation. * **Project**: The associated project name. * **Organization**: The associated organization name. * **Conversation**: Conversation details, including messages and transcriptions. ```javascript Chathive.widget.on("tool.custom.event", ({ name, parameters }) => { console.log("Event name:", name); console.log("Parameters:", parameters); }); ``` # Attributes This page outlines the attributes that can be used or configured in both chatbot and AI form projects. ## Customer data These attributes are used to identify the current customer:

Attribute	Type	Description
id	string	The id of the customer in your system
email	string	Customers emails
firstName	string	Customers first name
lastName	string	Customers last name
avatar	string	Avatar to display for the customer
link	string	Link that redirects users to this customer inside your CRM system

{% hint style="warning" %} Ensure compliance with GDPR laws when setting customer data. {% endhint %} # Overview Tools enhance your AI by connecting it to various apps and services, enabling it to fetch real-time information, update your CRM, send notifications, and much more. They keep your AI up to date and help you get things done efficiently! ## How to create a tool Tools are contained within your project to ensure that sensitive tools aren’t accidentally activated in public projects. You can create a custom tool directly within your project or start with one of our templates. A custom tool relies on an API request executed by the AI model. You can set this up easily using our step-by-step wizard in just 3 simple steps. ### Tool Prompts * **Name:** Give your tool a unique name within your project. * **Description:** Clearly explain what your tool does and what kind of response it will generate. * **When to Call:** Specify exactly when the model should use this tool. Example: ``` name: "get_current_weather" description: "Get the current weather in a given location" when to call: "When the users ask for the weather use get_current_weather" ``` ### Parameters Specify the parameters your AI model must provide to your tool. These parameters are defined using a [JSON schema](https://json-schema.org/), allowing you to leverage its rich features for validation and structure. If no parameters are defined, the AI model will execute your tool without passing any parameters. {% content-ref url="/pages/cJCkyXJBkEGTWSHC0ctM" %} [Parameters](/tools/parameters) {% endcontent-ref %} ### API configuration In the final step, you can configure your API using our **API builder**. ![Screenshot of the api tool setup with a example how to use template variable in the url field and body](/files/qfJPgCgkxk4kLU68s9mQ)
By default, parameters are passed directly into the request body. However, you can override this with a custom request body if needed. This allows you to include additional information, such as conversation context or other values, without requiring the AI model to request them from the user. #### Template variabels In your API setup, you can use **variables** in the **URL**, **query parameters**, **headers**, and **body**. These templates will automatically be replaced with the corresponding values when the tool is called.

Template key	Description
{{parameter_key}}	Access your parameters
{{context.your_key}}	Access the context you've provided to the SDK
{{customer.id}}	Get the id of the conversations customer
{{customer.email}}	Get the email of the conversations customer
{{customer.firstName}}	Get the first name of the conversations customer
{{customer.lastName}}	Get the last name of the conversations customer
{{customer.avatar}}	Get the avatar of the conversations customer
{{project._id}}	Get the id of the project
{{project.name}}	Get name of the project
{{organization._id}}	Get the organization id
{{organization.name}}	Get the name of the organization
{{conversation.language}}	Get the language of the conversation
{{conversation.sessionId}}	Get the sessionId of the conversation
{{conversation.createdAt}}	Get the datetime the conversation was created
{{conversation.updatedAt}}	Get the datetime the conversation was last updated
{{conversation.lastMessageAt}}	Get the datetime the last message was send
{{conversation.tagIds}}	Get `,` -seperated list with all tag ids in the conversation

### Response restrictions #### Timeout To keep your agents running smoothly, tools have a **5-minute** response window before timing out.\ We will lower this timeout in the future to improve performance. #### Response size To keep things running smoothly and avoid overloading the agent, there is a **25MB limit** on all responses. If a tool tries to return more data than that, the call will be stopped and the agent will receive an error message explaining that the response was too big. # Parameters When you configure your tool, you can define the parameters your AI model should provide. These parameters follow a [**JSON schema**](https://json-schema.org/), ensuring structured and validated inputs. ### **Define Parameters in JSON Schema** Each parameter should include: * **name**: The parameter's key. * **type**: The expected data type (`string`, `number`, `boolean`, etc.). * **description**: A brief explanation of the parameter. * **required**: Whether the parameter is mandatory. Here’s an example schema for the **get\_weather** tool: ```json { "type": "object", "properties": { "location": { "type": "string", "description": "The name of the city or geographic coordinates for weather lookup." }, "unit": { "type": "string", "enum": ["metric", "imperial"], "description": "The temperature unit: 'metric' for Celsius, 'imperial' for Fahrenheit." } }, "required": ["location"], "additionalProperties": false, } ``` *** ### **How the AI Uses These Parameters** When the AI calls the **get\_weather** tool, it provides values based on the defined schema. For example, the AI might generate the following request: ```json { "location": "New York", "unit": "metric" } ``` * If a parameter is marked as **required**, the AI will always provide it. * Optional parameters, like `unit`, will only be included if the AI model thinks it is necessary. *** ### **Returning the Response** Once the tool processes the request, it should return a structured response, which can also be formatted before passing it back to the AI. {% content-ref url="/pages/Uz2fvGxXKDE5A1Tl43SB" %} [Format response](/tools/format-response) {% endcontent-ref %} # Format response If your tool returns complex, unstructured, or excessive information, you can format the response before passing it to the AI model. This helps improve the accuracy of the AI’s response and context bloating. You can format the response by writing JavaScript code that modifies the tool’s output. Write your code into the editor, and it will execute once the tool has run successfully. The tool's response is accessible through the **`response`** variable, which is always a string. If you expect a JSON object, you’ll need to parse it first. Once you've formatted the response, ensure you return it as a string to achieve the best results.

Example code how to format the response of the weather tool

### Variables We provide three string variables: * **Response**: A stringified output returned by the tool. * **Session**: A stringified JSON object containing session metadata: *

{ 
      user: object;
      sessionId: string;
      language: string;
      createdAt: string;
      updatedAt: string;
      customer: object;
      context: object;
      projectId: string;
      organizationId: string;
  }

* **Parameters**: A stringified JSON object containing all parameters passed to the tool. ### Tip To ensure the AI model can process the response accurately and effectively. We encourage you to follow these tips: * **For simple data:** Return it as a string that clearly explains the data and its fields. * **For complex data:** If the data cannot be easily formatted into a string, include a description explaining how the AI model should interpret it. Then, return both the description and data as a single string. # API trigger Trigger your agent directly from you apps or websites with the API trigger. ## Create trigger * API triggers are created inside **agent projects**. * Each API trigger must have a **unique name** and **unique key** within the project. * The trigger key is **case-insensitive** and can be customised to match an identifier meaningful for your application. > **Note:** Make sure the key is something easy to reference when making API calls.

### Create API key API triggers are secured by [API keys](https://chathive.app/api_key) that are managed by your organization. * The API key must have at least the permission `project.trigger`

#### Best practices * Only grant the API key access to the specific projects it needs. * Limit the permissions to only what’s required. ## Send a request To call your trigger, send a **POST** request to its unique URL. ``` https://api.oniroco.app/api/v1.0/project/:projectId/trigger/:key ``` This URL can be found in the trigger settings, or construct it using your project ID and trigger key. Optionally, include a JSON body with instruction and configuration. The body will be passed to your filters. * Be processed by the trigger’s filters. * Be passed to your agent as input. The api key you created must be included in the headers of the post request. ```url curl -X POST "https://api.oniroco.app/api/v1.0/project/:projectId/trigger/:key" \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "key": "value" }' ``` ### Request body You can include a body with the trigger to give your AI agent more context when executing your request. The following fields are supported:

Status	Value	Description
instruction	string \| object	Instruction that will be provided to the agent, can be a string or object
sessionId	string	Unique string generated by you to distinguished conversations. When sessionId changes all previous conversation context will be lost and it will be like a new conversation has started
environment	string	Identify in the analytics from where the request came. Default: "api"
language	ISO 639-1 language code	The current language of your website visitor. Must be ISO 639-1
timezone	string	Accepted but request timed out before agent completed it's task. Is only returned when `wait for response` has been enabled and request took to long.
customer	customer data	Data to identify the current customer.
context	record<string, Boolean \| number \| string \| undefined>	Extra context that should be used by the agent to provide accurate answers.

### Response

Status	Description
200	Request has been accepted and agent completed it's task. Body will be included with final response.
202	Request has been accepted but agent is stil executing the task. Is only returned when `wait for response` has been disabled. /
400	Event has been dropped. The body doesn't match the filters
404	Trigger does not exist Trigger has been paused Trigger has been deleted
408	Accepted but request timed out before agent completed it's task. Is only returned when `wait for response` has been enabled and request took to long.

## Advanced Settings ### Customize trigger key Customize the trigger key used in the API to clearly indicate which trigger is being executed in your code. Some key guidelines: * Must be unique within your organization. * Can only contain the following characters: `a-zA-Z0-9_-`.

### Ignore duplicate triggers To prevent executing the same trigger multiple times and waisting AI credits, you can enforce it to only execute triggers with a unique body. Once this is turned on, every trigger that is executed with the same body will be dropped. This will only check triggers that are executed with a body.

### Strict body When you don't have control on how the [request body](#request-body) is send to the trigger. You can disable the strict body option. This will pass the request body completely to the AI agent. \ We recommend to use strict body as much as possible. ### Wait for response For tasks that take a long time (minutes, hours, or days), you can configure the trigger to immediately return a $$(202)$$ success response once the task is accepted. This way, your server doesn't have to wait for the task to finish.

Chatbot project

AI Form project

Triggers