API reference

Widget

The embeddable Ask widget, identified by a site key and the calling origin.

GET/v1/public/widget

Resolve a widget site key#

Resolves a site key (created in the console under Widget) for the calling origin. The browser sends Origin; the origin must be in the widget's allowlist or the call answers 403 origin_not_allowed. The site key is public and safe in page source.

Auth. None. This route is public.

Plan. The church needs the widget feature, and it must be on in the church's settings.

Auth: No key
Plan: The church needs the widget feature, and it must be on in the church's settings.
Operation id: widgetConfig

Parameters

Parameters
Name	In	Description
`key`	query	The widget's public site key, created in the console under Widget. (string, e.g. wk_live_8f3a1c9d2b7e)
`Origin`	header	Sent by the browser: the page making the call. It must be in the widget's allowlist. (string)

Responses

200 Success. Resolve a widget site key.

200 example

{
  "status": true,
  "message": "widget",
  "data": {
    "object": "widget",
    "church": "grace-chapel",
    "name": "Grace Chapel",
    "mode": "ask",
    "settings": {
      "greeting": "Ask about our teaching"
    }
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

403 The calling origin is not in the widget's allowlist.

403 example

{
  "status": false,
  "message": "This site is not allowed to use this widget.",
  "error": {
    "code": "origin_not_allowed",
    "status": 403,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

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

POST/v1/public/widget/handoff

Hand a question to the church#

A visitor asks a pastor, or a crisis contact, to follow up. The church sees it in its care queue. Collect only what the visitor offers; email or phone lets the church reply.

Auth. None. This route is public.

Auth: No key
Operation id: widgetHandoff

Parameters

Parameters
Name	In	Description
`key`	query	The widget's public site key, created in the console under Widget. (string, e.g. wk_live_8f3a1c9d2b7e)
`Origin`	header	Sent by the browser: the page making the call. It must be in the widget's allowlist. (string)

Request body

Request body fields
Field	Type	Description
`email`	`string (email)`	The email address.
`kind`	`enum: pastor \| crisis_contact`	The kind.
`name`	`string`	The name.
`phone`	`string`	A phone number the church can call back.
`question`	`string`	The question, up to 1000 characters.

Example request body

{
  "kind": "pastor",
  "name": "Ada",
  "email": "[email protected]",
  "phone": "",
  "question": "Could a pastor call me about forgiveness?"
}

Responses

200 Success. Hand a question to the church.

200 example

{
  "status": true,
  "message": "handoff",
  "data": {
    "id": "hof_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
    "status": "open"
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X POST "$FOLIO_API_URL/v1/public/widget/handoff?key=wk_live_8f3a1c9d2b7e" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "pastor",
  "name": "Ada",
  "email": "[email protected]",
  "phone": "",
  "question": "Could a pastor call me about forgiveness?"
}'

POST/v1/public/widget/messages

Ask from the widget#

Asks a question from a page that embeds the widget. The response is 202 with status pending and poll_after_ms, or 200 with a finished answer when the same question was already answered and reviewed. Poll GET /v1/public/widget/messages/{message} for the answer. Visitors are identified by an anonymous session string you generate (16 to 128 URL-safe characters) and keep in the browser.

Questions that need a person (a crisis) are answered with care guidance and a hand-off instead of a model answer. Visitors are rate limited, and a church's widget has a busy ceiling.

Auth. None. This route is public.

Plan. Needs the widget and Ask features. Each new question counts against the Ask allowance; 429 when the church's allowance is used up for visitors.

Auth: No key
Plan: Needs the widget and Ask features. Each new question counts against the Ask allowance; 429 when the church's allowance is used up for visitors.
Operation id: widgetAsk

Parameters

Parameters
Name	In	Description
`key`	query	The widget's public site key, created in the console under Widget. (string, e.g. wk_live_8f3a1c9d2b7e)
`Origin`	header	Sent by the browser: the page making the call. It must be in the widget's allowlist. (string)

Request body

Request body fields
Field	Type	Description
`question`	`string`	The question, up to 1000 characters.
`session`	`string`	An anonymous visitor id you generate: 16 to 128 URL-safe characters.

Example request body

{
  "question": "What did we teach about forgiveness?",
  "session": "k3n9x2m8q1w7e5r4t6y0"
}

Responses

200 Success. Ask from the widget.

200 example

{
  "status": true,
  "message": "widget_answer",
  "data": {
    "object": "widget_answer",
    "answer": "",
    "blocks": [],
    "follow_ups": [],
    "sources": [],
    "next_steps": [],
    "conversation_id": "conv_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
    "message_id": "msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
    "status": "pending",
    "poll_after_ms": 800
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

429 The visitor asked too quickly, or the church's widget is busy.

429 example

{
  "status": false,
  "message": "Please wait a little before asking again.",
  "error": {
    "code": "rate_limited",
    "status": 429,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

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"
}'

GET/v1/public/widget/messages/{message}

Poll a widget answer#

Returns the current state of an answer. status is pending, complete or failed. Pass wait (seconds) to hold the request open until the answer arrives. Use the same session you asked with.

Auth. None. This route is public.

Auth: No key
Operation id: widgetMessage

Parameters

Parameters
Name	In	Description
`key`	query	The widget's public site key, created in the console under Widget. (string, e.g. wk_live_8f3a1c9d2b7e)
`Origin`	header	Sent by the browser: the page making the call. It must be in the widget's allowlist. (string)
`message` required	path	The message id, such as msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012. (string, e.g. msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012)
`session`	query	The anonymous visitor id you generated: 16 to 128 URL-safe characters. Use the same one for follow-ups. (string, e.g. k3n9x2m8q1w7e5r4t6y0)
`wait`	query	Seconds to hold the request open until the answer is ready, up to the server's cap. (integer, e.g. 10)

Responses

200 Success. Poll a widget answer.

200 example

{
  "status": true,
  "message": "widget_answer",
  "data": {
    "object": "widget_answer",
    "answer": "Forgiveness is a decision to release a debt, as God released ours. [1]",
    "blocks": [
      {
        "type": "paragraph",
        "text": "Pastor Ade taught that forgiving is releasing the debt. [1]",
        "source_refs": [
          1
        ]
      }
    ],
    "follow_ups": [
      "What did we teach about reconciliation?"
    ],
    "sources": [
      {
        "number": 1,
        "title": "Seventy times seven",
        "excerpt": "We forgive because we were forgiven."
      }
    ],
    "next_steps": [],
    "conversation_id": "conv_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
    "message_id": "msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
    "status": "complete"
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

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

POST/v1/public/widget/messages/{message}/feedback

Rate a widget answer#

Records whether an answer helped. Feedback goes to the church's review queue; it is never used as training data.

Auth. None. This route is public.

Auth: No key
Operation id: widgetFeedback

Parameters

Parameters
Name	In	Description
`key`	query	The widget's public site key, created in the console under Widget. (string, e.g. wk_live_8f3a1c9d2b7e)
`Origin`	header	Sent by the browser: the page making the call. It must be in the widget's allowlist. (string)
`message` required	path	The message id, such as msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012. (string, e.g. msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012)
`session`	query	The anonymous visitor id you generated: 16 to 128 URL-safe characters. Use the same one for follow-ups. (string, e.g. k3n9x2m8q1w7e5r4t6y0)

Request body

Request body fields
Field	Type	Description
`kind`	`enum: helpful \| not_helpful`	The kind.

Example request body

{
  "kind": "helpful"
}

Responses

200 Success. Rate a widget answer.

200 example

{
  "status": true,
  "message": "feedback recorded",
  "data": {
    "recorded": true
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X POST "$FOLIO_API_URL/v1/public/widget/messages/msg_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012/feedback?key=wk_live_8f3a1c9d2b7e&session=k3n9x2m8q1w7e5r4t6y0" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "helpful"
}'

GET/v1/public/{church}/widget

Read a church's widget settings#

The public settings of a church's widget by church slug. Use GET /v1/public/widget with a site key when you are embedding the widget on another site.

Auth. None. This route is public.

Auth: No key
Operation id: publicWidget

Parameters

Parameters
Name	In	Description
`church` required	path	The church slug, such as grace-chapel. For partner routes, the customer church id (org_) or slug. (string, e.g. grace-chapel)

Responses

200 Success. Read a church's widget settings.

200 example

{
  "status": true,
  "message": "widget",
  "data": {
    "object": "widget",
    "church": "grace-chapel",
    "name": "Grace Chapel"
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/public/grace-chapel/widget"

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