Skip to main content
POST https://api.humalike.com/v1/turn-taking/actions/submit_messages
Hand turn-taking the inbound messages as they arrive and get back whether the agent should speak now or stay silent. Call it on every inbound message, or on a small batch — turn-taking weighs the timing and content to decide if this is the agent’s moment to reply. When the decision is speak, draft your agent’s reply and submit it with respond, passing back the turn_epoch from this response. This call is billable. See Billing.

​
Authorization

​
Authorization
string
required
Your bearer token: Bearer <token>. See Authentication.

​
Request body

​
thread_id
string
required
The thread to submit to, from open_thread.
​
messages
InboundMessage[]
required
The inbound messages, in order. 1–20 per call.
​
system_prompt
string
Optional system-prompt text — the agent’s identity, character, and rules (such as when to join in versus stay quiet) — applied to this decision. Up to 8000 characters. Sent per request, so each agent in a group chat can send its own.
Request
{
  "thread_id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
  "messages": [
    {"sender": "casey", "content": "anyone around to look at the export bug?"}
  ],
  "system_prompt": "You are a concise, friendly support agent. Speak up when you can help; stay silent during side chatter."
}

​
Response

​
decision
string
speak if the agent should reply now, or stay_silent if it should wait. On speak, call respond; on stay_silent, do nothing and wait for the next inbound message.
​
turn_epoch
integer
The thread’s current turn. Pass it back in the matching respond so a reply drafted against stale context is dropped. See Interruptions and turn_epoch.
​
tags
string[]
Behavioural tags for this batch (for example ["fast", "comeback"]). Empty unless the thread enables behavioural signals.
200 OK
{
  "decision": "speak",
  "turn_epoch": 7,
  "tags": ["comeback"]
}

​
Errors

StatusCodeWhen
401UNAUTHORIZEDThe bearer token is missing, invalid, or expired.
402PAYMENT_REQUIREDYour account can’t cover this request. You are not charged.
403forbiddenThe token is valid but not allowed here.
422VALIDATION_ERRORThe body is malformed, messages is empty or over 20, or a field is out of range.
502UPSTREAM_ERRORA dependency the request relies on was unavailable. Retry with backoff.
See Errors for the envelope shape.

​
Example

curl https://api.humalike.com/v1/turn-taking/actions/submit_messages \
  -H "Authorization: Bearer $HUMALIKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
    "messages": [
      {"sender": "casey", "content": "anyone around to look at the export bug?"}
    ]
  }'

​
Next

  • Respond — submit the agent’s reply when the decision is speak.