Public chat and form HTTP interfaces

The public chat and form interfaces create ordinary stored site conversations. They do not use MCP bearer tokens or hosting API keys. Prefer the generated widget and managed form handler for normal visitors; use direct HTTP only when building a supported custom integration or performing an authorized diagnostic.

Endpoints and common targeting#

Send JSON with Content-Type: application/json to the application host.

Preserve actual IDs and origins from the integration. Managed hosted requests reject unknown explicit site IDs and conflicting matched origins. Conversations are looked up within the organization and resolved site context. Legacy/companion resolution can differ, so do not rely on an omitted identifier as an isolation mechanism.

Chat example#

{
  "organization_id": 123,
  "site_id": 456,
  "site_origin": "https://example-site.answer.cloud",
  "content": "What services does this organization offer?"
}

Send to https://app.answer.cloud/api/messages. The successful JSON includes conversation, user_message, ai_message, and references. Check a substantive ai_message.content and its cited URLs against the published facts. Relevant titles from the retrieval endpoint alone do not establish answer generation.

Retain conversation.id privately and send it as conversation_id with the same targeting and the next content to continue. A direct API exchange does not verify the widget's rendering, keyboard controls, or mobile layout.

Do not send account passwords, build tokens, private chat history, or a custom system prompt as part of a public diagnostic. Use a short factual question whose answer appears on the intended site.

Structured form example#

{
  "organization_id": 123,
  "site_id": 456,
  "site_origin": "https://example-site.answer.cloud",
  "form": {
    "name": "Project inquiry",
    "fields": {
      "name": "Example visitor",
      "email": "visitor@example.com",
      "message": "Please tell me about your services.",
      "interests": ["Consulting", "Support"]
    }
  }
}

Send to https://app.answer.cloud/api/form_submissions. The form handler saves submitted fields, captures recognized contact fields, starts a new conversation, records a server-side conversion, and queues team notifications. If generation fails, a fallback acknowledgment preserves accepted capture. Success does not confirm email delivery or a team response deadline.

Scalars become trimmed text; null becomes empty text. Nested objects are rejected. Files and native/offline HTML POST fallback are not supported by the managed embed. Optional session_id and tracking use the chat payload: when the embed is available, AEOTracking.buildPayload() supplies session_id and custom_data for tracking.

Browser integration and errors#

A managed form uses data-aeo-form="Name" and an optional data-aeo-form-status element. Set data-aeo-open-chat="false" to retain inline success without automatically opening chat. aeo:form-success carries the parsed API response in event detail; aeo:form-error carries detail.error.

The browser validates native required/email constraints, disables submit controls while pending, preserves input afterward, and does not automatically retry. A direct API call does not itself open or update the widget.

Invalid forms return HTTP 422 with {"error":"..."}. Blank chat content returns 400. An unknown organization, unresolved managed site, or out-of-scope conversation can return 404. Check status and response type before parsing. A network/server error can occur after capture, so inspect the inbox before resubmitting when duplicates matter.

Use a test organization or coordinate test submissions: accepted tests queue real notifications. See forms, answer quality, and troubleshooting.