Returning.AI
  1. Widgets
Returning.AI
  • Returning.AI
    • APIs
      • Authentication
      • System API
        • Auth
          • Secure Auth
          • register
          • verify email
          • login
        • Server
          • create new server
          • get my servers
          • update server
          • channel list of server
        • Channel
          • get channels list
          • create new channel
          • update channel
          • delete channel
        • Role
          • role list of server
          • create new role
          • update role
          • delete role
          • get role list of user on a server
          • add role to a user on a server
          • remove role from a user on a server
        • Badge
          • get badges list
          • create new badge
          • update badge
          • delete badge
          • award badge to user
          • remove badge from user
      • Application API
        • Community Users
          • Get community users
          • Get user
        • User Fields
          • Get All User Fields
          • Get Specific User Field
          • Create Custom User Field
          • Update Custom User Field
          • Delete Custom User Field
        • User Field Histories
          • Get all user field histories in a community
          • Get user field histories for a specific field
          • Get user field histories for a specific user
          • Get user field histories of specific user field and user
          • Create user field history for specific user
      • Integration API
        • Users
          • Get Users with Filters
          • Create New User
          • Get User Data
          • Manage User Account
          • Get User Gamification History
          • Get User Gamification Stats
          • Bulk Import
          • Bulk Update
          • Get All Bulk Update
          • Check Bulk Update Status
          • Check Bulk Update Details
          • Bulk Update Copy
        • Messages
          • Get Messages
          • Send Message
          • Reply Message
          • React Message
        • Channels
          • Get Channels List
        • Xp Settings
          • Get Tier Info
      • User API
        • API key
          • Get User Api Key
          • Post User Api Key
          • Update User Api Key
          • Delete Endpoint
          • api key info
        • Messages
          • Direct Channel
            • React Message Copy
            • Send Message
            • Reply Message
          • Forum Channel
            • Send Message
            • Reply Message
            • React Message
          • Text Channel
            • Reply Message
            • Send Message
            • React Message
          • Send Message
          • Reply Message
          • React Message
    • Channels
      • Iframe
    • Events
      • Outgoing webhooks
        • Encryption
        • User Joins Server
        • User Visits server
        • New Message Posted Anywhere
        • New Message Posted To channel
        • Purchased Store Item
      • Incoming webhooks
        • API Keys & Encryption
        • Send message into channels
        • Update Custom User Fields
        • Update In-game currency
    • Widgets
      • Authenticated Widgets
      • Public widgets
    • Features
  1. Widgets

Authenticated Widgets

Returning.AI Widget Integration Guide#

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:
1.
Community ID {{community_id}} - Your unique community identifier
Where to find it?
1.
In your admin settings.
2.
Find the Appearance page.
image.png
2.
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?
1.
In your admin settings.
2.
Head to the feature for the widget. (The channel widgets will be used as an example here)
image.png
3.
Widget ID {{widget_ID}} - The specific widget instance identifier
Where to find it?
1.
In your admin settings.
2.
Head to the feature for the widget. (The channel widgets will be used as an example here)
3.
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:
1.
Calls your backend endpoint to get a token
2.
Stores the token in localStorage
3.
Listens for token requests from the widget iframe
4.
Securely sends the token to the iframe using postMessage API

Step 5: Embed the Widget#

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
Modified at 2025-10-22 09:39:31
Previous
Widgets
Next
Public widgets