feat: Add doc for permission settings & announcement space support (#…

…7721)

feat: Add doc for import mode external users support
docs: Messages API dev docs improvement
docs: Memberships API dev docs improvement
docs: Discoverable space docs improvement
PiperOrigin-RevId: 681521060
Source-Link: googleapis/googleapis@c472cf7
Source-Link: googleapis/googleapis-gen@a905bb2
Copy-Tag: eyJwIjoiQXBwc0NoYXQvLk93bEJvdC55YW1sIiwiaCI6ImE5MDViYjIyYzk2OGViZGRlZDEzNmIyODJlZjA3Mzk5MmZjMTQwYzUifQ==

AppsChat/samples/V1/ChatServiceClient/create_membership.php

@@ -29,40 +29,25 @@
 use Google\Apps\Chat\V1\Membership;
 
 /**
- * Creates a human membership or app membership for the calling app. Creating
- * memberships for other apps isn't supported. For an example, see
- * [Invite or add a user or a Google Chat app to a
- * space](https://developers.google.com/workspace/chat/create-members).
+ * Creates a membership for the calling Chat app, a user, or a Google Group.
+ * Creating memberships for other Chat apps isn't supported.
  * When creating a membership, if the specified member has their auto-accept
  * policy turned off, then they're invited, and must accept the space
  * invitation before joining. Otherwise, creating a membership adds the member
- * directly to the specified space. Requires [user
+ * directly to the specified space.
+ * Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
  *
- * To specify the member to add, set the `membership.member.name` for the
- * human or app member, or set the `membership.group_member.name` for the
- * group member.
+ * For example usage, see:
  *
- * - To add the calling app to a space or a direct message between two human
- * users, use `users/app`. Unable to add other
- * apps to the space.
+ * - [Invite or add a user to a
+ * space](https://developers.google.com/workspace/chat/create-members#create-user-membership).
  *
- * - To add a human user, use `users/{user}`, where `{user}` can be the email
- * address for the user. For users in the same Workspace organization `{user}`
- * can also be the `id` for the person from the People API, or the `id` for
- * the user in the Directory API. For example, if the People API Person
- * profile ID for `user@example.com` is `123456789`, you can add the user to
- * the space by setting the `membership.member.name` to
- * `users/user@example.com` or `users/123456789`.
+ * - [Invite or add a Google Group to a
+ * space](https://developers.google.com/workspace/chat/create-members#create-group-membership).
  *
- * - To add or invite a Google group in a named space, use
- * `groups/{group}`, where `{group}` is the `id` for the group from the Cloud
- * Identity Groups API. For example, you can use [Cloud Identity Groups lookup
- * API](https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup)
- * to retrieve the ID `123456789` for group email `group@example.com`, then
- * you can add or invite the group to a named space by setting the
- * `membership.group_member.name` to `groups/123456789`. Group email is not
- * supported, and Google groups can only be added as members in named spaces.
+ * - [Add the Chat app to a
+ * space](https://developers.google.com/workspace/chat/create-members#create-membership-calling-api).
  *
  * @param string $formattedParent The resource name of the space for which to create the
  *                                membership.

AppsChat/samples/V1/ChatServiceClient/create_message.php

@@ -29,18 +29,30 @@
 use Google\Apps\Chat\V1\Message;
 
 /**
- * Creates a message in a Google Chat space. The maximum message size,
- * including text and cards, is 32,000 bytes. For an example, see [Send a
+ * Creates a message in a Google Chat space. For an example, see [Send a
  * message](https://developers.google.com/workspace/chat/create-messages).
  *
- * Calling this method requires
- * [authentication](https://developers.google.com/workspace/chat/authenticate-authorize)
- * and supports the following authentication types:
+ * The `create()` method requires either user or app authentication. Chat
+ * attributes the message sender differently depending on the type of
+ * authentication that you use in your request.
  *
- * - For text messages, user authentication or app authentication are
- * supported.
- * - For card messages, only app authentication is supported. (Only Chat apps
- * can create card messages.)
+ * The following image shows how Chat attributes a message when you use app
+ * authentication. Chat displays the Chat app as the message
+ * sender. The content of the message can contain text (`text`), cards
+ * (`cardsV2`), and accessory widgets (`accessoryWidgets`).
+ *
+ * ![Message sent with app
+ * authentication](https://developers.google.com/workspace/chat/images/message-app-auth.svg)
+ *
+ * The following image shows how Chat attributes a message when you use user
+ * authentication. Chat displays the user as the message sender and attributes
+ * the Chat app to the message by displaying its name. The content of message
+ * can only contain text (`text`).
+ *
+ * ![Message sent with user
+ * authentication](https://developers.google.com/workspace/chat/images/message-user-auth.svg)
+ *
+ * The maximum message size, including the message contents, is 32,000 bytes.
  *
  * @param string $formattedParent The resource name of the space in which to create a message.
  *

AppsChat/samples/V1/ChatServiceClient/create_space.php

@@ -29,14 +29,19 @@
 use Google\Apps\Chat\V1\Space;
 
 /**
- * Creates a named space. Spaces grouped by topics aren't supported. For an
- * example, see [Create a
+ * Creates a space with no members. Can be used to create a named space.
+ * Spaces grouped by topics aren't supported. For an example, see
+ * [Create a
  * space](https://developers.google.com/workspace/chat/create-spaces).
  *
  * If you receive the error message `ALREADY_EXISTS` when creating
  * a space, try a different `displayName`. An existing space within
  * the Google Workspace organization might already use this display name.
  *
+ * If you're a member of the [Developer Preview
+ * program](https://developers.google.com/workspace/preview), you can create a
+ * group chat in import mode using `spaceType.GROUP_CHAT`.
+ *
  * Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
  *

AppsChat/samples/V1/ChatServiceClient/get_space_event.php

@@ -36,6 +36,9 @@
  * updated, the server returns the updated `Message` resource in the event
  * payload.
  *
+ * Note: The `permissionSettings` field is not returned in the Space
+ * object of the Space event data for this request.
+ *
  * Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
  * To get an event, the authenticated user must be a member of the space.

AppsChat/samples/V1/ChatServiceClient/list_messages.php

@@ -31,8 +31,12 @@
 
 /**
  * Lists messages in a space that the caller is a member of, including
- * messages from blocked members and spaces. For an example, see
- * [List messages](/chat/api/guides/v1/messages/list).
+ * messages from blocked members and spaces. If you list messages from a
+ * space with no messages, the response is an empty object. When using a
+ * REST/HTTP interface, the response contains an empty JSON object, `{}`.
+ * For an example, see
+ * [List
+ * messages](https://developers.google.com/workspace/chat/api/guides/v1/messages/list).
  * Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
  *

AppsChat/src/Chat/V1/Client/ChatServiceClient.php

@@ -502,40 +502,25 @@ public function completeImportSpace(
     }
 
     /**
-     * Creates a human membership or app membership for the calling app. Creating
-     * memberships for other apps isn't supported. For an example, see
-     * [Invite or add a user or a Google Chat app to a
-     * space](https://developers.google.com/workspace/chat/create-members).
+     * Creates a membership for the calling Chat app, a user, or a Google Group.
+     * Creating memberships for other Chat apps isn't supported.
      * When creating a membership, if the specified member has their auto-accept
      * policy turned off, then they're invited, and must accept the space
      * invitation before joining. Otherwise, creating a membership adds the member
-     * directly to the specified space. Requires [user
+     * directly to the specified space.
+     * Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
      *
-     * To specify the member to add, set the `membership.member.name` for the
-     * human or app member, or set the `membership.group_member.name` for the
-     * group member.
-     *
-     * - To add the calling app to a space or a direct message between two human
-     * users, use `users/app`. Unable to add other
-     * apps to the space.
-     *
-     * - To add a human user, use `users/{user}`, where `{user}` can be the email
-     * address for the user. For users in the same Workspace organization `{user}`
-     * can also be the `id` for the person from the People API, or the `id` for
-     * the user in the Directory API. For example, if the People API Person
-     * profile ID for `user@example.com` is `123456789`, you can add the user to
-     * the space by setting the `membership.member.name` to
-     * `users/user@example.com` or `users/123456789`.
-     *
-     * - To add or invite a Google group in a named space, use
-     * `groups/{group}`, where `{group}` is the `id` for the group from the Cloud
-     * Identity Groups API. For example, you can use [Cloud Identity Groups lookup
-     * API](https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup)
-     * to retrieve the ID `123456789` for group email `group@example.com`, then
-     * you can add or invite the group to a named space by setting the
-     * `membership.group_member.name` to `groups/123456789`. Group email is not
-     * supported, and Google groups can only be added as members in named spaces.
+     * For example usage, see:
+     *
+     * - [Invite or add a user to a
+     * space](https://developers.google.com/workspace/chat/create-members#create-user-membership).
+     *
+     * - [Invite or add a Google Group to a
+     * space](https://developers.google.com/workspace/chat/create-members#create-group-membership).
+     *
+     * - [Add the Chat app to a
+     * space](https://developers.google.com/workspace/chat/create-members#create-membership-calling-api).
      *
      * The async variant is {@see ChatServiceClient::createMembershipAsync()} .
      *
@@ -561,18 +546,30 @@ public function createMembership(CreateMembershipRequest $request, array $callOp
     }
 
     /**
-     * Creates a message in a Google Chat space. The maximum message size,
-     * including text and cards, is 32,000 bytes. For an example, see [Send a
+     * Creates a message in a Google Chat space. For an example, see [Send a
      * message](https://developers.google.com/workspace/chat/create-messages).
      *
-     * Calling this method requires
-     * [authentication](https://developers.google.com/workspace/chat/authenticate-authorize)
-     * and supports the following authentication types:
+     * The `create()` method requires either user or app authentication. Chat
+     * attributes the message sender differently depending on the type of
+     * authentication that you use in your request.
      *
-     * - For text messages, user authentication or app authentication are
-     * supported.
-     * - For card messages, only app authentication is supported. (Only Chat apps
-     * can create card messages.)
+     * The following image shows how Chat attributes a message when you use app
+     * authentication. Chat displays the Chat app as the message
+     * sender. The content of the message can contain text (`text`), cards
+     * (`cardsV2`), and accessory widgets (`accessoryWidgets`).
+     *
+     * ![Message sent with app
+     * authentication](https://developers.google.com/workspace/chat/images/message-app-auth.svg)
+     *
+     * The following image shows how Chat attributes a message when you use user
+     * authentication. Chat displays the user as the message sender and attributes
+     * the Chat app to the message by displaying its name. The content of message
+     * can only contain text (`text`).
+     *
+     * ![Message sent with user
+     * authentication](https://developers.google.com/workspace/chat/images/message-user-auth.svg)
+     *
+     * The maximum message size, including the message contents, is 32,000 bytes.
      *
      * The async variant is {@see ChatServiceClient::createMessageAsync()} .
      *
@@ -629,14 +626,19 @@ public function createReaction(CreateReactionRequest $request, array $callOption
     }
 
     /**
-     * Creates a named space. Spaces grouped by topics aren't supported. For an
-     * example, see [Create a
+     * Creates a space with no members. Can be used to create a named space.
+     * Spaces grouped by topics aren't supported. For an example, see
+     * [Create a
      * space](https://developers.google.com/workspace/chat/create-spaces).
      *
      * If you receive the error message `ALREADY_EXISTS` when creating
      * a space, try a different `displayName`. An existing space within
      * the Google Workspace organization might already use this display name.
      *
+     * If you're a member of the [Developer Preview
+     * program](https://developers.google.com/workspace/preview), you can create a
+     * group chat in import mode using `spaceType.GROUP_CHAT`.
+     *
      * Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
      *
@@ -985,6 +987,9 @@ public function getSpace(GetSpaceRequest $request, array $callOptions = []): Spa
      * updated, the server returns the updated `Message` resource in the event
      * payload.
      *
+     * Note: The `permissionSettings` field is not returned in the Space
+     * object of the Space event data for this request.
+     *
      * Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
      * To get an event, the authenticated user must be a member of the space.
@@ -1126,8 +1131,12 @@ public function listMemberships(ListMembershipsRequest $request, array $callOpti
 
     /**
      * Lists messages in a space that the caller is a member of, including
-     * messages from blocked members and spaces. For an example, see
-     * [List messages](/chat/api/guides/v1/messages/list).
+     * messages from blocked members and spaces. If you list messages from a
+     * space with no messages, the response is an empty object. When using a
+     * REST/HTTP interface, the response contains an empty JSON object, `{}`.
+     * For an example, see
+     * [List
+     * messages](https://developers.google.com/workspace/chat/api/guides/v1/messages/list).
      * Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
      *