From 03a42a72bdd8a45b7ab8cf4e8df5195745e7a9bc Mon Sep 17 00:00:00 2001 From: Zita Szupera Date: Mon, 11 Dec 2023 16:28:10 +0100 Subject: [PATCH] Document all call instance methods --- .../docs/api/_common_/create-call.mdx | 5 +- .../docs/api/_common_/manage-call-members.mdx | 2 +- .../docusaurus/docs/api/basics/calls.mdx | 152 ++++++++++++++++++ .../docs/api/streaming/backstage.mdx | 2 + 4 files changed, 159 insertions(+), 2 deletions(-) diff --git a/docusaurus/video/docusaurus/docs/api/_common_/create-call.mdx b/docusaurus/video/docusaurus/docs/api/_common_/create-call.mdx index d6e1b124..4b21eb79 100644 --- a/docusaurus/video/docusaurus/docs/api/_common_/create-call.mdx +++ b/docusaurus/video/docusaurus/docs/api/_common_/create-call.mdx @@ -6,7 +6,7 @@ You can create a call by providing the call type and an ID: - The [call type](/api/call_types/builtin) controls which features are enabled and sets up permissions. Call type settings and permissions can be set from API, or using the [Stream Dashboard](https://dashboard.getstream.io/). - Calls IDs can be reused, which means they can be joined multiple times, so it's possible to set up recurring calls. -You can optionally restrict call access by providing a list of existing users. +You can specify call members who can receive push notification about the call. It's also possible to store any custom data with the call object. @@ -31,6 +31,9 @@ call.create({ }, }, }); + +// Upsert behavior +call.getOrCreate({data: /* */}); ``` diff --git a/docusaurus/video/docusaurus/docs/api/_common_/manage-call-members.mdx b/docusaurus/video/docusaurus/docs/api/_common_/manage-call-members.mdx index 195f79c7..ce2010c7 100644 --- a/docusaurus/video/docusaurus/docs/api/_common_/manage-call-members.mdx +++ b/docusaurus/video/docusaurus/docs/api/_common_/manage-call-members.mdx @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -You can restrict call access by defining a list of members who are allowed to join the call. Call members need to be existing users. Every call member has a call-level role, [you can configure roles](/api/call_types/permissions/) on the call type. +You can provide a list of call members. Call members need to be existing users. Every call member has a call-level role, [you can configure roles](/api/call_types/permissions/) on the call type. Call members can receive [push notifications](/api/call_types/settings/#push-notifications-settings). diff --git a/docusaurus/video/docusaurus/docs/api/basics/calls.mdx b/docusaurus/video/docusaurus/docs/api/basics/calls.mdx index e6995227..5fb518e2 100644 --- a/docusaurus/video/docusaurus/docs/api/basics/calls.mdx +++ b/docusaurus/video/docusaurus/docs/api/basics/calls.mdx @@ -20,6 +20,54 @@ import CallMemberSort from '../../../shared/video/_call-member-sort-fields.mdx'; +### `ring` flag + +To start the ringing flow, we need to set the `ring` flag to `true` and provide the list of members we want to call. It is important to note that the caller should also be included in the list of members. + + + + +```js +// or call.create +// or call.get +await client.call('default', 'test-outgoing-call').getOrCreate({ + ring: true, + data: { + created_by_id: 'myself', + members: [{ user_id: 'myself' }, { user_id: 'my friend' }], + }, +}); +``` + + + + +This step will start the signaling flow and send the `call.ring` WebSocket event. It's also possible to send push notifications to call members on this event, for more information see the [Call Types page](../call_types/builtin/#push-notifications-settings). + +Call members can decide to accept or reject the incoming call. The callee can decide to cancel the outgoing call (for more information see the [SDK documentations](https://getstream.io/video/docs/)). + +### `notify` flag + +Setting the `notify` flag to `true` will send the `call.notification` WebSocket event. It's also possible to send push notifications to call members on this event, for more information see the [Call Types page](../call_types/builtin/#push-notifications-settings). + + + + +```js +// or call.create +// or call.get +await client.call('default', 'test-outgoing-call').getOrCreate({ + notify: true, + data: { + created_by_id: 'myself', + members: [{ user_id: 'myself' }, { user_id: 'my friend' }], + }, +}); +``` + + + + ## Updating calls @@ -28,6 +76,67 @@ import CallMemberSort from '../../../shared/video/_call-member-sort-fields.mdx'; +## Restrict call access + +You can restrict access to a call by updating the [Call Type](../call_types/permissions/) permissions and roles. +A typical use case is to restrict access to a call to a specific set of users -> call members. + +By default, all users unless specified otherwise, have the `user` role. + +You can remove the `join-call` permission from the `user` role for the given call type scope. This will prevent regular users from joining a call of the given type. + +Next, let's ensure that the `call_member` role has the `join-call` permission for the given call type scope. This will allow users with the `call_member` role to join a call of this type. + +Once this is set, we can proceed with setting up a `call` instance and providing the `members`. + + + + +```js +const callType = (await client.video.listCallTypes()).call_types[callTypeName]; +// Remove JOIN_CALL permission from user role +const userGrants = callType.grants['user'].filter( + (c) => c !== VideoOwnCapability.JOIN_CALL, +); +// Make sure JOIN_CALL permission is set for call_member role +const callMemberGrants = callType.grants['call_member']; +if (!callMemberGrants.includes(VideoOwnCapability.JOIN_CALL)) { + callMemberGrants.push(VideoOwnCapability.JOIN_CALL); +} + +// Update the call type with the changes +await client.video.updateCallType(callTypeName, { + grants: { user: userGrants, call_member: callMemberGrants }, +}); +``` + + + + +## Sessions + +Call IDs can be reused, which means a call can be joined and left by participants multiple times. Every time the first participant joins the call, a new session is started. Every time the last participant left the call, the session is ended. + +- If a call session is started, the `call.session_started` WebSocket event will be dispatched. It's also possible to send push notifications to call members on this event, for more information see the [Call Types page](../call_types/builtin/#push-notifications-settings). + +- If a call session is ended, the `call.session_ended` WebSocket event will be dispatched. + +## Ending calls + +This action terminates the call for everyone. Ending a call requires the `end-call` permission. + + + + +```js +await call.endCall(); +``` + + + + +Only users with the `join-ended-call` permission can join an ended call. + ## Query calls For many video calling, live stream, or audio rooms apps, you'll want to show: @@ -245,3 +354,46 @@ call.query_members( + +## Send custom event + +It's possible to send any custom event for a call: + + + + +```js +// the custom event can be any kind of data +await call.sendCustomEvent({ + type: 'draw', + x: 10, + y: 30, +}); +``` + + + + +Sending a custom event will dispatch the `custom` WebSocket event. + +## Pin and unpin video + +You can pin the video of a participant in a call session. The SDKs will make sure that the pinned participant is displayed in a prominent location in the call layout for all participants. You can also unpin a pinned participant if you no longer want to highlight them. + + + + +```js +await call.pinVideo({ + session_id: 'session-id', + user_id: 'user-id-to-unpin', +}); + +await call.unpinVideo({ + session_id: 'session-id', + user_id: 'user-id-to-pin', +}); +``` + + + diff --git a/docusaurus/video/docusaurus/docs/api/streaming/backstage.mdx b/docusaurus/video/docusaurus/docs/api/streaming/backstage.mdx index 860ffd7d..a152224b 100644 --- a/docusaurus/video/docusaurus/docs/api/streaming/backstage.mdx +++ b/docusaurus/video/docusaurus/docs/api/streaming/backstage.mdx @@ -108,6 +108,8 @@ Optionally, you can start the HLS broadcast and/or recording at the same time as +It's also possible to send push notifications to call members on this event, for more information see the [Call Types page](../call_types/builtin/#push-notifications-settings). + ## Stop Live When the stream ends the `StopLive` endpoint will remove the viewers that are still in the call, and prevent from new viewers to join.