speakers

Run Speaker Sip Test

Place a REAL AI call on this speaker to prove the SIP path works.

SITE-ADMIN ONLY, like the rest of this router and for the same reason: it hands out real-world sound at a customer site. During an install it is often an ESCALATE_VOICE_DOWN operator on the phone with the technician — widening it to them was considered and declined (round-0 review, OQ-5), and that refusal is unchanged: the 2026-09-15 widening admitted the monitoring manager, who runs the floor, not the operator on the call.

IT ANNOUNCES NOTHING AND CANNOT. The call row has no reservation, so the only writer of announced_at has nothing to write on; the provider webhook drops the call as not-a-talk-down; and the test agent is published with no custom functions, so it cannot escalate, dismiss, or record an outcome.

503 until RETELL_SIPTEST_AGENT_ID is set (or when it equals the talk-down agent's id). 409 for a speaker tested inside the last minute, for a site that has used its daily allowance, and for a horn somebody else is already talking on. A DEVICE REFUSAL IS A 200, NOT A 502: the device's own error body ("Invalid SIPAccountId 'Gate horn'") is the answer the owner pressed the button for, so it comes back in device_error with passed: false rather than as an error carrying nothing. A 502 here means the device could not be reached at all.

A 200 MEANS THE HORN IS ON A CALL RIGHT NOW, not that the test is over: the route returns at connect so the owner hears it, and the watchdog hangs it up at the cap. Poll the GET below to watch it end.

post/speakers/{speaker_id}/sip-test

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/speakers/{speaker_id}/sip-test
  • Auth
    HTTP bearer

Path parameters

speaker_idstring required

Response

Successful Response

call_idstring uuid required

The call record for this test.

speaker_idstring uuid nullable

The speaker that was tested.

speaker_labelstring required

The speaker's display name.

statusstring required

placing | connected | ended | failed.

passedboolean required

True only when the device and the voice platform both reported this call live.

summarystring required

One sentence a person can act on.

device_call_idstring nullable

The device's own CallId, once it answered the dial.

provider_call_idstring nullable

The voice platform's call id.

provider_statusstring nullable

The platform's own call status, verbatim.

provider_disconnection_reasonstring nullable

Why the platform says the call ended.

duration_msinteger nullable

The platform's measured call duration.

provider_unreadableboolean

True when the voice platform could not be read at all. NOT the same as passed: false with a status: it means we do not know what the platform saw, which is a different thing to do about it than a call the platform never received.

signals_agreed_atstring date-time nullable

When the device and the platform first agreed the call was live. A HIGH-WATER MARK: once set it stays, because a call that has since ended still passed.

auth_modestring nullable

Which auth mode the device accepted.

playback_notestring nullable

Set when the device could not confirm it had finished a clip and the owner went ahead anyway.

sip_account_idstring nullable

Which SIP account the call was placed from; null means the device default.

started_atstring date-time nullable

When the call was placed.

ended_atstring date-time nullable

When the call ended, if it has.

end_reasonstring nullable

Why the call ended.

max_secondsinteger required

The test call's duration cap — the watchdog hangs it up at this.

result_versioninteger

Shape version of the stored result this was rendered from. 0 means a row written before the stamp existed.

Example response

{
  "speaker_label": "North horn — gate",
  "status": "connected",
  "device_call_id": "1",
  "device_states": [
    {
      "state": "Calling"
    }
  ],
  "provider_call_id": "call_85b9",
  "provider_status": "ongoing",
  "provider_disconnection_reason": "agent_hangup",
  "duration_ms": 13400,
  "auth_mode": "digest",
  "device_error": {
    "http_status": 400,
    "body": "{\"error\":{\"code\":400,\"message\":\"Invalid SIPAccountId 'Gate horn'\"}}"
  },
  "sip_account_id": "sip_account_1",
  "end_reason": "max_duration",
  "max_seconds": 30,
  "result_version": 1
}

Changes

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