docs(call): Restricted call access docs (#1153)

packages/client/docusaurus/docs/javascript/02-guides/02-joining-creating-calls.mdx

@@ -6,7 +6,7 @@ description: An overview of how to create calls and join them
 
 This guide shows how to create, join, leave, and end call rooms and ring calls.
 
-## Call room
+## Call
 
 ### Create and join a call
 
@@ -143,3 +143,52 @@ The following options are supported when creating a call:
 | `startsAt` | When the call will start. Used for calls scheduled in the future, livestreams, audio rooms etc                  | -       |
 | `team`     | Restrict the access to this call to a specific team                                                             | -       |
 | `ring`     | If you want the call to ring for each member                                                                    | false   |
+
+### Restricting access
+
+You can restrict access to a call by tweaking the [Call Type](../../guides/configuring-call-types/) permissions and roles.
+A typical use case is to restrict access to a call to a specific set of users -> call members.
+
+#### Step 1: Set up the roles and permissions
+
+On our [dashboard](https://dashboard.getstream.io/), navigate to the **Video & Audio -> Roles & Permissions** section and select the appropriate role and scope.
+In this example, we will use `my-call-type` scope.
+
+By default, all users unless specified otherwise, have the `user` role.
+
+We start by removing the `JoinCall` permission from the `user` role for the `my-call-type` scope.
+It will prevent regular users from joining a call of this type.
+
+![Revoke JoinCall for user role](../assets/02-guides/02-joining-creating-calls/user-revoke-joincall.png)
+
+Next, let's ensure that the `call_member` role has the `JoinCall` permission for the `my-call-type` scope.
+It will allow users with the `call_member` role to join a call of this type.
+
+![Grant JoinCall for call_member role](../assets/02-guides/02-joining-creating-calls/call_member-grant-joincall.png)
+
+Once this is set, we can proceed with setting up a `call` instance.
+
+#### Step 2: Set up the call
+
+```typescript
+const call = client.call('my-call-type', 'my-call-id');
+await call.getOrCreate({
+  data: {
+    members: [
+      // please note the `role` property
+      { user_id: 'alice', role: 'call_member' },
+      { user_id: 'bob', role: 'call_member' },
+    ],
+  },
+});
+
+// and if necessary, to grant access to more users
+await call.updateCallMembers({
+  update_members: [{ user_id: 'charlie', role: 'call_member' }],
+});
+
+// or, to remove access from some users
+await call.updateCallMembers({
+  remove_members: ['charlie'],
+});
+```

packages/client/src/Call.ts

@@ -535,7 +535,7 @@ export class Call {
    *
    * @param params.ring if set to true, a `call.ring` event will be sent to the call members.
    * @param params.notify if set to true, a `call.notification` event will be sent to the call members.
-   * @param params.members_limit the members limit.
+   * @param params.members_limit the total number of members to return as part of the response.
    */
   get = async (params?: {
     ring?: boolean;

packages/react-sdk/docusaurus/docs/React/02-guides/02-joining-creating-calls.mdx

@@ -6,7 +6,7 @@ description: An overview of how to create calls and join them
 
 This guide shows how to create, join, leave, and end call rooms and ring calls.
 
-## Call room
+## Call
 
 ### Create and join a call
 
@@ -143,3 +143,52 @@ The following options are supported when creating a call:
 | `startsAt` | When the call will start. Used for calls scheduled in the future, livestreams, audio rooms etc                  | -       |
 | `team`     | Restrict the access to this call to a specific team                                                             | -       |
 | `ring`     | If you want the call to ring for each member                                                                    | false   |
+
+### Restricting access
+
+You can restrict access to a call by tweaking the [Call Type](../../guides/configuring-call-types/) permissions and roles.
+A typical use case is to restrict access to a call to a specific set of users -> call members.
+
+#### Step 1: Set up the roles and permissions
+
+On our [dashboard](https://dashboard.getstream.io/), navigate to the **Video & Audio -> Roles & Permissions** section and select the appropriate role and scope.
+In this example, we will use `my-call-type` scope.
+
+By default, all users unless specified otherwise, have the `user` role.
+
+We start by removing the `JoinCall` permission from the `user` role for the `my-call-type` scope.
+It will prevent regular users from joining a call of this type.
+
+![Revoke JoinCall for user role](../assets/02-guides/02-joining-creating-calls/user-revoke-joincall.png)
+
+Next, let's ensure that the `call_member` role has the `JoinCall` permission for the `my-call-type` scope.
+It will allow users with the `call_member` role to join a call of this type.
+
+![Grant JoinCall for call_member role](../assets/02-guides/02-joining-creating-calls/call_member-grant-joincall.png)
+
+Once this is set, we can proceed with setting up a `call` instance.
+
+#### Step 2: Set up the call
+
+```typescript
+const call = client.call('my-call-type', 'my-call-id');
+await call.getOrCreate({
+  data: {
+    members: [
+      // please note the `role` property
+      { user_id: 'alice', role: 'call_member' },
+      { user_id: 'bob', role: 'call_member' },
+    ],
+  },
+});
+
+// and if necessary, to grant access to more users
+await call.updateCallMembers({
+  update_members: [{ user_id: 'charlie', role: 'call_member' }],
+});
+
+// or, to remove access from some users
+await call.updateCallMembers({
+  remove_members: ['charlie'],
+});
+```