Chat Interface Embedding

This guide shows you how to embed a Fairo Chat Interface directly into your own application using a secure redirect token.

1. Authenticate with redirect token

Your app should request a short-lived redirect_token for the end user before loading the chat.

curl --location --request POST \
'https://api.fairo.ai/api/v1/auth/redirect_token' \
 --header 'Authorization: Basic <API_KEY:API_SECRET base64>'

Response (example):

{
  "redirect_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Add the redirect_token as part of the url in the iframe, this is a single use token, so don't cache it.

The redirect token tells Fairo "this user is allowed to talk to this interface." You should generate a fresh token per signed-in user in your app, not hardcode one.

2. Embed the chat iframe

Now render the chat interface in your product using an <iframe>.

<iframe
  src={`https://app.fairo.ai/embedded/chat/{{chatInterfaceId}}/${redirect_token}`}
/>

That's it --- once the iframe loads, the user can chat.

3. Typical flow in a react frontend

In a React app, the pattern looks like:

1. Your backend calls POST /api/v1/auth/redirect_token using the credentials.
2. Your frontend asks your backend for that token (never expose org API secret to the browser).
3. You render the iframe with the token.

Pseudo-React:

function EmbeddedAssistant() {
  const [redirectToken, setRedirectToken] = useState<string | null>(null);

  useEffect(() => {
    // Call YOUR backend, not Fairo directly from browser
    fetch(`${your_endpoint}/api/fairo/auth`)
      .then((r) => r.json())
      .then((data) => setRedirectToken(data.redirect_token));
  }, []);

  if (!redirectToken) return null; // or loader

  return (
    <iframe
      src={`https://app.fairo.ai/embedded/chat/{{chatInterfaceId}}/${redirectToken}`}
    />
  );
}