Embed Walkthrough
Below is everything you need to know about the Copilot Embed and its settings.
Authenticating Embed/Authenticating Users Copied!
Generate Authentication Token Copied!
You must retrieve a token from the Embed Authentication endpoint by specifying the user’s uid and the userTier they belong to.
https://api.finchat.io/auth/generate-token Validate Token Copied!
You will then pass this token to the iFrame via postMessage.
Post Message is a secure mechanism for cross-origin communications. We verify the sender's origin before processing the message.
Whe you send this token through Post Message, we verify it in our backend
and extract the
uid
to mint a
Firebase Custom Token
specific to the user. This firebase token is then used in the Embed to
authenticate your user.
Whitelist Your App/Website Domain(s):
Make sure the domain you are embedding from is listed in the allowed domains in the FinChat Partner Portal.
https://finchat.io/enterprise/portal/?tab=organization-settings
Embedding In Different Platforms Copied!
Below you will find examples for Embedding in different environments.
Example of embedding in React:
import React from 'react';
const Embed = () => {
const token = 'YOUR_SIGNED_TOKEN';
const embedKey = 'YOUR_EMBED_KEY';
React.useEffect(() => {
function handleIframeReady(event: MessageEvent) {
if (event.data !== 'READY') return;
const targetWindow = window.frames['finchat'];
if (!targetWindow) return;
targetWindow.postMessage({ token }, 'https://enterprise.finchat.io');
}
window.addEventListener('message', handleIframeReady);
return () => window.removeEventListener('message', handleIframeReady);
}, [token]);
return (
<iframe
name="finchat"
src={`https://enterprise.finchat.io/${embedKey}`}
style={{ border: 'none', width: '100%', height: '100%' }}
/>
);
};
export default Embed;Example of embedding in HTML/JavaScript:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Embed FinChat</title>
<style>
#finchat {
border: none;
width: 100%;
height: 100vh; /* Ensure the iframe takes the full viewport height */
}
</style>
</head>
<body>
<iframe id="finchat" name="finchat" src="https://enterprise.finchat.io/YOUR_EMBED_KEY"></iframe>
<script>
const token = '';
const embedKey = '';
document.addEventListener('DOMContentLoaded', () => {
const iframe = document.getElementById('finchat');
iframe.src = `https://enterprise.finchat.io/${embedKey}`;
function handleIframeReady(event: MessageEvent) {
if (event.data !== 'READY') return;
const targetWindow = window.frames['finchat'];
if (!targetWindow) return;
targetWindow.postMessage({ token }, 'https://enterprise.finchat.io');
}
window.addEventListener('message', handleIframeReady);
// Clean up event listener when the window is unloaded
window.addEventListener('unload', () => {
window.removeEventListener('message', handleIframeReady);
});
});
</script>
</body>
</html> const webViewRef = useRef(null);
const token = "AUTH_TOKEN_HERE";
const key = "EMBED_KEY_HERE";
const url = "https://enterprise.finchat.io/";
const handleMessage = (event: WebViewMessageEvent) => {
event.persist();
if (event.nativeEvent.data !== "READY") return;
if (!webViewRef.current) return;
const message = JSON.stringify({
token,
// query: "Summarize Microsofts Business Model", Optional Query field to trigger a custom query
});
webViewRef.current.injectJavaScript(`
try {
window.postMessage(${message}, "${url}");
} catch (error) {
console.error('Error', error);
}
`);
};
return (
<WebView
ref={webViewRef}
source={{
uri: `${url}${key}`,
}}
onMessage={handleMessage}
/>
);Passing a Query into Embed Copied!
To pass a custom query to the embed and instantly trigger a prompt Simply update the postMessage you send to the iFrame.
const message = {
token: token,
query: 'QUERY_HERE',
}
targetWindow.postMessage(message, 'https://enterprise.finchat.io/')
OR
targetWindow.postMessage(
{token: token, query: 'Your Query Here'},
'https://enterprise.finchat.io/'
)
Company Specific Example Prompts Copied!
Displaying Company Specific Prompts in Embed Copied!
You can opt into displaying AI generated sample prompts for any given company inside the embed.
There are several ways/parameters you can use to display example prompts.
Company Identifier: Recommended Approach
This yields the most consistent results. Use an identifier which uses the company’s exchange code & ticker to generate example prompts.
https://enterprise.finchat.io/YOUR_EMBED_KEY/?identifier=encodeURIComponent("NasdaqGS-AAPL")In order to use the identifier you may need to map your exchange codes to match S&P Global’s methodology .
Company Name:
Use the company name to display AI generated example prompts.
https://enterprise.finchat.io/YOUR_EMBED_KEY/?name=encodeURIComponent("Apple Inc.")Company Ticker:
Use the company ticker to display AI generated example prompts.
https://enterprise.finchat.io/YOUR_EMBED_KEY/?ticker=encodeURIComponent("AAPL")Retrieve Company Sample Prompts in API Copied!
You can use the API to retrieve the sample prompts in multiple languages.
Retrieve Embed User Data Copied!
Fetch and paginate user data: Copied!
curl 'https://finchat.io/api/organization/users?apiKey=ENTERPRISE_KEY&page=1'Retrieve data for a specific user/user ID Copied!
curl 'https://finchat.io/api/organization/users?apiKey=ENTERPRISE_KEY&user=USER_UID'User Data Format Copied!
The user data is returned in the following format:
{
uid: string;
org: string;
tracking?: { timestamps?: number[] };
navChats?: {
favorites: Array<{ uid: string; title: string; favorite: boolean }>;
chats: Array<{ uid: string; title: string; favorite: boolean }>;
};
language?: string;
chats: {
uid: string;
title: string;
messages: {
id: string;
interactionId: string;
content: string;
role: 'user' | 'bot';
createdAt: string;
updatedAt: string;
aborted?: boolean;
relatedQuestions?: string[];
flagged?: 'helpful' | 'unhelpful';
}[];
}[];
};Data structure explained
uid: // The users unique identifier
org: // The users organization, will match your unique organization
tracking: // The timestamps of the users recent prompts. This is used for controlling/regulating their usage.
navChats: // The nav items which populate their sidebar. Seperated in to items they have marked as a favorite and regular chats
language: // The users selected language
chats: // The full array of the users chats with your embed