A conversation created with workflowId (or picked up by your project's automation) runs the configured workflow. Steps that wait for the customer surface in three ways: as a BOT message in the conversation, as a workflow.step.presented event, and via the pending-step endpoint.
Read the pending step
curl https://api.gleap.io/v3/s2s/conversations/cnv_…/workflow \
-H "Authorization: Bearer $TOKEN"{ "step": { "workflowId": "wf_…", "stepType": "buttons",
"actionFlowId": "node-3", "actionId": 0,
"action": { "type": "buttons", "options": ["Block card", "Talk to a human"], "…": "…" } } }step is null when nothing is waiting for the customer (internal steps auto-run). action carries the same structure the Gleap widget renders from — text, options, input configuration, attribute definitions for form steps.
Answer the step
curl -X POST https://api.gleap.io/v3/s2s/conversations/cnv_…/workflow/answer \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "selected": "Block card" }'One field per step kind:
Step | Body |
|---|---|
Free-text / input / chat input |
|
Buttons / selection |
|
Conversation rating step |
|
Attachments alongside an answer |
|
Ask for a human (no bot run) |
|
The endpoint returns 202 — the workflow advances asynchronously; follow it via workflow.step.presented / message.created events or by re-reading the pending step.
Run a workflow on an existing conversation
curl -X POST https://api.gleap.io/v3/s2s/conversations/cnv_…/workflow/wf_…/run \
-H "Authorization: Bearer $TOKEN"Replaces any active workflow on the conversation and reopens it for the customer. Only live workflows can run; drafts return workflow_not_found.
List available workflows
curl https://api.gleap.io/v3/s2s/workflows -H "Authorization: Bearer $TOKEN"
# → [ { "id": "wf_…", "name": "Card issues" }, … ]
workflow.completed fires when a workflow ends — reason: "completed" for a normal end (including close steps) or reason: "handed_off" when it passed the conversation to an AI agent or your team.