Add people to a call

POST https://connect.suryojasvi.com/api/v1/calls/{call_id}/participants

Ring more people into a call in a direct message conversation, as one adds someone to a phone call. They are rung, and join the call if they answer. Someone who turned the call down, missed it, or left it is rung again.

The call stays the conversation's it was placed in, which is where its entry is left when it ends.

Only someone on the call may add people to it, and a call can have at most 4 people, since each connects to every other directly.

Changes: New in Zulip 13.0 (feature level ZF-dd4ee5).

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/1/participants \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode 'user_ids=[10, 11]'

Parameters

call_id integer required in path

Example: 1

The ID of the call to act on.


user_ids (integer)[] required

Example: [10, 11]

The IDs of the users to ring.


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.

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"
    },
    "msg": "",
    "result": "success"
}

An example JSON response for when the call is no longer ringing:

{
    "code": "BAD_REQUEST",
    "msg": "That call has ended.",
    "result": "error"
}