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

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.

post/v1/conversations/handoff

Request

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

Request body

owner'ai' | 'human' | 'external' required
conversation_idstring uuid

One conversation. Pass this or phone.

phonestring

The customer's number (E.164): every conversation the business has with it.

business_idstring uuid

Required when the API key reaches more than one business and only phone is given.

external_reply_timeout_secondsinteger nullable

owner 'external' only: Kai answers when nothing replied in this many seconds.

Response

Owner set (or already set).

conversation_idstring required
owner'ai' | 'human' | 'external' required
owner_set_atstring date-time required
external_reply_timeout_secondsinteger nullable

Changes

No recorded changes to this operation across all 1 revision of this API.