Authenticated Widgets

A step-by-step guide to embed interactive community widgets on your platform with user authentication.

Step 1 Get the required credentials

Before implementing the codes to run the widgets, you'll need the following:

Community ID {{community_id}} - Your unique community identifier

Where to find it?

In your admin settings.

Find the Appearance page.

Widget API Key {{WIDGET_API_KEY}} - Your secret API key for authentication

Important

Keep your {{WIDGET_API_KEY}} secret! Never expose it in frontend code or commit it to public repositories.

Where to find it?

In your admin settings.

Head to the feature for the widget. (The channel widgets will be used as an example here)

Widget ID {{widget_ID}} - The specific widget instance identifier

Where to find it?

In your admin settings.

Head to the feature for the widget. (The channel widgets will be used as an example here)

In the Iframe code example, the widget ID is in the URL.

Step 2: Understanding the Architecture

The widget uses a secure authentication flow that requires a backend server:

Your Frontend → Your Backend → Returning.AI API → Token → Widget

Why not call the API directly from the frontend?

Your {{WIDGET_API_KEY}} would be exposed in the browser

Anyone could steal your API key and impersonate users

This could lead to unauthorized access and security breaches

Backend requirement: You need a server-side endpoint that can securely store and use your API key.

Step 3: Set Up Backend Authentication

Call an endpoint on your server that authenticates users with the Returning.AI widget API.
Endpoint:
POST https://prod-widgets.returning.ai/widget/{{community_id}}/signin
Required Headers:

returningai-api-key: Your Widget API Key (from admin panel)

email: The logged-in user's email from your auth system

Content-Type: application/json

Response: Returns a token on success (200 status).

Note: The token is valid for one session. If authentication expires, the widget will request a new token automatically.

Examples:

Node.js

PHP

Python

Step 4: Add Frontend Authentication Script

Add this JavaScript to your frontend to handle the authentication flow and secure communication with the widget iframe.

How it works:

Calls your backend endpoint to get a token

Stores the token in localStorage

Listens for token requests from the widget iframe

Securely sends the token to the iframe using postMessage API

Insert the iframe code into your HTML to display the widget.

Parameters to Replace:

{{widget_type}}: The type of widget (see supported features below)

{{widget_ID}} : Your specific widget ID from the admin panel

Supported Widgets type

Choose the feature you want to embed:

Channels

Allow users to interact and send messages via the widget.
Widget Type: channel-widget

Use Case: Community chat, discussions, announcements

Store

Milestone

Currency Overview

Troubleshooting

Common Issues

Widget not loading?

Check that your community_id, widget_type and widget_ID are correct

Verify the iframe URL matches the format exactly

Check browser console for errors
Authentication failing?

Ensure your WIDGET_API_KEY is correct and stored securely in environment variables

Verify the user's email is being passed correctly to your backend

Check that your backend endpoint is accessible from the frontend
Token not being received by widget?

Verify the postMessage listener is active before the iframe loads

Check that event.origin matches exactly: https://prod-widgets.returning.ai

Getting Help

If you encounter issues that are difficult to debug, reach out to the Returning.AI support team for assistance.

Security Checklist

Before going to production:

API key is stored in environment variables (never in code)

API key is never exposed to the frontend

Backend endpoint validates user authentication

postMessage listener checks event.origin

HTTPS is enabled on your domain

API key is not committed to version control

Quick Start Checklist

Obtained community_id, WIDGET_API_KEY, and widget_ID from admin panel

Created backend authentication endpoint

Added frontend authentication script

Embedded iframe with correct widget type and ID

Tested authentication flow

Verified widget loads and functions correctly

Returning.AI Widget Integration Guide

Step 1 Get the required credentials

Step 2: Understanding the Architecture

Step 3: Set Up Backend Authentication

Step 4: Add Frontend Authentication Script

Step 5: Embed the Widget

Supported Widgets type

Troubleshooting

Common Issues

Getting Help

Security Checklist

Quick Start Checklist

Authenticated Widgets

Returning.AI Widget Integration Guide#

Step 1 Get the required credentials#

Step 2: Understanding the Architecture#

Step 3: Set Up Backend Authentication#

Step 4: Add Frontend Authentication Script#

Step 5: Embed the Widget#

Supported Widgets type#

Troubleshooting#

Common Issues#

Getting Help#

Security Checklist#

Quick Start Checklist#

Returning.AI Widget Integration Guide

Step 1 Get the required credentials

Step 2: Understanding the Architecture

Step 3: Set Up Backend Authentication

Step 4: Add Frontend Authentication Script

Step 5: Embed the Widget

Supported Widgets type

Troubleshooting

Common Issues

Getting Help

Security Checklist

Quick Start Checklist