Method: spaces.setup

建立聊天室並將指定的使用者新增至聊天室。通話使用者會自動加入聊天室,且不應在要求中指定為成員資格。如需範例,請參閱「設定包含初始成員的聊天室」。

如要指定要新增的真人成員,請使用適當的 membership.member.name 新增成員資格。如要新增真人使用者,請使用 users/{user},其中 {user} 可以是使用者的電子郵件地址。對於同一個 Workspace 機構 ({user}) 中的使用者,您也可以為 People API 中的使用者設定 id,或是在 Directory API 中為使用者設定 id。舉例來說,如果 user@example.com 的 People API 個人資料 ID 為 123456789,您可以將 membership.member.name 設為 users/user@example.comusers/123456789,將使用者新增至聊天室。

如要指定要新增的 Google 群組,請使用適當的 membership.group_member.name 新增成員資格。如要新增或邀請 Google 群組,請使用 groups/{group},其中 {group} 是 Cloud Identity Groups API 中的群組 id。舉例來說,您可以使用 Cloud Identity Groups lookup API 擷取群組電子郵件地址 group@example.com 的 ID 123456789,然後將 membership.group_member.name 設為 groups/123456789,將群組新增至聊天室。系統不支援群組電子郵件,而且您只能在已命名的聊天室中將 Google 群組新增為成員。

如果已命名的聊天室或群組通訊,如果來電者封鎖對象、遭到部分成員封鎖,或是沒有新增成員的權限,這些成員就不會加入建立的聊天室。

如要在發起通話的使用者和另一位真人使用者之間建立即時訊息 (DM),請指定一個代表真人使用者的成員資格。如果某位使用者封鎖另一位使用者,則該要求會失敗,系統也不會建立即時訊息。

如要在發出呼叫的使用者和呼叫應用程式之間建立即時訊息,請將 Space.singleUserBotDm 設為 true,且不要指定任何成員資格。你只能使用這個方法透過呼叫應用程式設定即時訊息。如要將通話應用程式新增為聊天室成員,或兩位真人使用者之間的現有即時訊息,請參閱「邀請或將使用者或應用程式新增至聊天室」。

如果兩位使用者之間已經存在即時訊息,即使其中一位使用者在提出要求時封鎖另一位使用者,系統仍會傳回現有的即時訊息。

不支援含有討論串回覆的聊天室。如果在設定聊天室時收到「ALREADY_EXISTS」錯誤訊息,請嘗試使用其他displayName。Google Workspace 機構中的現有聊天室可能已使用這個顯示名稱。

需要使用者驗證

HTTP 要求

POST https://chat.googleapis.com/v1/spaces:setup

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "space": {
    object (Space)
  },
  "requestId": string,
  "memberships": [
    {
      object (Membership)
    }
  ]
}
欄位
space

object (Space)

必要欄位。Space.spaceType 為必填欄位。

如要建立聊天室,請將「Space.spaceType」設為「SPACE」並設定 Space.displayName。如果在設定聊天室時收到「ALREADY_EXISTS」錯誤訊息,請嘗試使用其他displayName。Google Workspace 機構中的現有聊天室可能已使用這個顯示名稱。

如要建立群組通訊,請將 Space.spaceType 設為 GROUP_CHAT。不要設定 Space.displayName

如要在真人之間建立 1:1 對話,請將 Space.spaceType 設為 DIRECT_MESSAGE,並將 Space.singleUserBotDm 設為 false。請勿設定 Space.displayNameSpace.spaceDetails

如要在真人和通話應用程式之間建立 1:1 對話,請將 Space.spaceType 設為 DIRECT_MESSAGE,並將 Space.singleUserBotDm 設為 true。請勿設定 Space.displayNameSpace.spaceDetails

如果 DIRECT_MESSAGE 聊天室已存在,系統會傳回該聊天室,而不是建立新聊天室。

requestId

string

選用設定。這項要求的專屬 ID。建議隨機產生 UUID。指定現有的要求 ID 時,系統會傳回使用該 ID 建立的聊天室,而不會建立新空間。在同一個 Chat 應用程式中指定現有要求 ID,但該要求 ID 與其他使用者不同。在這種情況下,系統會傳回錯誤。

memberships[]

object (Membership)

選用設定。要邀請加入聊天室的 Google Chat 使用者或群組。省略呼叫的使用者 (由系統自動新增)。

設定目前除了來電者以外,最多允許 20 個會員資格。

如果是人類成員資格,Membership.member 欄位必須包含 user,且已填入 name (格式:users/{user}),type 則設為 User.Type.HUMAN。只能在設定聊天室時新增真人使用者 (只能透過通話應用程式新增即時通訊應用程式)。您也可以使用使用者的電子郵件地址做為 {user} 的別名,以便新增成員。舉例來說,user.name 可以是 users/example@gmail.com。如要邀請 Gmail 使用者或外部 Google Workspace 網域的使用者,必須使用使用者的電子郵件地址來邀請 {user}

如果是 Google 群組成員,Membership.group_member 欄位必須包含 group 且已填入 name (格式:groups/{group})。只有在將「Space.spaceType」設為「SPACE」時,才能新增 Google 群組。

Space.spaceType 設為 SPACE 時可選用。

Space.spaceType 設為 GROUP_CHAT,且至少有兩個成員時,此為必要欄位。

Space.spaceType 設為 DIRECT_MESSAGE 且包含真人使用者 (含一個成員資格) 時,此為必要欄位。

為真人和發出呼叫的 Chat 應用程式進行 1:1 對話 (將 Space.spaceType 設為 DIRECT_MESSAGE,並將 Space.singleUserBotDm 設為 true 時),這個欄位必須留空。

回應主體

如果成功,回應主體會包含 Space 的執行例項。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.create

詳情請參閱授權指南