Conversational interface via a REST API

Use the conversational REST API when you want to build a chat-style experience (a widget, mobile app, partner portal, or internal tool) on top of an existing thunk workflow. The integration uses the same workflow work item and conversation thread the agent already understands — without email.

This is different from Inbound requests via a REST API, which starts structured workflow work items. The conversational API is for turn-by-turn chat on a workflow that has a conversation input.

Precondition. The thunk workflow must have exactly one conversation-type input property. Without that, the chat UI and conversational REST API are not available for the thunk.

What you can do

Typical integrator flow:

Confirm the workflow has exactly one conversation input property
Create a thunk API key (same keys as the workflow REST API)
Open the OpenAPI docs for this thunk’s conversational endpoints
Start a conversation (first user message) and keep the returned conversation id
Send follow-up messages; poll messages or subscribe to the event stream

Optional: attach files on a turn, upload files for structured file inputs before start, and (when enabled on the conversation property) register structured-data schemas the assistant may return with messages.

1: Confirm the conversation input

In the thunk designer, open the workflow structure and check that there is exactly one input property whose type is Conversation. That property is the chat channel for each workflow work item.

If you need a quick product check: go to Run → Inbound Requests → Chat UI. When the conversation input is present, the Chat UI button is enabled and opens the hosted chat app for the thunk. When it is missing, the Chat UI button stays disabled and an info banner explains that the chat UI is enabled only if the workflow has a conversation input property.

2: Create an API key

API keys are shared with the structured workflow REST API. They are not created on the Chat UI tab.

Go to Run → Inbound Requests → API Channel
Open API Keys
Create a key and copy it immediately — it is shown only once

For screenshots and revoke steps, see Inbound requests via a REST API (Generate an API Key).

Keys use the thk_… prefix. Send them to the public gateway as:

X-API-Key:

Base URL for customer integrations:

https://postern.thunk.ai/api/thunk//convo

3: Open the OpenAPI documentation

Each thunk exposes its own conversational OpenAPI document because optional data fields on start match that thunk’s workflow inputs.

Go to Run → Inbound Requests → Chat UI
Click View OpenAPI Documentation

That opens Swagger UI for this thunk’s conversational endpoints (paths such as /start, /{convoId}/sendMessage, /{convoId}/messages, and /{convoId}/events).

Authorize in Swagger is not your thunk API key. The OpenAPI Authorize control expects a Bearer JWT (a product session token). Use that only for interactive try-it-out. For real integrations through postern.thunk.ai, send X-API-Key: thk_… on the request — do not paste the thunk API key into the Bearer Authorize dialog. (This differs from the workflow REST OpenAPI docs, where Authorize accepts the API key.)

4: Start a conversation

POST /start creates the workflow conversation and sends the first user message. The response includes a convoId used for every later call.

Minimal shape:

{
  "conversation": {
    "type": "message",
    "message": "Hello — I need help with my request."
  }
}

You may also send:

data — other workflow input fields (not the conversation property)
name — label for the new conversation (optional; server assigns a default if omitted)
displayName — label for the human on this turn (optional)
conversation.attachments — optional file attachments on the first message (see below)

Example with curl:

curl -X POST \
  'https://postern.thunk.ai/api/thunk//convo/start' \
  -H 'accept: application/json' \
  -H 'X-API-Key: ' \
  -H 'Content-Type: application/json' \
  -d '{
    "conversation": {
      "type": "message",
      "message": "Hello — I need help with my request."
    }
  }'

A successful response looks like:

{
  "convoId": ""
}

5: Send messages and read replies

Send a follow-up

POST /{convoId}/sendMessage stores the user turn and returns a messageId:

curl -X POST \
  'https://postern.thunk.ai/api/thunk//convo//sendMessage' \
  -H 'accept: application/json' \
  -H 'X-API-Key: ' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Here are more details."
  }'

Optional fields: displayName, attachments.

List messages

GET /{convoId}/messages returns a page of messages in chronological order (oldest first within the page). The first call (no pageToken) returns the most recent page; use pageToken / nextPageToken for older history.

Useful query parameters:

limit — page size
pageToken — pass the previous response’s nextPageToken to continue
since — only messages after this ISO timestamp (exclusive); use the same since on every call that includes pageToken

curl -X GET \
  'https://postern.thunk.ai/api/thunk//convo//messages' \
  -H 'accept: application/json' \
  -H 'X-API-Key: '

You can also fetch one message with GET /{convoId}/message/{messageId}, or check whether the assistant is still working with GET /{convoId}/info (agentWorking).

Live updates (SSE)

GET /{convoId}/events is a long-lived Server-Sent Events stream. After a newMessage event, call GET /messages (optionally with since) to load the text. The stream may also emit agentStatus and periodic heartbeat keepalives (safe to ignore).

Attachments and file inputs

Message attachments. On POST /start (conversation.attachments) or POST /…/sendMessage (attachments), each item is { "name", "data" } where data is a base64 data: URL (the same string browsers produce from FileReader.readAsDataURL). Limits: up to 5 files and 10 MiB total decoded payload per message. When you list messages, attachments include a short-lived contentPointer download URL.

Structured file inputs on start. If the workflow’s non-conversation inputs include file fields, upload first with POST /uploadFiles, then put the returned url values into data on POST /start (do not embed large base64 blobs in the start body for those fields).

Structured data (optional)

If the conversation input property has structured data enabled, you can register JSON schemas (on POST /start or via /{convoId}/structuredDataSchemas) describing payloads the assistant may attach to messages. Listed assistant messages may then include a structuredData array. Use GET /info at the API root to see whether structuredDataEnabled is true for the thunk. Details and schemas are in the thunk’s OpenAPI document.

Choosing conversational vs workflow REST

Goal	Use
Chat turns on a workflow conversation	This article (conversational REST API)
Create / poll structured workflow work items	Inbound requests via a REST API