Skip to main content
The widget puts an agent in the bottom right corner of your pages, as a chat bar. Under Character you can put a small pixel bot on the bar. While someone types, it follows the words along the bar. Press Enter and the bar grows into a chat. While the agent works, the character acts it out with one word beside it (Thinking, Reading, Scouring, Writing). When it runs a browser or computer task, the chat shows the task’s progress: a bar and a few short steps written for the visitor, ticked off as the agent gets through them, with how long it’s been going. Visitors see the agent’s answers, the forms it shows them and that progress. They never see its tool calls, what its worker is doing at each moment, or its browser.

​
Add it to your site

  1. In the console, open the agent and go to Widget. Turn on On your website.
  2. List the Domains that may show it, like example.com. Each domain covers its subdomains. Leave the list empty to allow any site.
  3. Copy the snippet and paste it into your pages, before </body>:
The Widget tab shows your own snippet, with these steps for each kind of site: For Next.js:
Visitors chat with the agent’s published version. To try your changes first, switch the agent’s Test chat (beside its settings) from Chat to Widget. You see the same conversation as visitors would, on a stand-in website, running your draft. To see it on your own site instead, type its address in the field above the preview (your widget’s domains are suggested). A cloud browser opens the page and the widget runs on a picture of its first screen, at the preview’s size, as phones get the page when the preview is narrow. Pop-up offers and cookie notices are left out of the picture. Pop out opens that test page in its own window. Turning the widget off removes it from every site at once. Your team can still test it in the console.

​
Control it from your page

The script defines window.Eager:

​
Tell the agent who it’s talking to

Eager.set gives a new conversation values it starts knowing, so the agent doesn’t ask for them:
Call it before the visitor’s first message (values set later apply to their next conversation). Names are lowercase letters, numbers and _; values are text up to 1,000 characters. The agent also knows Eager’s own: today’s date and the time in the visitor’s time zone, their browser’s language, the page they’re on, and the channel (widget, or share_link on a share link). A procedure’s input with the same name, like account_id, is taken as given. The page sets these, so a visitor can change them: they say who the visitor claims to be, and the agent treats them that way. Don’t use them to grant access to anything. To call it before the script has loaded, queue the calls:
No website needed: turn on Share link in the agent’s Widget settings and send the link (https://guidinghand.ai/a/…) to anyone. It opens a page that’s only the chat with the published version. No one signs in, and the page can’t be put in another site’s frame.
  • Off by default. Turn it off and the link stops working at once; turn it on again and it’s the same link.
  • New link. Makes a new address and ends the old one, for when a link has gone further than you meant.
  • Same as the widget. The same limits (counted together with the widget’s), visitors see only their own conversations, and the chats appear in Conversations marked share link and are billed to your org like any other chat.

​
How it works

  • Isolated from your page. The widget runs in an iframe, so your CSS can’t change it and its CSS can’t change your page. The iframe takes only the room the widget needs, and the rest of your page stays clickable. The iframe can only be shown on your listed domains: the browser enforces this with frame-ancestors.
  • Visitors and their conversations. Each visitor’s browser keeps a random key and their conversation. When they come back to your site, the conversation is still there. New chat starts over. Only that browser can read or continue the conversation.
  • In the console. Widget conversations appear in Conversations marked website, with the site they came from. They are billed like any other chat, by tokens, to your org.
  • Limits. Each visitor can send 40 messages an hour, each network 120, and a widget answers up to 1,000 messages an hour across all its visitors. The widget accepts text messages and form answers. Visitors can’t upload files.
  • Coming back mid-reply. If a visitor reloads or moves to another page while the agent is still answering, the widget picks the reply up when it finishes.
  • On phones. The widget rests as the character alone. Tapping it opens the chat full screen.
Set the widget from code with GET and PATCH /v1/agents/{agent_id}/widget: enabled, domains, character, placeholder (the bar’s text), suggestions (typing suggestions for visitors, on by default), share (the share link, share_url in the reply) and new_share_link: true (a new link, ending the old one). character is none (the bar alone, the default) or bot (the pixel support bot).