Skip to content

Create Assessment

POST
/webchat/assessments

Create an assessment.

definition is the flow itself and is validated HERE, against the app’s own model - so a graph whose start_step_id names a step it does not define is a 422 rather than a dead end a visitor walks into.

Note chat_bot_id is a QUERY parameter on this one and a BODY field on every other webchat create. That is the app’s own inconsistency, mirrored rather than tidied: moving it into the body would send the handler a parameter it does not take.

Authorizations

Parameters

Query Parameters

chat_bot_id
required

Owning chat bot id (UUID).

string

Owning chat bot id (UUID).

Header Parameters

Idempotency-Key
Any of:
string

Retry-safety key. Replaying it returns the FIRST result.

X-Target-Org-Id
Any of:
string

Request Body required

A guided question flow the widget can run with a visitor.

definition is the flow itself - a start step, the steps, and the results they lead to. It is the app’s own AssessmentDefinition, so a graph that names a step it does not define is a 422 here rather than a dead end the visitor walks into.

object
definition
required

The flow: {start_step_id, steps[], results[]}.

object
results
Array<object>

A terminal result node — shown when the visitor’s path leads here.

object
body
string
"" <= 2000 characters
booking_enabled
boolean
handoff_enabled
boolean
id
required
string
>= 1 characters <= 64 characters
links
Array<object>
object
label
required
string
>= 1 characters <= 200 characters
url
required
string
>= 1 characters <= 2048 characters
title
required
string
>= 1 characters <= 200 characters
start_step_id
required
string
>= 1 characters <= 64 characters
steps
Array<object>

One question-and-answers step in the assessment flow.

object
allow_free_text
boolean
answers
Array<object>

A single selectable answer within an assessment step.

object
id
required
string
>= 1 characters <= 64 characters
next_step_id
Any of:
string
<= 64 characters
result_id
Any of:
string
<= 64 characters
text
required
string
>= 1 characters <= 500 characters
id
required
string
>= 1 characters <= 64 characters
question
required
string
>= 1 characters <= 2000 characters
description
Any of:
string
<= 2000 characters
name
required
string
>= 1 characters <= 200 characters
surface
Any of:
string
Allowed values: external internal

Responses

201

Successful Response

object
data
required

An open envelope for one webchat object.

Open because the widget’s config grows a field per product decision and a pinned schema would DROP it. Same choice the desk surface made.

object
key
additional properties
any
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string