1
Create the session
POST /v1/sessions creates a session_id and returns versions.state_version: 0. The session is pinned to the active published configuration.2
Request the first question
POST /v1/sessions/{session_id}/next with state_version: 0 returns a decision and ranked candidates.3
Send the next turn
Send the new
state_version and, when available, the decision_id, question_id, actual text asked, and visitor answer.4
Apply external information
/events adds a summary, missed messages, or known CRM data without immediately selecting a question.5
Read or resume
GET /v1/sessions/{session_id} returns the public state. Resume after an interruption with the latest state_version.6
Report the outcome
/feedback records success, failure, or another business outcome. It replaces the limited 0.9 beta “conversion” concept.Two values to keep
decision_id and question_id improve turn correlation but remain optional: NBQ can recover the pending decision from observed messages.
Soft stopping rules
max_turns is a soft limit. Once reached, NBQ may still return the best available question with a warning. Your application decides whether to continue or stop. action: stop means no identifiable question is available.