> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gleap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows & bots

> Render Gleap workflow steps in your own UI and answer them

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

```bash theme={null}
curl https://api.gleap.io/v3/s2s/conversations/cnv_…/workflow \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{ "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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
curl https://api.gleap.io/v3/s2s/workflows -H "Authorization: Bearer $TOKEN"
# → [ { "id": "wf_…", "name": "Card issues" }, … ]
```

<Note>
  `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.
</Note>