Workflows & bots

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	`{ "text": "12345" }`
Buttons / selection	`{ "selected": "Block card" }`
Conversation rating step	`{ "rating": 5 }`
Attachments alongside an answer	`{ "text": "…", "attachments": [{ "url": "…", "name": "…", "contentType": "…" }] }`
Ask for a human (no bot run)	`{ "botAction": "humanHandoff" }`

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.

Guide

Endpoints

Read the pending step

Answer the step

Run a workflow on an existing conversation

List available workflows

​Read the pending step

​Answer the step

​Run a workflow on an existing conversation

​List available workflows

Read the pending step

Answer the step

Run a workflow on an existing conversation

List available workflows