Document all call instance methods (#341)

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: /* */});
 ```
 
 </TabItem>

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).
 

docusaurus/video/docusaurus/docs/api/basics/calls.mdx

@@ -20,6 +20,54 @@ import CallMemberSort from '../../../shared/video/_call-member-sort-fields.mdx';
 
 <CreateCall />
 
+### `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.
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```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' }],
+  },
+});
+```
+
+</TabItem>
+</Tabs>
+
+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).
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```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' }],
+  },
+});
+```
+
+</TabItem>
+</Tabs>
+
 ## Updating calls
 
 <UpdateCall />
@@ -28,6 +76,67 @@ import CallMemberSort from '../../../shared/video/_call-member-sort-fields.mdx';
 
 <CallMembers />
 
+## 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`.
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```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 },
+});
+```
+
+</TabItem>
+</Tabs>
+
+## 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.
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```js
+await call.endCall();
+```
+
+</TabItem>
+</Tabs>
+
+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(
 <CallMemberFilters />
 
 <FilterConditions />
+
+## Send custom event
+
+It's possible to send any custom event for a call:
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```js
+// the custom event can be any kind of data
+await call.sendCustomEvent({
+  type: 'draw',
+  x: 10,
+  y: 30,
+});
+```
+
+</TabItem>
+</Tabs>
+
+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.
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```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',
+});
+```
+
+</TabItem>
+</Tabs>

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
 
 <GoLive />
 
+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.