Claim incoming built-in call invite
POST https://z.u1v.ru/api/v1/calls/incoming/claim
Claim and normalize an incoming built-in call invite for the
authenticated Zulip account.
This endpoint keeps incoming caller identity behind the same
Zulip-authenticated call-control boundary as
POST /calls/bootstrap,
POST /calls/devices/register, and
POST /calls/plan. Clients submit the
observed incoming invite context, and the server either returns a
normalized claim envelope or fails closed with accepted: false.
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/incoming/claim \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode system_call_id=system-call-1 \
--data-urlencode 'raw_headers={"X-App-Call-Id": "app-call-1", "X-App-Planner-Token": "planner-app-call-1"}' \
--data-urlencode remote_identity_uri=sip:ophelia@sip.example.com \
--data-urlencode device_instance_id=device-1
Parameters
system_call_id string required
Example: "system-call-1"
App/runtime system call identifier for the incoming invite.
remote_identity_uri string | null optional
Example: "sip:ophelia@sip.example.com"
Optional remote SIP identity observed for the caller.
device_instance_id string | null optional
Example: "device-1"
Optional active device instance identifier for the current
client.
Response
Return values
-
accepted: boolean
Whether the incoming invite was successfully claimed
and normalized for app-owned UI.
-
reason: string | null
Machine-readable rejection reason when accepted is
false.
-
ui_error_code: string | null
Stable user-facing PBX error code. This supplements
reason without changing the legacy value.
-
appCallId: string | null
Canonical application call identifier.
* routeClass: string | null
Server-selected call route class.
* roomId: string | null
Conference room identifier, when applicable.
* displayName: string | null
Authenticated caller display name.
* avatarUrl: string | null
Authenticated caller avatar URL, when available.
* remoteIdentityUri: string | null
Normalized remote SIP identity URI.
* asteriskChannelId: string | null
Server-owned Asterisk channel identifier.
* asteriskBridgeId: string | null
Server-owned Asterisk bridge identifier.
* plannerToken: string | null
Opaque planner token bound to the call.
* deviceInstanceId: string | null
Device instance selected to own the call.
* metadata: object
Bounded server-authoritative call metadata.
* Server-authoritative call metadata value.
* rawHeaders: object
Normalized allowlisted SIP/app invite headers.
* Normalized SIP/app invite header 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:
{
"accepted": true,
"appCallId": "app-call-1",
"deviceInstanceId": "device-1",
"displayName": "Ophelia",
"msg": "",
"plannerToken": "planner-app-call-1",
"rawHeaders": {
"X-App-Call-Id": "app-call-1"
},
"remoteIdentityUri": "sip:ophelia@sip.example.com",
"result": "success",
"routeClass": "direct"
}