Live Chat SDK — raia Developer Hub

Featured tool

SDK Studio — sdk.raia.run

The hosted tool we built for configuring and testing the Live Chat widget end-to-end. Generate your embed snippet, preview commands live, and copy production-ready code into your app.

Launch SDK Studio

Overview

The raia Live Chat SDK embeds the agent widget into your web app and lets you control it programmatically from JavaScript.

Installation

Paste this script just before the closing </body> tag of your page. The exact tag for your agent is shown in raia Command under the Live Chat Skill settings.

html

<script
  src="https://chat.raiaai.com/widget.js"
  data-api-key="{your-public-agent-id}"
  defer>
</script>

Security note

If you enabled the Live Chat Security Key in raia Command, generate the HMAC token on your backend and pass it during initialization. Never expose your Agent Secret Key in the browser.

The window.raiaChat object

Once the script loads, the SDK exposes a global window.raiaChat object. You interact with the widget exclusively by sending commands through it.

javascript

window.raiaChat.sendCommand(COMMAND_TYPE, payload);

Widget control commands

Command	Payload	Description
`OPEN_CHAT`	`{ page?: string }`	Opens the chat window. Optionally navigates to a specific internal page.
`CLOSE_CHAT`	None	Closes the chat window, minimizing it to the launcher button.
`DESTROY`	None	Completely removes the widget from the DOM and cleans up event listeners.

User & context commands

Command	Payload	Description
`SET_USER`	`{ user: UserInfo }`	Passes user identity (name, email, customData) to the agent.
`CLEAR_USER`	None	Removes the current user identity.
`SET_CONTEXT`	`{ context: string }`	Sets global context that persists across the session.
`CLEAR_CONTEXT`	None	Clears the global context.

Conversation management commands

Command	Payload	Description
`SEND_MESSAGE`	`{ message: string }`	Sends a message to the agent on behalf of the user.
`RESET_CONVERSATION`	None	Clears the current chat history and starts a fresh conversation.
`DELETE_CHAT`	None	Deletes the entire conversation history from the server.
`SET_WELCOME_MESSAGE`	`{ message: string }`	Overrides the default welcome message dynamically.

Example: authenticating a user

The most common use of the SDK is identifying a user after they log into your app. Passing their details via SET_USER lets the agent address them by name and use their account context.

javascript

// After successful login
const userData = {
  firstName: "Jane",
  lastName: "Doe",
  email: "jane@example.com",
  customData: {
    accountId: "12345",
    planType: "enterprise"
  }
};

window.raiaChat.sendCommand('SET_USER', { user: userData });

Frequently asked questions

Can I open the chat when a user clicks a specific button on my site?

Yes — attach a click listener that calls window.raiaChat.sendCommand('OPEN_CHAT').

How do I style the widget to match my brand?

Basic styling (colors, launcher icon, positioning) is configured in raia Command under the Live Chat Skill. For advanced dynamic styling, use the UPDATE_THEME command.

Does SET_USER create a new conversation?

No — it just updates the context for the current session. The agent picks up the new information on the very next message.