---
title: "Set who answers a customer's text conversation: Kai (ai), the owner (human) or your own system (external) (sms:write)."
method: POST
path: "/v1/conversations/handoff"
---

# Set who answers a customer's text conversation: Kai (ai), the owner (human) or your own system (external) (sms:write).

`POST /v1/conversations/handoff`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/conversations/handoff`
- Auth: HTTP bearer

owner 'ai' is the default: Kai replies. 'human' keeps Kai quiet so the owner answers. 'external' keeps Kai quiet so your system answers: it receives the sms.received webhook (which carries conversation_owner) and replies with POST /v1/messages. With external_reply_timeout_seconds (external only, 60 to 86400), Kai answers a message nothing replied to in that time, within about a minute of the deadline, unless a newer message arrived or the owner changed. Inbound messages are always stored and sms.received always fires. Pass conversation_id for one conversation, or phone for every conversation the business has with that customer's number (one per business line). Each owner change fires conversation.handoff. Re-sending the same owner is a no-op that reports changed: false. Responds 503 feature_unavailable until the feature is rolled out.

## Request body

- object
  - `owner` 'ai' | 'human' | 'external', required
  - `conversation_id` string, uuid: One conversation. Pass this or phone.
  - `phone` string: The customer's number (E.164): every conversation the business has with it.
  - `business_id` string, uuid: Required when the API key reaches more than one business and only phone is given.
  - `external_reply_timeout_seconds` integer, nullable: owner 'external' only: Kai answers when nothing replied in this many seconds.

## Response `200`

Owner set (or already set).

- object
  - `conversation_id` string, required
  - `owner` 'ai' | 'human' | 'external', required
  - `owner_set_at` string, date-time, required
  - `external_reply_timeout_seconds` integer, nullable
  - `conversations` object[], required
    - `conversation_id` string
    - `lead_id` string, nullable
    - `lead_phone` string, nullable
    - `business_phone` string, nullable
    - `previous_owner` 'ai' | 'human' | 'external'
    - `owner` 'ai' | 'human' | 'external'
    - `changed` boolean

## Other responses

- `400`: Missing or invalid owner, neither or both of conversation_id and phone, a bad timeout, or business_id_required.
- `403`: Missing sms:write scope, or business_id outside the key.
- `404`: conversation_not_found.
- `503`: feature_unavailable: handoff is not rolled out yet.

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)