Widget and embed · API docs

The widget lets visitors ask questions of the church's approved teaching from any web page, without you running a server or exposing a key.

Embed it#

Create a widget in the console under Widget. You get a site key. Add one script tag:

Code

<script src="https://folio.example.org/embed.js" data-key="wk_live_8f3a1c9d2b7e" async></script>

Optional attributes: data-theme="light" or "dark" to override the page theme.

The site key and the allowlist#

A site key is public: it is safe in page source. It only works from origins you list in the widget's allowlist. A call from another origin answers 403 origin_not_allowed. Add every origin that embeds the widget, including your staging site.

The widget needs the widget feature on the church's plan and must be switched on in the church's settings. Sandbox churches cannot use it.

What visitors get#

Visitors are anonymous. The widget generates a random session string in the browser (16 to 128 URL-safe characters) and sends it with each question so the visitor can ask follow-ups. Answers are drawn from approved teaching only. Questions that suggest a crisis get care guidance and a hand-off to the church instead of a model answer. Feedback visitors give goes to the church's review queue; it is never used as training data.

Build your own front end#

The public endpoints the widget uses are open to you. They take the site key as key and the browser's Origin header.

curl -X GET "$FOLIO_API_URL/v1/public/widget?key=wk_live_8f3a1c9d2b7e"

Ask a question. The response is 202 with status pending, or 200 if the same question already has a reviewed answer:

curl -X POST "$FOLIO_API_URL/v1/public/widget/messages?key=wk_live_8f3a1c9d2b7e" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "What did we teach about forgiveness?",
  "session": "k3n9x2m8q1w7e5r4t6y0"
}'

Poll for the answer. wait holds the request open for up to that many seconds:

curl -X GET "$FOLIO_API_URL/v1/public/widget/messages/msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012?key=wk_live_8f3a1c9d2b7e&session=k3n9x2m8q1w7e5r4t6y0&wait=10"

Response

{
  "status": true,
  "message": "widget_answer",
  "data": { "object": "widget_answer", "status": "complete", "answer": "Forgiveness is a decision to release a debt, as God released ours. [1]", "sources": [{ "number": 1, "title": "Seventy times seven", "excerpt": "We forgive because we were forgiven." }], "follow_ups": [] }
}

status is pending, complete or failed. Honour poll_after_ms while pending.

Public Ask on the church's site#

Without a site key, POST /v1/public/{church}/ask asks from the church's public page about its published teaching, and GET /v1/public/{church}/ask/messages/{message} polls for the answer. Published, reviewed answers are readable at GET /v1/public/{church}/ask/{slug}.

Limits#

Visitors are rate limited, a church's widget has a busy ceiling (429), and each new question counts against the church's Ask allowance. Hide the box when you receive 402 or 403.

Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.