Send a call signal

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

Relay one step of a WebRTC negotiation to another participant in a call.

Two people on a call can connect their browsers directly, which they arrange by exchanging descriptions of how each can be reached: an offer, an answer, and a list of candidate network routes. This endpoint carries one such description to the participant it is addressed to, as a call_signal event. The server stores none of it and is not otherwise in the call.

Calls with more than two participants use the organization's video provider instead, which needs no signalling of this kind.

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

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/signal \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode recipient_id=10 \
    --data-urlencode 'signal={"kind": "offer", "sdp": "v=0\\r\\n..."}'

Parameters

call_id integer required in path

Example: 1

The ID of the call to act on.


recipient_id integer required

Example: 10

The ID of the participant to hand this signal to. Must be someone on the call.


signal object required

Example: {"kind": "offer", "sdp": "v=0\\r\\n..."}

The negotiation step itself.

signal object details:

  • kind: string required

    Which step this is; or video, to say whether the sender is sending video.

    Changes: video is new in Zulip 13.0 (feature level ZF-9c788a).

    Must be one of: "offer", "answer", "candidate", "video".

  • sdp: string optional

    The session description, for an offer or an answer.

  • candidate: string optional

    The candidate string, for a candidate.

  • sdp_mid: string optional

    The media stream identification the candidate belongs to.

  • sdp_m_line_index: integer optional

    The index of the media description the candidate belongs to.

  • username_fragment: string optional

    The candidate's username fragment.

  • sending_video: boolean optional

    For video: whether the sender is now sending video -- a camera or a shared screen -- so that the recipient can show the sender's picture in place of a frozen frame when they stop.

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

  • video_source: string optional

    For video, while sending_video: whether the video is from a camera or a shared screen, so that the recipient can show a shared screen whole.

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

    Must be one of: "camera", "screen".


Response

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:

{
    "msg": "",
    "result": "success"
}