External Widget Setup
AI funding and usage
AI included uses REDA credits. Bring your own AI uses your organisation’s provider account, billed directly by that provider. The licence selects one funding model for the organisation. In either model, REDA AI governs configured tools and actions in Salesforce. Set up your licence and AI accounts.
If the administrator changes the effective AI connection, model or funding mode, affected chat sessions need a new conversation. Start a new chat when asked; the old account’s conversation cannot simply continue on the new route. For customer accounts, verify credential access for the website guest or signed-in portal identity. See connection permissions.
An agent with Channel = External_Widget is bound to the public widget surface only. It cannot be invoked from the internal Salesforce LWC, from Flow / Apex (API channel), or from a community/portal page. Conversely, the public REST endpoint (/chat/v1/*) only accepts agents whose Channel is set to External_Widget — routing an Internal, API, or Community agent through this surface is rejected with a clear error. Pick the channel that matches the surface you intend to deploy on.
What is the External Widget?
The External Widget lets you embed a REDA AI chat widget on your website, portal, or web application. Visitors can ask questions, search your data, and get help — all without logging into Salesforce.
- No Authentication Required — Visitors chat without a Salesforce login
- Guest Access — Uses a configured Guest User profile with limited, controlled permissions
- Origin Restrictions — You control exactly which domains can embed the widget
- Fully Configurable — Colors, text, layout, bubble style, and welcome screen are all customizable via embed attributes
- Mobile Responsive — Automatically adapts to mobile screens with optional full-screen mode
Setup Overview
-
Configure the Agent Definition
Set the channel to External_Widget and configure allowed origins, welcome message, and tools.
-
Generate the API Key
Create an External API Key that the widget uses to authenticate.
-
Embed the Widget
Add a single script tag to your website with the API key and endpoint.
-
Customize Appearance
Add optional
data-*attributes to control colors, layout, bubble style, and welcome screen.
Step 1: Configure the Agent Definition
- Navigate to the REDAAI Agent Definition object in Setup
- Open or create an Agent Definition record
- Set Channel to
External_Widget - Set Allowed Origins to the domain(s) where the widget will be embedded (e.g.
https://example.com, https://www.example.com) - Set External Welcome Message to a greeting for visitors (e.g. “Hi! How can we help you today?”)
- Optionally upload a Mascot Image for a custom avatar
- Assign appropriate tools (read-only recommended for guest users)
- Activate the agent
Step 2: Generate an API Key
The widget authenticates using an External API Key. See API Key Management for detailed steps. You will need two values from the API key record:
- API Key — the generated key string
- Endpoint URL — the Salesforce Sites REST endpoint (format:
https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1)
Step 3: Embed the Widget
Add a single <script> tag to your website. The REDA AI Loader handles everything — loading the widget, applying your configuration, and initializing the chat.
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key-here"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1">
</script>
Replace <org> with your Salesforce org’s My Domain prefix and your-api-key-here with the actual API key.
The data-api-key and data-endpoint attributes are required. Without them, the widget will not load.
This key is public. It sits in your page's HTML, so anyone viewing the page source can read it — that is by design for a public widget, and it is why the key alone must never be enough to reach anything sensitive. Two controls do the real work: Allowed Origins, checked against the browser-set Origin header (page JavaScript cannot forge it), so the key only works when called from your domains; and the guest user's own permissions, which cap what any conversation can reach no matter what the agent is asked. Configure both as if the key were on a billboard.
Full-Featured Embed Example
You can add optional data-* attributes to customize the widget’s appearance and behavior:
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key-here"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-title="Support Agent"
data-primary-color="#0070D2"
data-bubble-style="pill"
data-bubble-label="Ask Support"
data-header-style="minimal"
data-welcome-heading="How can {title} help?"
data-welcome-subtext="Ask me anything about your account"
data-theme="light"
data-position="bottom-right"
data-display-mode="bubble">
</script>data-display-mode="docked-right" (or docked-left) and the assistant opens as a full-height panel docked to that edge, instead of a floating card — useful when answers include property cards or photos. The launcher bubble stays exactly where it is. See Display Mode.
See Widget UI Customization for the complete list of data-* attributes.
Configuring Allowed Origins
The Allowed Origins field on the Agent Definition controls which domains can embed your widget. This is a security feature that prevents unauthorized embedding.
Allowed Origins is empty by default, and empty means no restriction — any website that has your API key can use your agent. Because the API key is visible in your page’s source code (unavoidable for any embeddable widget — see Step 2), anyone can copy it from your site. Filling in Allowed Origins is what stops another website from using your agent, and your credits.
We recommend setting it on every live widget.
https://example.com, https://www.example.com, https://support.example.com
The widget loads only on these three domains. Any other domain is blocked.
- Always include the protocol —
https://example.comandexample.comare treated differently - Separate multiple domains with commas
- List every domain your visitors actually use — if
www.example.comandexample.comboth serve your site, include both, or the widget will fail on one of them - Test before going live — embed on a staging domain first to verify it works, and add the staging domain to the list while you do
When Allowed Origins is set, REDA AI checks the website the request genuinely came from, as reported by the visitor’s browser. A page cannot claim to be a different site, so your key will not work if it is copied onto someone else’s website.
Two things follow from this. Requests that do not come from a browser at all are refused when Allowed Origins is set — so if you call the chat API directly from your own server, leave Allowed Origins blank and control access another way. And an allowlist is one layer, not the whole story: the per-conversation, hourly and daily limits on the Agent Definition are what cap usage if a key is ever misused.
Upgrading? If Allowed Origins is blank — the default — nothing changes for you. Widgets keep working exactly as before.
Know what the allowlist does and does not stop. It works because browsers set the
Origin header themselves and page JavaScript cannot override it — so a stolen key
pasted into another website is refused. It cannot stop a server-side caller
that forges the header, from curl or any script. No origin allowlist can.
What limits that case is everything else: the per-session and per-hour rate limits, the org-wide daily credit cap, and revoking the key. Treat Allowed Origins as the control that keeps your widget on your own pages, not as authentication.
Guest User Permissions
External Widget agents run under a Guest User profile. This profile should be carefully configured:
- Limited Object Access — Grant access only to objects visitors need (e.g. Knowledge, Case)
- Limited Field Access — Expose only public, non-sensitive fields
- Sharing Rules — Guest users can only see records marked as public via sharing rules
- Write Access (Optional) — Grant create access sparingly (e.g. only for Case creation)
Always review your Guest User profile and sharing rules before deploying an External Widget. Test as a guest user to verify exactly what data is accessible.
Recommended Tools for External Widgets
Be conservative with tool assignments for guest-facing agents:
| Tool | Recommended? | Notes |
|---|---|---|
soql_query |
Maybe | Only if guests need to search public records (e.g. knowledge base articles) |
get_record |
Maybe | If guests should view details of specific public records |
count_records |
Maybe | Useful for answering “how many” type questions on public data |
create_record |
Rarely | Only if visitors should create records (e.g. support cases). Restrict to specific objects. |
describe_object |
No | Exposes schema details — not appropriate for external users |
send_email |
No | Security risk — never assign to external widgets |
update_record / delete_record |
No | Guests should not modify or delete records |
web_search |
Optional | Enable via Allow Web Search on the Agent Definition. Incurs additional credit cost per search. |
How Actions Work on the External Widget
The External Widget is a conversational, customer-facing channel, so it does not show the confirmation cards used on the Internal channel. Instead, the agent auto-executes an Action tool and then automatically replies with the real outcome — e.g. “Thanks! I’ve created your request as Case #00001234.” If the action fails, it reports that honestly. The number of automatic follow-up turns is capped by the Max Continuation Depth platform setting (default 3). Because the widget runs as the shared Site guest user, assign Action tools deliberately and keep guest permissions tight. See Action Confirmations → How confirmations differ by channel.
Common Use Cases
Visitors open the chat on your support page. The agent answers FAQs, searches knowledge articles, and offers to create a support case for complex issues.
Tools: soql_query, create_record (Cases only)
Prospects on your website chat with the agent. The agent qualifies the lead and creates a Lead record for follow-up.
Tools: soql_query, create_record (Leads only)
Tenants or customers ask about properties, bookings, or account details. The agent searches public data and provides answers.
Tools: soql_query, get_record
Widget Appearance Overview
The widget supports extensive customization through data-* attributes on the embed script tag:
- Bubble Style — Circle (default) or pill-shaped button with a text label
- Header Style — Colored (brand background) or minimal (white/clean)
- Welcome Hero — Branded welcome screen with heading, avatar, and optional subtext
- Colors — Primary color, header background, user message color, background, text, and borders
- Typography — Custom font family and font size
- Dimensions — Panel width, height, bubble size, and border radius
- Position — Bottom-right or bottom-left
- Theme — Light or dark mode
- Mobile — Configurable breakpoint and optional full-screen mode
- Text / i18n — All labels, placeholders, ARIA text, and error messages are customizable
For full details and examples, see Widget UI Customization.
Best Practices
Review the Guest User profile permissions carefully. Ensure no sensitive data is exposed. Test the widget as a guest to verify what data is accessible.
Keep Tools Minimal — Only assign tools that guests actually need. Each tool adds to token usage and potential data exposure.
Write Appropriate Guardrails — Add Guardrail prompts to restrict agent behavior. Example: “Never discuss internal pricing. Always offer to connect the user with sales.”
Monitor Conversations — Review conversation logs regularly to understand visitor questions. Use insights to improve your knowledge base or adjust agent behavior.
Test on Multiple Devices — Verify the widget works on desktop, tablet, and mobile before going live.
Frequently Asked Questions
You add a single <script> tag to your page. The REDA AI Loader automatically fetches the widget code with cache-busting, applies your configuration from data-* attributes, and initializes the chat. No additional JavaScript is required.
Yes. Add all domains to the Allowed Origins field on the Agent Definition (comma-separated). Use the same embed code on each site.
The API will reject requests from domains not listed in Allowed Origins. The widget will not function on unauthorized domains.
Yes. Create separate Agent Definition records, each with their own API key and allowed origins. Each website gets its own embed code pointing to the appropriate API key and endpoint.
Yes. The widget attaches to the page once on load and persists across route changes. It uses a Shadow DOM, so it does not conflict with your application’s styles or JavaScript.
Yes. All customization is done via data-* attributes on the embed script tag. No CSS or JavaScript changes are needed. See Widget UI Customization for all options.
Next Steps
Customize your widget’s appearance with Widget UI Customization, or review Data Access & Permissions to secure your guest user setup.