Chat with a workflow

A workflow can answer a chat the way an agent does. Each message starts a run, and the text of its Reply block is the answer, streamed back like an agent's reply. Use it when an answer needs several steps: check the message, look something up, then answer.

Where a workflow can chat

Steps

1. 1

   Add a Reply block

   Put a Reply block where the answer is ready, usually after an Agent block, and set its Reply text to {{last.output}}. Give every path that should answer its own Reply. The Website chatbot template is set up this way.

2. 2

   Read the message

   A chat run's input has message (what the person wrote), history (the conversation so far), conversation_id and channel (playground, widget, link or api), plus agent_id when an agent answers with the workflow. Use {{input.message}} in the first block.

3. 3

   Try it in the Playground

   Pick the workflow in the Playground and send a message. If it has no Reply block, the Playground asks you to add one, and Open in designer takes you there.

4. 4

   Publish

   Every channel except the Playground uses the published version.

5. 5

   Choose where it chats

   Copy the widget's embed code, share the chat link, call POST /v1/chat, or set an agent to answer with it.

curl -N https://api.sentientone.ai/v1/chat \  -H "Content-Type: application/json" \  -H "X-Api-Key: $SENTIENTONE_API_KEY" \  -d '{"workflow_id": "YOUR_WORKFLOW_ID", "message": "Where is my order A-1042?"}'

<script  src="https://app.sentientone.ai/widget.js"  data-widget-key="pk-so-…"  data-workflow-id="YOUR_WORKFLOW_ID"  defer></script>

POST /v1/chat answers with the same server-sent events as an agent: meta, then delta events with the answer, then done with the workflow_run_id. Send the conversation_id from meta to continue the conversation. From a browser, use the workflow's publishable widget key in X-Widget-Key instead of your secret key; it works only from the websites you allow.

Answer with a workflow

An agent can hand its chats to one of your published workflows. On the agent's Settings tab (or its Deploy tab), under Answers, choose the workflow in Answer with a workflow. Every message to the agent (its widget, the API and the Playground) then goes through the workflow, which answers with its Reply block. Widgets and code that already call the agent don't need to change.

If the workflow fails before it replies, ends without reaching a Reply block, isn't published or was deleted, the agent answers itself, and its trace says workflow_fallback. The person chatting always gets an answer.

Credits

Each message costs 1 credit from your balance, whichever channel it comes from. That covers the run: its Agent and AI blocks don't charge again. A run that ends without an answer is refunded. At zero credits the API answers 402 OUT_OF_CREDITS, and the widget and chat links tell visitors the assistant is unavailable right now.

If something goes wrong