VEverdun
external-talkdowns

Update External Talkdown

Report what the extension observed: connected, ended or failed.

requested -> connected -> ended, requested -> failed, connected -> failed. Anything else is a 409, EXCEPT an exact repeat of the row's current terminal status with the same fail_reason, which is an idempotent 200 no-op so a lost response does not make the extension's retry look like an error. Timestamps and duration_ms are server-side.

patch/events/{event_id}/external-talkdowns/{talkdown_id}

Request

  • Base URL
    https://api.verdun.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://api.verdun.ai/events/{event_id}/external-talkdowns/{talkdown_id}
  • Auth
    HTTP bearer

Path parameters

event_idstring required
talkdown_idstring required

Request body

status'connected' | 'ended' | 'failed' required

The state the extension observed. connected = the vendor console reported the call up (the horn is live). ended and failed are terminal.

fail_reason'timeout' | 'not_logged_in' | 'phone_not_found' | 'busy' | 'extension_error'
detailstring nullable

Short attempt trail — extension version, last observed console state. At most 200 characters, letters/digits/spaces and . , ; : _ ( ) / - only, no unbroken run over 32 characters, and never a URL. Anything token-shaped is refused rather than stored.

Example request

{
  "status": "connected",
  "detail": "extension 0.3.1; last observed state: connecting"
}

Response

Successful Response

idstring uuid required

The talk-down record id.

event_metadata_idstring uuid required

The alarm this was about.

camera_idstring uuid required

The camera whose vendor console was driven.

parent_idstring uuid required

The client, denormalised so a tenant-scoped read needs no join.

site_idstring uuid required

The site, denormalised for the same reason.

operator_idstring uuid nullable

Who talked. Null once that account has been deleted — the record outlives it.

provider'verkada_command' required
mode'mic' | 'clip' required
status'requested' | 'connected' | 'ended' | 'failed' required
fail_reason'timeout' | 'not_logged_in' | 'phone_not_found' | 'busy' | 'extension_error'
client_refstring required

The extension's per-attempt id; the idempotency key this row was created under.

requested_atstring date-time required

When the operator pressed the button, on the SERVER's clock.

connected_atstring date-time nullable

When the vendor console reported the call up. Null if it never did.

ended_atstring date-time nullable

When the attempt reached a terminal state.

duration_msinteger nullable

connected_at to ended_at in milliseconds. Null when the call never connected — which is the honest answer, not zero.

detailstring nullable

Free-text attempt trail. Never a URL or a token.

created_atstring date-time nullable

Row creation timestamp.

updated_atstring date-time nullable

Row update timestamp.

Example response

{
  "client_ref": "a1b2c3d4e5f6"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.