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"
}