Chat Widget

The chat widget is a web widget that typically appears at the bottom right corner of a web page. It provides a chat interface with which users can communicate with your AI character.

Creating a Chat Widget

To create a chat widget:

Go to Integrations -> Widgets page
Click the New Chat Widget button
Fill in the fields in the pop up modal
This creates a "dummy" chat widget. To embed the real chat widget in your web app, hover over the dummy chat widget and click on the embed button.
Copy the appropriate code snippet and paste it in your source code.

Integrating with Host Apps

A chat widget integrates deeply with its host app by sending messages to and receiving messages from the host app. The message transfer is accomplished via the use of the window.postMessage() function.

Sending Messages from Chat Widget to Host App

A chat widget will send a message to the host app typically after receiving a message of type FUNCTION_CALL from an AI character. The content of the FUNCTION_CALL message is a stringified JSON object that contains the name and arguments of a function to be executed, as shown below.

{
    content: '{ "func": "changeBackgroundColor", "args": "red" }',
    type: 'FUNCTION_CALL'
}

After extracting the name and arguments from the message, the chat widget will send a message to the host app.

window.parent.postMessage(JSON.parse(message.content), "*");

That is:

window.parent.postMessage({ func: "changeBackgroundColor", args: "red" }, "*");

In order to respond to this message, the host app may register a window event listener as shown below:

window.addEventListener('message', function (event) {
    const key = event.message ? 'message' : 'data';
    const data = event[key];
    if (data.func === 'changeBackgroundColor') {
        changeBackgroundColor(data.args || 'white');
    }
}, false);
 
function changeBackgroundColor(color) {
    document.body.style.backgroundColor = color;
}

Sending Messages from Host App to Chat Widget

A host app can send messages to a chat widget to either trigger a behavior of the chat widget or to trigger a behavior of the AI character powering the chat widget.

In the code snippets below, make sure to replace "proteusai-chat-widget" with the ID of the iframe element hosting the chat widget (or chat page).

Open the Chat Widget

(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'openChatWidget',
}, '*');

Close the Chat Widget

(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'closeChatWidget',
}, '*');

Start a Conversation

This is the equivalent of opening the chat widget and clicking the Start Conversation button on the chat widget.

(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'startConversation',
}, '*');

Set the State of a Conversation

This enters a key-value pair into the state of the conversation. One use case is allowing the host app to store the email or user token of the logged-in user so that actions (e.g. API calls) are performed with the identity of that user.

(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'setConversationState',
    args: {
        key: 'name',
        value: 'Franklin',
        parseValue: false,
    },
}, '*');

Type a Message

This is the equivalent of opening the chat widget, clicking the Start Conversation button on the chat widget, and typing a message in the message text box.

(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'typeMessage',
    args: 'Hello, World!',
}, '*');

Send a Message

This is the equivalent of opening the chat widget, clicking the Start Conversation button on the chat widget, typing a message in the message text box, and clicking the send button.

You can send simple text messages in a variety of ways, as shown below.

(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage('Hello, World!', '*');
 
// or
 
(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'sendMessage',
    args: 'Hello, World!',
}, '*');
 
// or
 
(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'sendMessage',
    args: {
        content: 'Hello, World!',
    },
}, '*');
 
// or
 
(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'sendMessage',
    args: {
        content: 'Hello, World!',
        type: 'TEXT',
    },
}, '*');
 
// or
 
(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    content: 'Hello, World!',
}, '*');
 
// or
 
(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    content: 'Hello, World!',
    type: 'TEXT',
}, '*');

You can also send non-text messages.

(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    func: 'sendMessage',
    args: {
        content: 'https://picsum.photos/200/300',
        type: 'IMAGE_URL',
    },
}, '*');
 
// or
 
(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    content: 'https://picsum.photos/200/300',
    type: 'IMAGE_URL',
}, '*');

Trigger an AI Function

You can send a message of type FUNCTION_CALL to trigger a function belonging to the AI character that powers the chat widget.

For instance, assuming there is an AI character's function named setUserIdentity, you can trigger it from a host app by executing the below code snippet.

const args = JSON.stringify({ name: 'Franklin', email: 'franklin@email.com' });
(document.getElementById('proteusai-chat-widget') as HTMLIFrameElement).contentWindow?.postMessage({
    content: `{ "func": "setUserIdentity", "args": ${args} }`,
    type: 'FUNCTION_CALL',
}, '*');

Integrations Slack