Plan built-in conference start or resume with room state
POST https://z.u1v.ru/api/v1/calls/conferences/plan
Plan an authenticated built-in conference resume for the active Zulip
account.
This endpoint extends the same Zulip-authenticated call-control
boundary as POST /calls/bootstrap,
POST /calls/devices/register, and
POST /calls/recovery. Clients submit only
app-owned room context for an already authenticated conference
target; the server remains authoritative for caller identity,
conversation eligibility, room allocation, and broker-facing
planning details.
The response always declares whether conference resume is available
or must fail closed to the existing provider_link fallback
contract.
Usage examples
The -u line implements HTTP Basic authentication.
See the Authorization header documentation for how
to get those credentials for Zulip users and bots.
curl -sSX POST https://z.u1v.ru/api/v1/calls/conferences/plan \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode owner_user_id=42 \
--data-urlencode room_id=room-1 \
--data-urlencode media_type=audio \
--data-urlencode idempotency_key=conf-plan-1 \
--data-urlencode 'display_name=General > Launch plan' \
--data-urlencode 'metadata={"conversation_kind": "topic", "conversation_stream_id": "9", "conversation_topic": "Launch plan"}'
Parameters
owner_user_id string required
Example: "42"
Authenticated Zulip user ID for the active caller.
room_id string | null optional
Example: "room-1"
Conference room identifier to resume. Omit this field to
let the server find or provision the room from
conversation metadata.
idempotency_key string | null optional
Example: "conf-plan-1"
Optional client-generated key for deduplicating repeated
start or resume taps.
display_name string | null optional
Example: "General > Launch plan"
Optional client display-name hint. The server may
normalize or replace this value.
Response
Return values
-
availability: string
Server-authoritative availability value.
* fallback_mode: string
Server-authoritative fallback_mode value.
* fallback_reason: string | null
Server-authoritative fallback_reason value.
* ui_error_code: string | null
Server-authoritative ui_error_code value.
* identity: object | null
Server-authoritative identity details.
* sip_identity: string
Server-authoritative `sip_identity` value.
Server-authoritative planned_conference details.
* appCallId: string
Server-authoritative `appCallId` value.
-
provider: string
Server-authoritative provider value.
* providerVersion: string
Server-authoritative providerVersion value.
* routeClass: string
Server-authoritative routeClass value.
* routeMode: string
Server-authoritative routeMode value.
* routeType: string
Server-authoritative routeType value.
* mediaAnchor: string
Server-authoritative mediaAnchor value.
* identitySource: string
Server-authoritative identitySource value.
* capabilities: object
Server-authoritative capabilities details.
* Broker-advertised conference capability value.
* callCapabilities: object
Server-declared call media capability contract. Clients must use this
as the authoritative source for whether audio, video, and conference
flows can be attempted or need a user-facing fallback.
-
version: integer
Version of the call-capability contract.
* capabilitySourceVersion: string
Versioned server component that produced the capability decision.
* requestedMediaType: string
Media type requested by the caller.
* effectiveMediaType: string
Media type selected by the server after capability checks.
* routeSupportsAudio: boolean
Whether the selected route supports audio.
* routeSupportsVideo: boolean
Whether the selected route supports video.
* targetSupportsAudio: boolean
Whether the destination supports audio calls.
* targetSupportsVideo: boolean
Whether the destination supports video calls.
* localDeviceSupportsAudio: boolean
Whether the caller device supports audio calls.
* localDeviceSupportsVideo: boolean
Whether the caller device supports video calls.
* conferenceSupportsAudio: boolean
Whether the selected conference route supports audio.
* conferenceSupportsVideo: boolean
Whether the selected conference route supports video.
* unavailableReason: string | null
Machine-readable reason the requested media is unavailable.
* fallbackReason: string | null
Machine-readable reason a fallback media mode was selected.
* metadata: object
Bounded server-authoritative capability metadata.
* Call-capability metadata value.
* roomId: string
Server-authoritative roomId value.
* roomUri: string
Server-authoritative roomUri value.
* mediaType: string
Server-authoritative mediaType value.
* displayName: string
Server-authoritative displayName value.
* inviteHeaders: (string)[]
Server-authoritative inviteHeaders list.
* subscription: object | null
Server-authoritative subscription details.
* roomId: string
Conference room identifier for the subscription.
-
webSocketUrl: string | null
WSS endpoint for conference presence updates.
* webSocketHeaders: object
Headers required by the conference WSS subscription.
* Conference WSS header value.
* subscribeFrame: string | null
Optional initial conference WSS subscription frame.
* heartbeatSeconds: integer | null
Recommended conference WSS heartbeat interval.
* leaseExpiresAt: string | null
Expiration time of the conference subscription lease.
* renewToken: string | null
Opaque token used to renew the conference subscription.
* metadata: object
Bounded conference subscription metadata.
* Conference subscription metadata value.
* participants: (object)[]
Server-authoritative participants list.
* userId: string
Server-authoritative `userId` value.
-
displayName: string
Server-authoritative displayName value.
* avatarUrl: string | null
Server-authoritative avatarUrl value.
* metadata: object
Server-authoritative metadata details.
* Server-authoritative mapping value.
* roomContract: object | null
Server-authoritative roomContract details.
* shareUrl: string | null
Server-authoritative `shareUrl` value.
-
scheduledStartAt: string | null
Server-authoritative scheduledStartAt value.
* recordingState: string
Server-authoritative recordingState value.
* audioTopology: string
Server-authoritative audioTopology value.
* participantGainSemantic: string
Server-authoritative participantGainSemantic value.
* joinMuted: boolean | null
Whether the server-authoritative joinMuted condition is true.
* messagesEnabled: boolean | null
Whether the server-authoritative messagesEnabled condition is true.
* canInvite: boolean
Whether the server-authoritative canInvite condition is true.
* canShare: boolean
Whether the server-authoritative canShare condition is true.
* canSchedule: boolean
Whether the server-authoritative canSchedule condition is true.
* canRecord: boolean
Whether the server-authoritative canRecord condition is true.
* canManage: boolean
Whether the server-authoritative canManage condition is true.
* canChangeJoinMuted: boolean
Whether the server-authoritative canChangeJoinMuted condition is true.
* canChangeMessagesEnabled: boolean
Whether the server-authoritative canChangeMessagesEnabled condition is true.
* adminUserIds: (integer)[]
Server-authoritative adminUserIds list.
* uiHints: object | null
Server-authoritative uiHints details.
* Broker-provided conference UI hint value.
* metadata: object
Server-authoritative metadata details.
* Server-authoritative mapping value.
Example response(s)
Changes: As of Zulip 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
ignored_parameters_unsupported array.
A typical successful JSON response may look like:
{
"availability": "available",
"fallback_mode": "provider_link",
"identity": {
"person_id": "person-hamlet",
"sip_identity": "sip:hamlet@sip.example.com"
},
"msg": "",
"planned_conference": {
"appCallId": "conference-app-call-1",
"displayName": "General > Launch plan",
"inviteHeaders": [
"X-App-Call-Id: conference-app-call-1"
],
"mediaType": "audio",
"metadata": {
"conversation_kind": "topic",
"conversation_stream_id": "9",
"conversation_topic": "Launch plan"
},
"participants": [
{
"avatarUrl": null,
"displayName": "King Hamlet",
"metadata": {
"has_video": "true",
"is_active_speaker": "false",
"is_muted": "false",
"is_screen_sharing": "false",
"is_self": "true",
"is_speaking": "false"
},
"userId": "10"
},
{
"avatarUrl": null,
"displayName": "Othello, the Moor of Venice",
"metadata": {
"has_video": "true",
"is_active_speaker": "true",
"is_muted": "false",
"is_screen_sharing": "true",
"is_self": "false",
"is_speaking": "true"
},
"userId": "12"
}
],
"roomContract": {
"adminUserIds": [
10,
12
],
"audioTopology": "confbridge_mixed",
"canChangeJoinMuted": true,
"canChangeMessagesEnabled": true,
"canInvite": true,
"canManage": true,
"canRecord": false,
"canSchedule": true,
"canShare": true,
"joinMuted": true,
"messagesEnabled": false,
"participantGainSemantic": "participant_global_speaker_gain",
"recordingState": "available",
"scheduledStartAt": "2026-04-10T08:30:00Z",
"shareUrl": "https://chat.example/calls/room-1"
},
"roomId": "room-1",
"roomUri": "sip:room-1@pbx.example.com"
},
"result": "success"
}