Text Chat API

Test voice agents as a text interface without a phone call

How it works

Create a session (equivalent to initiating a call)
Append messages as the user (the agent responds in the same call)
Rewind to a previous point and explore a different conversational path
Retrieve the session to see the full transcript

Endpoints

Method	Path	Description
POST	`/workflow/{id}/text-chat/sessions`	Create a new text chat session
GET	`/workflow/{id}/text-chat/sessions/{run_id}`	Get a session and its message history
POST	`/workflow/{id}/text-chat/sessions/{run_id}/messages`	Append a user message and get the agent's response
POST	`/workflow/{id}/text-chat/sessions/{run_id}/rewind`	Rewind to a previous message and branch from there

Create a Session

POST

/workflow/{id}/text-chat/sessions

Request body — CreateTextChatSessionRequest:

json

{
  "initial_context": {
    "customer_name": "Jane",
    "account_id": "ACC-1234"
  }
}

Response: a run object with workflow_run_id and the agent's opening message.

Get a Session

GET

/workflow/{id}/text-chat/sessions/{run_id}

Returns the full message history as an array of { role, content, timestamp } objects. Roles are "user" and "assistant".

Append a Message

POST

/workflow/{id}/text-chat/sessions/{run_id}/messages

Request body — AppendTextChatMessageRequest:

json

{
  "content": "I'd like to cancel my subscription."
}

Response: the agent's reply as:

Response

json

{
  "role": "assistant",
  "content": "...",
  "timestamp": "..."
}

Rewind a Session

POST

/workflow/{id}/text-chat/sessions/{run_id}/rewind

Request body — RewindTextChatSessionRequest:

json

{
  "message_index": 4
}

Truncates the session history to the specified message index and allows replaying from that point. Useful for testing different conversation branches from the same root.

Use Cases

Agent QA before publishing — test edge cases without placing real calls
Regression testing — automate test scripts that append messages and assert expected responses
Demo environments — show agent capabilities in a browser without needing telephony
Non-voice channels — embed the same agent logic in a web chat widget

Was this page helpful?

PreviousTrigger Calls NextCampaigns