Send Support / Control Command
The operator control rail for a session. Send a plain message (delivered to the customer while a human has taken over), a control command, or both.
Recognized commands:
takeover— a human operator takes over the session; the agent stops auto-replying andmodebecomessupport.tell— inject operator guidance and fire an agent turn; the agent’sreplyis returned. Provide the text inmessage.whisper— append private operator guidance for the next agent turn; the customer never sees it.end— hand the session back to the agent (modereturns toai).close— close the session permanently.
A request with only message and no command is a plain operator message, valid while the session is in support mode (after takeover).
Optional idempotency applies to every operation: plain operator messages, tell, whisper, takeover, end, and close. Supply an idempotency_key in the body, or an Idempotency-Key header when the body key is absent, null, or blank. A nonblank body key takes precedence and is preserved exactly, including surrounding whitespace. Without a key, requests retain their existing behavior and are not deduplicated.
Keys are scoped account-wide in a support namespace, independently of inbound-message keys. The operation fingerprint includes the session, command, exact message text, and effective operator identity. Message whitespace is significant; omitted and null messages are equivalent, as are omitted and null commands. For JWT authentication, the server uses the authenticated operator email and ignores body operator_email; for gateway requests, it trims surrounding whitespace from operator_email and treats a blank email as absent. Reuse the same key only for the same operation. Authentication and session ownership are checked on every request, including replays.
A completed operation, including a deterministic refusal, returns its saved result and HTTP status without repeating its effects. Completion records the operation’s final server result, including any deferred delivery attempt result; the existing meaning of delivery success is unchanged. Pending retries return 202 with data.state: "in_progress" and data.retry_after_ms: 1000, without executing again. This state can persist if a process dies before recording its final outcome and does not prove the execution is still running. Retries never take over after a timeout; investigate prolonged pending states before resubmitting. A busy result means nothing ran and is retryable with the same key and operation.
A different operation using the same key returns 409 with idempotency_key_reused. An operation whose outcome cannot be established returns 409 with support_operation_outcome_unknown: investigate before resubmission. Such operations are never automatically re-executed or expired to allow execution. Idempotency does not promise exactly-once external delivery or a retention period beyond the stored receipt. Support keys are not automatically echoed in chat delivery callbacks.
Retrying a support operation
Send an optionalidempotency_key (at most 128 characters) with any support operation: a plain operator message, tell, whisper, takeover, end, or close. Use Idempotency-Key as a header fallback when the body key is absent, null, or blank. A nonblank body key takes precedence and is preserved exactly, including surrounding whitespace. Without an effective key, requests follow the existing behavior and are not deduplicated.
null messages are equivalent, as are omitted and null commands. For JWT-authenticated requests, the server uses the authenticated operator’s email and ignores any body operator_email. Gateway requests use operator_email after trimming surrounding whitespace; a blank email is treated as absent. Authentication and session ownership are checked again before any replay.
in_progress can persist if a process dies before recording its final outcome; it does not prove that the execution is still running. Investigate a prolonged pending state before resubmitting.
Completion records the operation’s final server result, including any deferred delivery attempt result. The existing meaning of delivery success stays the same. Unknown outcomes are never automatically re-executed or expired to allow execution. This contract does not promise exactly-once external delivery or a retention period beyond the stored receipt.
Support keys are not automatically echoed in chat delivery callbacks. The callback’s idempotency_key field correlates inbound turns.Authorizations
16-character API token associated with your OSVI account. Find it in your dashboard under Settings → API.
Headers
Optional support-operation key, used only when the body idempotency_key is absent, null, or blank. A nonblank body key wins and is preserved exactly, including surrounding whitespace. Scoped account-wide within the support namespace, separately from inbound-message keys.
128"support-close-4718a326-1"
Path Parameters
The session UUID (from Create Session or Get Active Session).
"4718a326-417b-4dda-90d0-21fd65a11cb8"
Body
Control command to apply. Omit to send a plain operator message (requires the session to be in support mode).
takeover, tell, whisper, end, close "close"
Message text. Required for a plain operator message and for the tell command; optional context for takeover.
"A human agent is joining the conversation."
Optional key for this exact support operation. A nonblank body key is preserved exactly, including surrounding whitespace, and takes precedence over Idempotency-Key; absent, null, or blank falls back to the header. Reuse the same key with the same session, command, exact message, and effective operator identity when retrying. Without an effective key, no deduplication occurs.
128"support-close-4718a326-1"
Optional operator email for gateway requests. Surrounding whitespace is trimmed and a blank email is treated as absent. For JWT-authenticated requests, the server always uses the authenticated user email and ignores this body field. The effective identity is part of the idempotency fingerprint.
"agent@yourco.com"
Response
Operation completed, or an existing command outcome such as busy. A completed keyed operation replays its saved result and status without repeating effects; completion records the final server result, including any deferred delivery attempt result. The response data includes state, session_id, and command; additional fields depend on the command (e.g. reply for tell, active_human for takeover). A busy outcome means nothing ran; retry with the same key and operation. Existing delivery-success semantics are unchanged.