Fetch built-in calls bootstrap

POST https://z.u1v.ru/api/v1/calls/bootstrap

Fetch the authenticated user's projected built-in-calls bootstrap envelope.

This endpoint keeps the client on existing Zulip API authentication and hides any broker or identity-provider token exchange behind the Zulip server. The response always declares whether direct calling is currently available or unavailable, and every unavailable state degrades to the existing provider_link fallback contract instead of requiring a second login.

The authenticated Zulip user is the only identity input. Clients send device/context metadata only; public SIP identities and other lookup keys are not accepted here.

Usage examples

curl

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/bootstrap \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode platform=android \
    --data-urlencode app_version=30.0.271+271 \
    --data-urlencode 'device_model=android-sdk35 (15)' \
    --data-urlencode device_instance_id=device-1 \
    --data-urlencode locale=en-US \
    --data-urlencode push_enabled=true \
    --data-urlencode 'metadata={"build_channel": "debug"}'

Parameters

platform string required

Example: "android"

Client platform label for the current device, such as android, ios, macos, windows, linux, or web.

app_version string required

Example: "30.0.271+271"

App version string reported by the client.

device_model string optional

Example: "android-sdk35 (15)"

Optional device model or host label for diagnostics.

device_instance_id string optional

Example: "device-1"

Optional client-generated device instance identifier.

locale string optional

Example: "en-US"

Optional BCP 47 locale identifier for the active UI locale.

push_enabled boolean optional

Example: true

Whether the client currently expects push-capable registration flows later in the calls stack.

metadata object optional

Example: {"build_channel": "debug"}

Optional app-owned metadata passed through the bootstrap request. This field is for client context only and cannot influence server-side identity selection.

Response

Return values

availability: string

Whether built-in direct calling is currently available for the authenticated user.
fallback_mode: string

The fallback mode the client should preserve when direct calling is unavailable.
fallback_reason: string | null

Server-authoritative fallback_reason value. * ui_error_code: string | null

Stable user-facing PBX error code. This supplements fallback_reason without changing the legacy value.
identity: object | null

Server-authoritative identity details. * sip_identity: string
```
Canonical SIP identity for the authenticated
user, projected by the server.
```
- person_id: string
  
  Optional stable backend person identifier for the user.
bootstrap: object | null

Server-authoritative bootstrap details. * version: string
```
Server-authoritative `version` value.
```
- provider: string
 
 Server-authoritative provider value. * providerVersion: string
 
 Server-authoritative providerVersion value. * capabilities: object
 
 Server-authoritative capabilities details. * Broker-advertised capability value. * issued_at: string
 
 Server-authoritative issued_at value. * identity: object
 
 Server-authoritative identity details. * sip_identity: string
```
Server-authoritative `sip_identity` value.
```
 - person_id: string
 
 Server-authoritative person_id value. * directory: object
 Server-authoritative directory details. * sip_user: string
```
Server-authoritative `sip_user` value.
```
 - extension: string
 
 Server-authoritative extension value. * did: string
 
 Server-authoritative did value. * display_name: string
 
 Server-authoritative display_name value. * sip_numeric_identity: string
 
 Server-authoritative sip_numeric_identity value. * registration: object
 Server-authoritative registration details. * softphone: object
```
Server-authoritative `softphone` details.
* `domain`: string

 Server-authoritative `domain` value.
* `transport`: string

 Server-authoritative `transport` value.
* `outbound_proxy`: string

 Server-authoritative `outbound_proxy` value.
* `connect_host`: string

 Server-authoritative `connect_host` value.
* `turn`: object
```
 Server-authoritative turn details. * uris: (string)[]
```
Server-authoritative `uris` list.
```
 - username: string
 
 Server-authoritative username value. * credential: string
 
 Server-authoritative credential value. * devices: (object)[]
 Server-authoritative devices list. * device_id: string
```
Server-authoritative `device_id` value.
```
 - device_type: string
 
 Server-authoritative device_type value. * registration_target: string
 
 Server-authoritative registration_target value. * ring_mode: string
 
 Server-authoritative ring_mode value. * ring_order: integer
 
 Server-authoritative ring_order value. * enabled: boolean
 
 Whether the server-authoritative enabled condition is true. * features: object
 Server-authoritative features details. * desk_phone_enabled: boolean
```
Whether the server-authoritative `desk_phone_enabled` condition is true.
```
 - push_enabled: boolean
 
 Whether the server-authoritative push_enabled condition is true. * browser_contour_enabled: boolean
 
 Whether the server-authoritative browser_contour_enabled condition is true. * callActionApi: object
 
 Server-backed call action API capability mirrored inside the broker bootstrap feature block for clients that only inspect the bootstrap payload.
 - supported: boolean
 
 Whether the server-authoritative supported condition is true. * version: integer
 
 Server-authoritative version value. * endpoint: string
 
 Server-authoritative endpoint value. * resultStates: (string)[]
 
 Server-authoritative resultStates list. * browser: object
 Server-authoritative browser details. * enabled: boolean
```
Whether the server-authoritative `enabled` condition is true.
```
 - transport: string
 
 Server-authoritative transport value. * webSocketUrl: string
 
 Server-authoritative webSocketUrl value. * sipDomain: string
 
 Server-authoritative sipDomain value. * inboundMode: string
 
 Server-authoritative inboundMode value. * backgroundParity: boolean
 
 Whether the server-authoritative backgroundParity condition is true. * iceServers: (string)[]
 
 Server-authoritative iceServers list. * allowedOrigins: (string)[]
 
 Server-authoritative allowedOrigins list. * disabledReason: string
 
 Server-authoritative disabledReason value. * metadata: object
 Server-authoritative metadata details. * Server-authoritative mapping value. * callActionApi: object
Server-backed call action API capability. The resultStates values are returned in the action_result field of /calls/{call_id}/actions responses; the top-level Zulip REST result field remains success for successful HTTP/API handling.
- supported: boolean
 
 Whether the server-authoritative supported condition is true. * version: integer
 
 Server-authoritative version value. * endpoint: string
 
 Server-authoritative endpoint value. * resultStates: (string)[]
 
 Server-authoritative resultStates list.

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",
    "bootstrap": {
        "browser": {
            "allowedOrigins": [
                "https://chat.example"
            ],
            "backgroundParity": false,
            "enabled": true,
            "iceServers": [
                "turn:turn.example.com:3478?transport=udp"
            ],
            "inboundMode": "delayed_answer",
            "sipDomain": "sip.example.com",
            "transport": "wss",
            "webSocketUrl": "wss://chat.example/ws"
        },
        "devices": [
            {
                "device_id": "soft-hamlet",
                "device_type": "softphone",
                "enabled": true,
                "registration_target": "flexisip",
                "ring_mode": "parallel",
                "ring_order": 10
            }
        ],
        "directory": {
            "display_name": "Hamlet",
            "extension": "101",
            "sip_user": "hamlet"
        },
        "features": {
            "browser_contour_enabled": false,
            "desk_phone_enabled": true,
            "push_enabled": false
        },
        "identity": {
            "person_id": "person-hamlet",
            "sip_identity": "sip:hamlet@sip.example.com"
        },
        "issued_at": "2026-04-09T10:15:30Z",
        "metadata": {
            "numeric_dial_fallback_scope": "asterisk_policy"
        },
        "registration": {
            "softphone": {
                "domain": "sip.example.com",
                "outbound_proxy": "sip.example.com:5072",
                "transport": "tls"
            }
        },
        "turn": {
            "uris": [
                "turn:turn.example.com:3478?transport=udp"
            ]
        },
        "version": "1.0"
    },
    "callActionApi": {
        "endpoint": "/api/v1/calls/{call_id}/actions",
        "resultStates": [
            "accepted",
            "already_applied",
            "stale_action",
            "answered_elsewhere",
            "cancelled",
            "rejected",
            "unauthorized",
            "unsupported",
            "rate_limited",
            "invalid_call_state"
        ],
        "supported": true,
        "version": 1
    },
    "fallback_mode": "provider_link",
    "identity": {
        "person_id": "person-hamlet",
        "sip_identity": "sip:hamlet@sip.example.com"
    },
    "msg": "",
    "result": "success"
}

API documentation home

Messages

Scheduled messages

Message reminders

Drafts

Navigation views

Channels

Users

Invitations

Server & organizations

Real-time events

Interactive bots