Website Chat Widget

Overview

The chat widget puts one of your agents on any website as a chat bubble in the corner of the page. Visitors chat with the agent directly - they don’t need a Rival account, and they never see your workspace.

The whole integration is one <script> tag. The agent does not need to be published: a private agent can run on your site and stay off the marketplace.

Where to find it

Open the agent, open its Settings drawer, and pick the Integrate tab. Switch the toggle at the top from API (A2A) to Chat widget. It has two tabs:

• Setup - turn it on, set allowed origins, copy the snippet, choose what visitors can reach.
• Appearance - name, icon, opening message, colour, position, and theme.

Only an org Owner or Admin can change the chat widget. Other members can see the settings, with the note “Only an organization owner or admin can change the chat widget.”

The Integrate tab is available on adopted agents too.

Setting it up

1. Turn on the chat widget. Switch it on; the status chip changes from Off to Live.

   Turning the widget on also switches on Integrate over A2A for the agent - the widget runs over that connection.

2. Add your Allowed Origins. Type your domain (for example acme.com) and click Add. One domain per entry, exact match only - subdomains are separate, so add www.acme.com too if you use it. If you leave out the scheme, https:// is assumed.

3. Copy your snippet. It looks like this:

   <script src="https://cdn.rival.io/chatbot/embed.js" data-key="rvw_..." data-api="https://cortexone-api.rival.io" async></script>

   The rvw_ key inside it is meant to be public - see Keys and security.

4. Paste it into your website, just before the closing </body> tag on every page that should show the bubble. The Setup tab has short instructions for WordPress, Webflow, Squarespace, and Shopify.

5. Choose what visitors can reach (both off by default), then click Save:

   • Use tools - lets the agent call its tools and connected accounts for a visitor.
   • Read knowledge base - lets the agent answer from the selected knowledge base.

Caution

No domains listed means the key works from any website. That’s fine while you test; add your domain before you go live.

Keys and security

The rvw_ key in the snippet is public by design - anyone can read it from your page source. What protects you is the Allowed Origins list: a browser on any site not on the list is refused, so nobody can paste your snippet into their own site and run up your bill.

Allowed Origins stops other websites, not determined attackers - it is not authentication. Keep that in mind when choosing what visitors can reach:

• Use tools lets a stranger’s question reach the accounts this agent is connected to - your CRM, your mailbox - using your credentials, with nobody reviewing it.
• Read knowledge base makes anything in the selected base answerable to anyone on the internet. Only turn it on for documents you would publish.

Rotating the key. Click Issue a new key to get a fresh snippet. Your old snippet keeps working for 7 days so you have time to update your site; a banner shows the date it stops.

What visitors can do. Visitors are anonymous. They can send messages and read the agent’s replies - nothing else. They can’t choose the model or reach any other part of Rival.

Pages opened straight from disk (file://) are always refused. Test from a real web server.

Appearance

The Appearance tab has a live preview. Changes apply when you save.

Setting	What it does	Default
Name	Shown in the chat header (up to 60 characters)	The agent’s name
Icon	PNG, JPG, WebP or SVG, up to 2 MB	The agent’s icon
Opening message	The first thing a visitor reads (up to 300 characters). Leave empty for none	Empty
Accent colour	The bubble, the visitor’s messages, and the send button	#1a73e8
Position	Bottom left or Bottom right	Bottom right
Theme	Match visitor (follows their device’s light or dark setting), Light, or Dark	Match visitor

Per-site overrides

To override Appearance on one site only, add these attributes to that site’s <script> tag:

Attribute	Values
data-theme	light, dark, or auto
data-accent	A hex colour, for example #e11d48
data-position	left or right

Conversations

A conversation lasts as long as the visitor’s browser tab. Closing the tab and coming back starts a new conversation.

Cost and limits

Visitors don’t pay. Answers run on your organization’s account and cost what a normal chat turn costs. Your organization needs a positive Run Balance, or the widget stops answering.

To protect your balance, the widget is rate limited:

• 500 messages a day per agent, across every site the snippet is on. After that, visitors see “This chat has reached its message limit for today.”
• Per-visitor and per-key rate limits. A visitor who sends too fast sees “Too many messages right now. Try again in a moment.”

Troubleshooting

What you see	Why
No bubble appears	The widget is switched off, or the snippet isn’t on the page. Check the Live chip on the Setup tab
”This website chat key is not enabled for …”	The site isn’t in Allowed Origins. Add it exactly as it appears in the browser address bar, including www. if present
”This agent’s organization cannot currently fund requests.”	Your Run Balance is empty. Top Up
”This website chat is not available. It may have been switched off.”	The widget was switched off, or the key was replaced more than 7 days ago. Copy the current snippet
”This chat has reached its message limit for today.”	The 500-message daily limit was reached. It resets the next day

Next steps

• Agent-to-Agent (A2A) - the connection the widget runs over, for calling the agent from your own code
• Knowledge Base - the documents the widget can answer from
• Personality & Guardrails - shape how the agent talks to visitors