Skip to main content
POST https://api.humalike.com/v1/turn-taking/actions/open_thread
Open a conversation. A thread is the unit of state for turn-taking; open one when the chat starts, then drive it with submit_messages and respond. The response includes a short-lived WebSocket URL you connect to in order to receive the agent’s messages. Call this again with the same thread_id to reconnect: it re-issues a fresh WebSocket URL without creating a new thread. See Threads. This call is not billable.

​
Authorization

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

​
Request body

​
thread_id
string
Optional thread id (a UUID). Omit to open a fresh thread — a new id is minted and returned. Pass an existing id to re-open that thread (the reconnect path). Opening a thread you do not own reads as absent.
​
integrations
object
Optional. Enables behavioural signals for the thread. Set on create; updated on a re-open that supplies it; omitting it leaves any existing configuration unchanged.
Request
{
  "integrations": { "social_signals": {} }
}

​
Response

​
thread
object
The opened thread.
​
channel
string
The thread’s channel address, turn-taking-thread/{thread_id}. Events on the WebSocket carry this as their channel.
​
realtime
object
The grant for streaming the agent’s messages.
200 OK
{
  "thread": {
    "id": "b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
    "user_id": "usr_a1b2c3",
    "created_at": "2026-06-16T12:00:00Z",
    "updated_at": "2026-06-16T12:00:00Z"
  },
  "channel": "turn-taking-thread/b9c1e4f0-2a77-4f6e-9d2a-1f0c8e5b3a44",
  "realtime": {
    "connect_url": "wss://api.humalike.com/v1/ws?c=9f8e7d6c5b4a3210...",
    "expires_at": "2026-06-16T12:00:30Z"
  }
}

​
Errors

StatusCodeWhen
401UNAUTHORIZEDThe bearer token is missing, invalid, or expired.
422VALIDATION_ERRORthread_id is not a UUID, or integrations is malformed.
See Errors for the envelope shape.

​
Example

curl https://api.humalike.com/v1/turn-taking/actions/open_thread \
  -H "Authorization: Bearer $HUMALIKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"integrations": {"social_signals": {}}}'

​
Next