Respond

POST https://api.humalike.com/v1/turn-taking/actions/respond

Submit your agent’s drafted reply after a speak decision. Turn-taking rewrites it into 1–5 short chat messages, scheduled a beat apart, and delivers them on the thread’s WebSocket as turn_taking.message events (with a turn_taking.typing indicator around them). The response tells you what was scheduled; the messages themselves arrive over the socket. See Receiving messages from the agent. Before it is paced, your draft is refined through a Theory of Mind pass — predicting how it will land for the people in the thread, and rewording it to head off the predicted damage. This happens inside respond, so you do not need to call foresee yourself first; doing so runs the refinement twice. Pass a system_prompt so the rewrite keeps your agent’s voice. Pass the turn_epoch from the submit_messages that returned speak. If a newer batch has arrived since, the draft is stale: nothing is scheduled, nothing is billed, and the response is superseded: true. This call is billable, unless it is superseded. Because the draft is refined through Theory of Mind, a respond meters two billable units: the reply and the refinement. The refinement appears as theoryofmind on your usage summary. See Billing. This call is idempotent: retrying the same reply does not schedule it twice.

Authorization

string

required

Your bearer token: Bearer <token>. See Authentication.

Request body

string

required

The thread to reply in.

string

required

The agent’s drafted reply, 1–4000 characters. This is the text that gets paced into chat messages.

integer

required

The turn_epoch from the deciding submit_messages. Required: a reply whose epoch is behind the thread’s current turn is dropped as stale (an interruption).

string

Optional system-prompt text — the agent’s identity, character, and style — applied while rewriting the reply so it stays in the agent’s voice. Up to 100,000 characters. Sent per request.

string

Optional display name for the agent in this reply, 1–255 characters. Sent per request, so each agent in a group chat can send its own.

PacingOverrides

Optional per-reply overrides for how the reply is paced out. Each field you omit keeps its default; the overrides apply to this reply only and never change the thread’s or account’s defaults.

Show PacingOverrides

number

How long the agent “reads” before its first message, in milliseconds. 0–30000. Defaults to no reading pause.

number

Typing speed in words per minute, used to derive each message’s typing delay. Greater than 0, up to 2000.

number

Ceiling on any single message’s typing delay, in milliseconds. Greater than 0, up to 60000. Every message also has a default minimum typing delay; if you set this ceiling below that minimum, the minimum drops to match, so this value is always respected as the hard ceiling.

object

Optional opaque JSON object carried with this reply. It is never read or acted on — it is echoed back verbatim on every turn_taking.message event the reply produces, so you can correlate delivered messages with your own state (for example a reply_to_message_id for bubble placement).Serialized, it must be at most 4096 bytes.

Request

{
  "thread_id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
  "content": "Yes — I can take a look. Can you share the export you tried and roughly when it failed?",
  "turn_epoch": 7,
  "pacing": {"typing_wpm": 320, "max_typing_ms": 4000},
  "metadata": {"reply_to_message_id": "m_8814"}
}

Response

ScheduledMessage[]

The chat messages the reply was paced into, in delivery order. Each is also pushed over the WebSocket as a turn_taking.message event at its deliver_at. Empty when superseded is true.

Show ScheduledMessage

string

The scheduled message’s id.

string

The thread this message belongs to.

string

The message text for this piece of the reply.

integer

0-based order of this message within the reply.

string

When the message is delivered on the WebSocket (ISO 8601).

string

The message’s delivery status.

boolean

true when the draft was stale because a newer batch arrived first. Nothing was scheduled and nothing was billed — draft again against the latest decision. false on a normal reply.

200 OK

{
  "scheduled": [
    {
      "id": "f2a0c6d1-8e3b-4a90-9c7e-2b1d4f6a0c11",
      "thread_id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
      "content": "Yes — I can take a look.",
      "position": 0,
      "deliver_at": "2026-06-16T12:00:01Z",
      "status": "scheduled"
    },
    {
      "id": "a7b3e9c2-1d44-4f08-bb6a-90c2e7d5f3a2",
      "thread_id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
      "content": "Can you share the export you tried and roughly when it failed?",
      "position": 1,
      "deliver_at": "2026-06-16T12:00:02Z",
      "status": "scheduled"
    }
  ],
  "superseded": false
}

A superseded reply schedules nothing:

200 OK (superseded)

{
  "scheduled": [],
  "superseded": true
}

Errors

Status	Code	When
`401`	`UNAUTHORIZED`	The bearer token is missing, invalid, or expired.
`402`	`PAYMENT_REQUIRED`	Your account can’t cover this request. You are not charged.
`403`	`forbidden`	The token is valid but not allowed here.
`422`	`VALIDATION_ERROR`	The body is malformed, `content` is empty or too long, `turn_epoch` is missing, a `pacing` field is out of range, or `metadata` exceeds 4096 bytes.
`502`	`UPSTREAM_ERROR`	A dependency the request relies on was unavailable. Retry with backoff.

A stale draft is not an error — it returns 200 with superseded: true. See Errors for the envelope shape.

Example

curl https://api.humalike.com/v1/turn-taking/actions/respond \
  -H "Authorization: Bearer $HUMALIKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
    "content": "Yes — I can take a look. Can you share the export you tried and roughly when it failed?",
    "turn_epoch": 7
  }'

import os
import httpx

resp = httpx.post(
    "https://api.humalike.com/v1/turn-taking/actions/respond",
    headers={"Authorization": f"Bearer {os.environ['HUMALIKE_TOKEN']}"},
    json={
        "thread_id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
        "content": "Yes — I can take a look. Can you share the export you tried and roughly when it failed?",
        "turn_epoch": 7,
    },
)
resp.raise_for_status()
result = resp.json()
if result["superseded"]:
    print("interrupted; draft against the latest decision")
else:
    print(f"{len(result['scheduled'])} messages scheduled; watch the WebSocket")

const res = await fetch("https://api.humalike.com/v1/turn-taking/actions/respond", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HUMALIKE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    thread_id: "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
    content: "Yes — I can take a look. Can you share the export you tried and roughly when it failed?",
    turn_epoch: 7,
  }),
});
if (!res.ok) throw new Error(`respond failed: ${res.status}`);
const { scheduled, superseded } = await res.json();
// The messages arrive over the WebSocket; superseded === true means draft again.

Record an event — report typing and edits for behavioural signals.

Get started

Turn-taking API

Persona API

Social Learning API

Social Observability API

Social Memory API

Theory of Mind API

Account

Authorization

Request body

Response

Errors

Example

Next

​Authorization

​Request body

​Response

​Errors

​Example

​Next

Authorization

Request body

Response

Errors

Example

Next