Start a call
POST https://connect.suryojasvi.com/api/v1/calls
Start a call ringing for the people in a direct message
conversation, or for the members of a group.
A call rings the people it is for, the way a telephone does,
rather than posting a link for them to notice later. Public
channels cannot be called: a channel can have hundreds of
members with no expectation of being interrupted.
Groups above a size are placed without ringing, so that a call
does not interrupt dozens of people at once; the response says
which happened.
Changes: New in Zulip 13.0 (feature level ZF-6022cf).
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://connect.suryojasvi.com/api/v1/calls \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode 'user_ids=[10, 11]' \
--data-urlencode stream_id=42 \
--data-urlencode is_video=true
Parameters
user_ids (integer)[] optional
Example: [10, 11]
The users to call, as a JSON-encoded list of user IDs.
The user making the request is always included, whether
or not they are listed.
Exactly one of user_ids and stream_id must be given.
stream_id integer optional
Example: 42
The ID of the group to call.
Exactly one of user_ids and stream_id must be given.
is_video boolean optional
Example: true
Whether the camera should start on. A voice call and a
video call differ only in this, but the distinction
reaches the other end so that it can say which kind is
ringing.
Defaults to false.
Response
Return values
-
call: object | null
A call, in the sense a telephone means it.
-
id: integer
The unique ID of the call.
-
initiator_id: integer
The ID of the user who started the call.
-
recipient_type: integer
Whether the call belongs to a direct message conversation
(3) or to a group (2).
-
recipient_type_id: integer
The ID of the direct message group or the channel the call
belongs to, according to recipient_type.
-
is_video: boolean
Whether the camera starts on.
-
status: string
"R" while it is ringing and nobody has answered, "A" once
somebody has, and "E" once it is over.
-
room_url: string
The URL of the video room to join. Built for the requesting
user, because the video provider is a property of their
organization.
-
ice_servers: (object)[]
The STUN and TURN servers a two-person call, which is carried
directly between the two clients, finds its route through, in
the form of WebRTC's RTCIceServer. A TURN server, where the
server has one configured, comes with a credential that
expires after a day.
-
urls: (string)[]
The server's STUN or TURN URLs.
-
username: string
For a TURN server, the username to authenticate with.
-
credential: string
For a TURN server, the credential to authenticate with.
-
participants: (object)[]
Everyone the call is for, including whoever started it.
-
user_id: integer
The ID of the user.
-
status: string
"R" while their phone is ringing, "A" if they
answered, "D" if they declined, "M" if they never
answered, and "L" if they answered and have left.
-
is_ringing: boolean
Whether the people called are being rung. This is
false for a group too large to ring, where the
call is placed to be joined instead.
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:
{
"call": {
"id": 1,
"initiator_id": 10,
"is_video": false,
"participants": [
{
"status": "A",
"user_id": 10
},
{
"status": "R",
"user_id": 11
}
],
"recipient_type": 3,
"recipient_type_id": 27,
"room_url": "https://meet.jit.si/connect-BJvS0m3iQ0OQ1kA",
"status": "R"
},
"is_ringing": true,
"msg": "",
"result": "success"
}
An example JSON response for when a public channel
was called:
{
"code": "BAD_REQUEST",
"msg": "You can only call a group, not a channel.",
"result": "error"
}
An example JSON response for when the organization
has no video call provider configured:
{
"code": "BAD_REQUEST",
"msg": "Calls are not enabled in this organization.",
"result": "error"
}