FactQLDocs
Get an API key
Guides

Embed a chat

Add <factql-chat> to any web page and your users can ask questions about your data there. It is one script and one HTML tag, with no framework needed.

Add it to a page

HTML
<script src="https://api.factql.ai/embed/v1/factql-chat.js"></script>

<factql-chat api-key="fl_live_..." end-user-id="user-42"></factql-chat>
  • Use an ask-only key, and list your website under Allowed websites on that key. The chat refuses a full-access key, because anyone can copy a key out of a web page.
  • Set end-user-id to a stable id for the signed-in person, so each person gets their own chats. Without it the chat uses a random id kept in that browser. See Serving many users.
  • The tag works in React, Vue and plain HTML alike. It is 560px tall by default; size it with CSS like any block.

Fit it to your app

Every option is an attribute on the tag. All are optional except the key.

HTML
<factql-chat
  api-key="fl_live_..."
  end-user-id="user-42"
  heading="Ask about your orders"
  greeting="What would you like to know?"
  starters="Which orders are late? | Revenue by region this month | Top 10 customers"
  placeholder="Type a question"
  send-label="Send"
  new-chat-label="Start over"
  max-rows="10"
  locale="en-GB"
></factql-chat>
Wording
headingstring
The title at the top. Default Ask your data.
greetingstring
The line shown before the first question. Default Ask a question in plain English. Set it to an empty string to show no line.
startersstring
Your own suggested questions, separated by |, up to 8. Set none to show no suggestions. When you leave it out, the chat shows up to four questions FactQL suggests for the workspace.
placeholderstring
The hint inside the question box.
send-labelstring
The send button. Default Ask.
stop-labelstring
The same button while an answer is running. Default Stop.
new-chat-labelstring
The button that clears the chat. Default New chat.
Answers
max-rowsnumber
Table rows shown under each answer, 1 to 200. Default 20.
hide-chartflag
Never draw a chart. Answers show text and a table.
show-sqlflag
Show the SQL behind each answer, folded under it.
localestring
en-GB or en-US: the spelling and date style of the written answer.
Connection
api-keystring · required
An ask-only key.
end-user-idstring
The person using your app.
workspace-idstring
Needed only when the key covers more than one workspace.
client-idstring
Needed only when the key covers more than one tenant.

The wording attributes are read when the tag is added to the page, so set them before that. max-rows, hide-chart, show-sql and locale apply from the next answer.

Match your brand

Set theme="light" or theme="dark"on the tag; without it the chat follows the visitor's system setting. Colours, font and corners are CSS variables you set on the tag.

CSS
factql-chat {
  height: 640px;
  max-width: 720px;
  --factql-accent: #0a6650;
  --factql-accent-text: #ffffff;
  --factql-bg: #fbf7f0;
  --factql-surface: #f1ebe0;
  --factql-border: #ded5c4;
  --factql-text: #1b1a17;
  --factql-muted: #6b665c;
  --factql-font: "Inter", system-ui, sans-serif;
  --factql-radius: 6px;
}
CSS variables
--factql-accentcolour
Buttons, the visitor's own question, and chart bars and lines.
--factql-accent-textcolour
Text on the accent colour. Default white.
--factql-bgcolour
The chat's background.
--factql-surfacecolour
Table headers, suggestion buttons and the SQL block.
--factql-bordercolour
Every border and divider.
--factql-textcolour
Main text.
--factql-mutedcolour
Secondary text: status lines, notes, chart labels.
--factql-errorcolour
Error messages.
--factql-fontfont
The font family. Default is the system font.
--factql-radiuslength
Corner radius of the chat box. Default 10px.
A colour you set is used in both light and dark. If your site has both, set theme to the one you styled, or change the variables in your own prefers-color-scheme rule.

React to answers

The tag fires two events you can listen for, and has one method, ask(question), for asking from your own buttons.

JavaScript
const chat = document.querySelector("factql-chat");

chat.addEventListener("factql-answer", (e) => {
  // question, explanation, sql, columns, rows, total_rows, session_id
  console.log(e.detail.question, e.detail.rows.length);
});

chat.addEventListener("factql-error", (e) => {
  console.warn(e.detail.message);
});

// Ask from your own button or link.
chat.ask("Which orders are late?");

What it does with your page

  • Answers are written as plain text, never as HTML, so an answer can't run script on your page.
  • The chat's styles stay inside the tag. Your site's CSS doesn't change it, and it doesn't change your site.
  • It calls FactQL with the key on the tag. Usage counts against your account like any other call; see Limits and errors.