1. Widgets
Returning.AI
  • Getting Started
  • Authentication
    • Secure Auth
      GET
    • register
      POST
    • verify email
      POST
    • login
      POST
  • Users
    • Get user
      GET
    • Get Users with Filters
      POST
    • Create New User
      POST
    • Get User Data
      POST
    • Manage User Account
      POST
    • Get User Gamification Stats
      POST
    • Get all mini game logs by user email
      POST
    • Get user's current Mini Games and Streak stats
      POST
  • Roles & Permissions
    • role list of server
      GET
    • create new role
      POST
    • update role
      PUT
    • delete role
      DELETE
    • get role list of user on a server
      GET
    • add role to a user on a server
      POST
    • remove role from a user on a server
      POST
  • Servers
    • create new server
      POST
    • get my servers
      GET
    • update server
      PUT
  • Channels
    • channel list of server
    • get channels list
    • create new channel
    • update channel
    • delete channel
    • Get Channels List
  • Messaging
    • Get Messages
    • Send Message
    • Reply Message
    • React Message
    • Upload Image
  • User Data
    • Get All User Fields
    • Get Specific User Field
    • Create Custom User Field
    • Update Custom User Field
    • Delete Custom User Field
    • 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
  • Gamification
    • get badges list
    • create new badge
    • update badge
    • delete badge
    • remove badge from user
    • award badge to user
    • Get Tier Info
    • Get User Gamification History
    • Get User Gamification Logs
  • Streaks & Mini Games
    • Get Streak Logs
  • Rewards & Redemptions
    • Update redemption transaction status
    • Get all redemption transactions by user email
    • Get All Redemption Statuses
    • Get Redemption Status by ID
    • Get all redemption transactions by Community
    • Create Redemption Status
  • Chart Analysis
    • Create Analysis
    • Get Analysis
    • Update Analysis
    • Delete Analysis
    • List Analyses
    • Append Drawings
  • Bulk Operations
    • Bulk Import
    • Get All Bulk Update
    • Check Bulk Update Status
    • Check Bulk Update Details
    • Bulk Update
    • Premium Currency Bulk Update
  • Application API
    • Community Users
      • Get community users
      • Get user
  • Integration API
  • 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
  • Community Analytics
    • Get Loyalty Overview
  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 2026-03-24 09:39:51
Previous
Widgets
Next
Public widgets
Built with