Community API Reference

How It Differs From the External Widget API

The Community API and the External Widget API serve different surfaces and have different security models:

Use this API when the chatbot lives behind a Salesforce Experience Cloud login. Use the External Widget API when the chatbot is on a public website.

Base URL

Served from your Experience Cloud site, under the path /services/apexrest/redaai/chat/community/v1/:

https://<your-community>.my.site.com/<site-path>/services/apexrest/redaai/chat/community/v1/

The exact host depends on your Experience Cloud configuration. Calls from inside the portal naturally use the portal’s session cookie for authentication.

Authentication

There is no API key. The endpoint trusts Experience Cloud’s session cookie to identify the calling portal user. Two consequences:

• Calls from a guest (unauthenticated) context are rejected with AUTH_REQUIRED.
• Calls from outside the portal that don’t carry the session cookie are also rejected.

This is why the Community API is naturally same-origin: the standard Experience Cloud session cookie won’t accompany cross-origin requests to the portal’s domain.

Endpoints

Six endpoints, all POST:

POST /chat/community/v1/init

Resolves the agent and either resumes the portal user’s most recent conversation with that agent (when one exists within the agent’s session timeout) or creates a fresh one.

Request body

{
  "agentName": "support-assistant"
}

Response (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "https://…/mascot.png",
  "maxMessageLength": 2000,
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "…" },
    { "role": "assistant", "content": "…", "timestamp": "…" }
  ]
}

When the response includes a non-empty messages array, the conversation was resumed; render the prior turns to preserve continuity. Otherwise the conversation is brand new.

Resume window

Resume eligibility is governed by Session Timeout Minutes on the agent definition (default 30). The platform finds the portal user’s most recently active conversation with that agent, checks that its last activity is within the timeout window, and resumes it if so.

POST /chat/community/v1/new

Forces a fresh conversation even if a recent one exists. Useful for “Start over” UI controls.

Request body

{
  "agentName": "support-assistant"
}

Response (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "…",
  "maxMessageLength": 2000
}

No messages array is returned because the conversation has no history yet.

POST /chat/community/v1/message

Sends a single user message to the agent and returns the reply.

Request body

{
  "conversationId": "<from /init or /new>",
  "message":        "What's open on my case 00012345?"
}

The platform validates that the calling portal user owns the conversation. Cross-user access is rejected.

Response (200 OK)

{
  "response":            "<agent reply text>",
  "creditsUsed":         1.42,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   0
}

continuationPending is the flag your client must act on. When the agent executed one or more actions during this turn, it returns true — meaning there is an outcome it has not narrated yet. Call /continue to get that narration. Ignoring the flag leaves the user looking at a reply that stops before the result of what just happened.

POST /chat/community/v1/action

Executes a confirmed action. Only Action tools assigned to the agent and scoped to the Community channel are accepted.

Request body

{
  "conversationId": "<from /init>",
  "actionTool":     "create_record",
  "params": {
    "object_name":  "Case",
    "field_values": { "Subject": "Issue with login", "…": "…" }
  }
}

Response (200 OK)

{
  "success": true,
  "result":  "<tool execution result, JSON-serialised>"
}

POST /chat/community/v1/continue

Asks the agent to narrate the real outcome of actions it auto-executed on the previous /message turn. No new user message is sent. Call it whenever the previous response came back with continuationPending: true.

Request body

{
  "conversationId":    "a0Q…",
  "continuationDepth": 0
}

Pass back the continuationDepth you received from the previous response. Omitting it is treated as 0.

Response (200 OK)

{
  "response":            "<agent narration of what happened>",
  "creditsUsed":         0.68,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   1
}

continuationPending stays true if the agent chained another action while narrating — so this is a loop, not a single follow-up call. Keep calling /continue, feeding back the returned continuationDepth each time, until it comes back false. The agent’s Max Continuation Depth setting bounds the chain, so the loop always terminates.

POST /chat/community/v1/history

Returns the conversation’s messages for the active portal user. Useful when the portal page reloads and needs to restore the visible thread.

Request body

{
  "conversationId": "a0Q…"
}

Response (200 OK)

{
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "…" },
    { "role": "assistant", "content": "…", "timestamp": "…" }
  ]
}

Error Responses

Same shape as the External Widget API:

{
  "error": "<localised user-facing message>",
  "code":  "<machine-readable code>"
}

Rate Limits

Same controls as the External Widget API, with two differences:

• Per-session limits are tracked per portal user, not per opaque session token.
• The daily credit cap is the Community Daily Credit Cap Platform Setting, not the External cap.

To lift the daily credit cap entirely, leave Community Daily Credit Cap blank or set it to 0 — both mean unlimited. It is deliberately a separate setting from the External Widget cap, so a busy public widget can never exhaust the budget your portal members rely on.

Conversation Ownership

Conversations are owned by the portal user who started them. The platform validates ownership on every /message, /action and /history call — calling with a conversationId belonging to another user is rejected with INVALID_INPUT.

This is the security boundary that lets the Community API run without API keys: the portal user’s own permissions and ownership govern what they can see and do.

The portal user’s Contact is supplied to the agent automatically. Experience Cloud users are linked to a Contact record through User.ContactId. When a conversation is created by /init or /new, REDA AI resolves that Contact and stores it as the conversation’s context record, then injects it into the system prompt on every subsequent turn. The agent therefore knows who it is talking to — name, account, and whatever other Contact fields you configured as context — without the client sending any identifying data, and without any per-agent setup.

A portal user with no Contact (rare, but possible for some Experience Cloud licence types) simply gets a conversation with no context record. Nothing fails.

Required Configuration on the Agent

Security Posture

• Authentication is the portal’s. No API keys to issue, rotate or leak. Every call inherits the portal user’s session.
• Permissions are the portal user’s. CRUD, FLS and sharing rules on the portal user’s profile govern what the agent and any tools can read or write — including which records they can see in the conversation history.
• Ownership is enforced on every call. A portal user cannot read another portal user’s conversations even if they obtain the conversation ID.
• Tool channel scoping applies. Only Action tools whose Channels include Community are usable here.
• Daily credit cap is the safety net. The Community Daily Credit Cap prevents a runaway portal bot from exhausting the licence budget.
• Generic error messages. Internal error details are never echoed; failures are recorded in the Incident Log for admin investigation.

Best Practices

Use the shipped community bridge component. The Lightning component for Experience Cloud handles the API calls, session resumption and UI rendering. Building a custom client only makes sense for non-portal contexts.

Resume rather than restart. Calling /init at the start of every page view is the right default — the platform will resume the recent conversation transparently. Reserve /new for explicit user-driven “Start over” controls.

Set a sensible Session Timeout. Too short and users lose context across page loads; too long and stale conversations resume when users intended a fresh start. The default 30 minutes is a reasonable starting point.

Watch the Community Daily Credit Cap. It’s independent of the External cap and tunable per the volume of authenticated portal users you serve.

Confirm tool channel scoping. An Action tool that’s only assigned to Internal won’t fire from a portal call — even if the agent is configured for it.

Review conversation continuity

A blank Conversation Window (Hours) now uses the organisation default, initially 30 minutes. A positive value sets the agent's window; 0 disables automatic resume. Matching remains channel-specific: API uses agent and record context; authenticated Internal/MCP uses agent, user and the relevant record context. Community uses the shared window setting instead of the external-session timeout. Home, app-page and utility-bar chat can resume eligible conversations. Explicit conversation identifiers remain subject to their route's access checks. Review agents that relied on blank meaning a new conversation, and use 0 where that behaviour is required. Packaged permission fixes also address Internal and Community conversation access.

Frequently Asked Questions

Next Steps

Read Community Agent Setup for the deployment walkthrough, or External Widget API Reference for the unauthenticated counterpart.