Add the Chat Widget to Your Website

The chat widget is the fastest way to put your agent in front of customers or staff. It appears as a small chat button on your page, and it works with any agent you have built. You do not need to write code. You create a widget channel in the console, then hand a short snippet to whoever manages your website, portal or CRM.

Before you start

• Your agent is built and tested. See Test your agent.
• You know who will be chatting: signed-in customers, staff using an internal tool, or anonymous visitors to a public site.
• You know the exact website addresses (origins) where the widget will appear, for example https://portal.your-company.example. Include the port if there is one, such as http://localhost:3000 for a developer's machine. No paths.
• Someone in IT can edit the page or template where the widget will sit.

How the widget knows who is chatting

The widget never asks people who they are. Each channel uses one of three ways to identify the person, and you choose it in the console.

Way	How it works	Best for
Your backend mints tokens	Your website's server, which already knows the signed-in person, asks Achilles for a short-lived pass using the channel key and says who the person is and what role they have.	Quick starts, internal tools, prototypes
Single sign-on (recommended)	Your website's server hands over the person's own signed login token. Achilles checks it with your public key and issues the pass. The channel key alone can no longer act as someone else.	Production sites with their own login
Anonymous guests	No login. Every visitor chats as one read-only role, and the page carries a public key instead of a pass.	Public websites and FAQs

In every case the pass carries the person's role, so the agent only shows what that role should see. The business view of roles is in Users and teams, and the technical view is in the IT overview.

The three keys

The console names every key it shows you, so it is always clear which one you are copying.

Key	Looks like	Where it goes	Secret?
Channel key	chn_live_…	Your website's server only, sent as the X-Channel-Key header	Yes. Shown once
Agent key	the agent's name, for example support-bot	The page, as data-agent-key	No. Always visible
Publishable key	pk_live_…	The page, as data-publishable-key. Guest mode only	No, but shown once

Set it up in the console

Open Deployments under Operate, then Channels, then Web Widget. The page walks you through four numbered steps. Each term has an info icon that explains it and links back to these docs.

1. Create a channel. Name it (for yourself, usually the customer and environment), confirm the agent, choose which roles it may serve, and list the allowed website origins. The widget only works on origins you list. You can change them later from Security on the channel.
2. Choose how users are identified. Pick one of the three ways above. The channel's current way is marked Current.
   • Your backend mints tokens is the default. Nothing else to set up.
   • Single sign-on: enter where your public keys live, the issuer and audience of your login tokens, and which token claims hold the role and other identity fields. Test with a real token from your login system, then switch the channel over. These settings apply to every channel of the same agent.
   • Anonymous guests: choose the guest role and optional message limits per day and per minute, then enable guest mode. Achilles refuses a role that could change data, see unmasked personal data, or needs identity details a guest never has.
3. Copy the keys. A new key appears here with its name, what it is for, and where it goes. Copy it straight away. Only a fingerprint is stored, so it cannot be shown again. Give secret keys to IT through your normal secure method.
4. Add the widget to the site. The code IT needs, already filled in for this channel and for the way you chose in Step 2. See The snippet.

Your channels are listed under Your channels at the bottom. Select one to configure it in Steps 2 to 4, or use the row actions: Security (allowed origins, allowed server addresses, key expiry), Rotate key, Leaked? Rotate now, Disable and Delete.

Treat the channel key as a password

Anyone with the channel key can request passes for the roles you allowed. There are two ways to replace it:

• Rotate key issues a new key. The old one keeps working for 7 days so IT can switch over without an outage. You can end that overlap early.
• Leaked? Rotate now issues a new key and cuts off the old one immediately. Anything still using it stops working at once.

You can also pin the key to your server's IP addresses and give it an expiry date under Security.

The snippet

Step 4 in the console shows the exact code for your channel. IT places it before the end of the page. What it looks like depends on how users are identified.

Your backend mints tokens. The page loads the widget with a pass your server fetched for the signed-in person:

<script
  src="https://widget.achillessystems.co/widget.js"
  data-agent-key="your-agent-key"
  data-api="https://api.your-company.example"
  data-token="SECURE-PASS-FOR-THIS-USER"
></script>

The last line is not something to paste as written. Your website fills it in for each signed-in person, which is the step IT completes.

Single sign-on. The page points the widget at a small endpoint on your own server, which swaps the person's login token for a pass. The widget calls it on load and again before each pass expires, so people never sign in twice:

<script
  src="https://widget.achillessystems.co/widget.js"
  data-agent-key="your-agent-key"
  data-api="https://api.your-company.example"
  data-token-endpoint="/api/chat-token"
></script>

Anonymous guests. One line, no server work. The publishable key is safe in the page because it only works on your allowed origins and only gets short-lived guest passes:

<script
  src="https://widget.achillessystems.co/widget.js"
  data-agent-key="your-agent-key"
  data-api="https://api.your-company.example"
  data-publishable-key="pk_live_..."
  async
></script>

The server-side part for each option is in the IT overview.

Branding and options

You can adjust how the widget looks without touching the agent's behaviour.

Option	What it does	Example
Position	Bottom right (default) or bottom left	Move it away from a cookie banner
Theme	Automatic, light or dark	Match your site
Title	The name in the widget header	Your brand or assistant name
Placeholder	The hint in the message box	Ask about your policy
Colour	Your brand colour	A hex value from your brand guide
Voice	Hide the microphone even if the agent supports voice	Text-only on a specific page

The greeting and the assistant's name come from the agent's own settings, which you can change in the console.

What customers will see

Situation	Experience
Normal answer	A reply in the chat
Progress	Friendly status lines such as looking up your information
A proposed change	A card with the details and Confirm and Cancel. See Approvals
Escalation	A card with a reference number, and the box is switched off. See Human handoff
Long task	A Continue button if the agent reaches its step limit

The widget displays inside its own frame, so your site's styling cannot break it and it cannot affect your page.

Go-live checklist

1. Test on a staging page with each role you allowed, or as a guest if the channel is in guest mode.
2. Check the widget shows only on the listed origins, and remove staging and localhost origins under Security.
3. If you use single sign-on, run the test with a real login token and confirm the role and identity fields come through.
4. Try a change request and confirm the approval card appears.
5. Try a handoff phrase and confirm the notification arrives.
6. Check the widget on a phone.
7. Decide who reviews the first week's conversations. See Monitor your agent.

Limits today

The widget supports text conversations and the approval and handoff cards. It does not support file uploads or rich cards beyond those. If something does not look right, see Troubleshooting.