SaganDocs
sagan.vn
VIEN

Website widget ​

The website widget puts a Genie chat window on a web page, such as a page of your intranet. Visitors chat without signing in to Genie, and the widget answers with one agent you choose, from that agent's knowledge bases. You create the widget in Settings, then paste a short snippet into your page.

Before you start ​

  • You need the Admin or Owner role to create or change a widget.
  • Choose the agent the widget will use. Its knowledge bases decide what visitors can ask about, so pick or create an agent for that audience, for example HR assistant for an HR page. See Agents and the default assistant.
  • Widget visitors see unrestricted documents only. Documents with document permissions never appear in their answers.

Create a widget ​

  1. Open Settings → Website widget (in the Publish & integrations group).
  2. Click New embed channel. The setup has five steps; click Next to move on.
  3. Channel info: choose the Bound agent, for example HR assistant. Optionally enter a Name.
  4. Security: in Allowed origins, enter the address of each site that will show the widget, one per line, for example https://intranet.contoso.test. Enter your intranet's address, not Genie's. *.contoso.test allows every subdomain of contoso.test. Adjust Requests per minute (per visitor IP address, default 30) and Daily request cap (for the whole widget, default 10000) if needed.
  5. Capabilities: write a Welcome message, and choose whether to show Suggested questions, Show web search toggle and Show file upload.
  6. Appearance: set the Page title, Header title, Widget position, Default language (English, Tiếng Việt or Browser / host default) and Primary color. The Widget preview shows the result.
  7. Webhooks (optional): enter a Webhook URL on your server and a Webhook secret to receive a message_sent event for each question and a message_received event for each answer.
  8. Click Save. Genie creates the widget and opens the Deploy step.
Screenshot coming soonSettings → Website widget: where you add a widget for an agent and get its embed codewebsite-docs/public/screenshots/en/embed-widget.png
Settings → Website widget: where you add a widget for an agent and get its embed code

Add the widget to your page ​

In the Deploy step, under Copy embed code, choose an embed style and click Copy code:

  • iframe: the full chat in a fixed area of the page.
  • Widget: a floating button in a corner that opens the chat.
  • Secure mode (recommended): a floating button, without the channel key in the page.

For Widget, paste the snippet just before </body> on your intranet page. It looks like this, with your own channel ID and key:

html
<script src="https://genie.contoso.test/genie-widget.js"
        data-channel="2b9f6c3a-7d41-4e0b-9c2d-8a5e1f0b6d73"
        data-token="em_..."
        data-position="bottom-right"
        data-title="HR assistant"></script>

The data-token value is the channel key. Anyone who opens the page can read it in the page source.

Secure mode ​

In secure mode the channel key stays on your intranet server, and the page receives only short-lived tokens. Use it whenever the widget is on a site where people sign in.

  1. Copy the Secure mode snippet. It points to an address on your own server instead of carrying the key:

    html
    <script src="https://genie.contoso.test/genie-widget.js"
        data-channel="2b9f6c3a-7d41-4e0b-9c2d-8a5e1f0b6d73"
        data-token-endpoint="https://intranet.contoso.test/genie/embed-token"
        data-position="bottom-right"></script>

  2. On your intranet server, add that address (/genie/embed-token here). The widget calls it with GET from the visitor's browser, with the intranet's cookies. Your code:

    1. checks that the visitor is signed in to the intranet and may use the widget;

    2. exchanges the channel key for a short-lived token:

      bash
      curl -s -X POST "https://genie.contoso.test/api/v1/embed/2b9f6c3a-7d41-4e0b-9c2d-8a5e1f0b6d73/exchange" \
  -H "Authorization: Embed $GENIE_CHANNEL_KEY" \
  -H "Origin: https://intranet.contoso.test"

      Genie answers {"success":true,"data":{"session_token":"ems_...","expires_in":1800}}. The Origin header must be one of the widget's Allowed origins.

    3. returns {"token":"ems_...","expiresIn":1800} to the browser.

  3. Paste the snippet into your page.

The token lasts 30 minutes, and the widget fetches a new one before it expires. The Deploy step shows complete examples of this server code in Node.js and Go.

Control the widget from your page ​

After the script has loaded, your page can call:

js
Genie.setLocale('vi-VN')                                  // switch the widget to Vietnamese ('en-US' for English)
Genie.openWithQuery('How many days of annual leave do I get?') // open the chat and ask
Genie.setContext({ page: location.pathname })             // send page context with each question

Genie.open(), Genie.close() and Genie.toggle() open and close the chat window.

What visitors see and can do ​

  • Visitors do not sign in to Genie. Their browser remembers their conversation, so it comes back when they reload the page.
  • The workspace's Admins and Owners can read widget conversations in Genie, to follow up on visitors' questions (see Who reads channel conversations). Tell visitors so on the page.
  • Genie answers only with the bound agent and its knowledge bases. The page cannot change the agent, the knowledge bases or the model.
  • Answers use unrestricted documents only.
  • Visitors cannot query Databases or Power BI, and Genie does not run code for them.
  • Web search is available only when the agent has web search on and you chose Show web search toggle; it starts off for each visitor.
  • Visitors can attach files only when you chose Show file upload and the agent accepts images.

Manage a widget ​

  • Channel key: at the bottom of the Deploy step. Use Reveal key and Copy channel key to read it, and Reset channel key if it leaks. After a reset the old key stops working at once, so update every page and server that uses it.
  • Turn a widget off or on: in the list, open the widget's menu and choose Off or On, or switch Enable channel in its settings. A widget that is off refuses every request.
  • Delete: every page that embeds the widget stops working.

Good to know ​

  • Treat the channel key in an iframe or Widget snippet as public: anyone who visits the page can copy it. Never bind an agent whose knowledge bases are not meant for every visitor of that page, keep Allowed origins and the request limits set, and prefer Secure mode.
  • Allowed origins stops other websites from showing your widget in a browser. It does not stop someone who copied the key from calling Genie directly; secure mode and the request limits do.
  • When a visitor goes over Requests per minute or the widget goes over Daily request cap, Genie refuses requests for a while.
  • Widget questions count toward the workspace's monthly budget, if your workspace has one.
  • Only the workspace's Admins and Owners see the Website widget page and its channel keys.