> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-d8d2882f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 그룹 대화

> 공유된 대화 키, 암호화된 제목, 멤버 관리, 서명된 메시지를 갖춘 다자간 X Chat 그룹 대화를 생성합니다.

그룹 채팅은 1:1 X Chat과 **동일한 암호화 모델**을 사용합니다: 한 개의 **대화 키**가 멤버 간에 공유되고, 각 멤버의 **아이덴티티 공개 키**로 감싸지며, 메시지는 Chat XDK로 암호화되고 서명됩니다. 달라지는 점은 **멤버십**, **대화 생성 방법**, 그리고 종종 대화의 **암호화된 제목/아바타** 필드입니다.

1:1 흐름은 [시작하기](/ko/xchat/getting-started)에 있습니다. 엔드포인트 세부 정보는 **API 레퍼런스 → Conversations and messages** 아래에 있습니다.

***

## 그룹이 1:1과 어떻게 다른가

| 주제    | 1:1                    | 그룹                                  |
| :---- | :--------------------- | :---------------------------------- |
| 아이덴티티 | 종종 경로에서 상대방 사용자 ID로 지정 | 대화 ID가 일반적으로 `g`로 시작                |
| 생성    | 사용자에게 키 + 메시징          | Create / initialize group API 후 키   |
| 참여자   | 당신 + 상대방 한 명           | 여러 사용자; 멤버십이 변경될 수 있음               |
| 메타데이터 | 최소                     | 이름, 아바타 등이 **암호문**일 수 있음(대화 키로 복호화) |
| 키 순환  | 덜 빈번                   | 사람이 참여하거나 나갈 때 일반적                  |

암호화는 여전히 다음과 같습니다: 키와 페이로드를 위한 **Chat XDK**; 그룹 생성, 참여자 키 감싸기 게시, 메시지 전송, 이벤트 로드를 위한 **X API**.

***

## 그룹 생성 및 키 설정

1. `POST /2/chat/conversations/group/initialize`로 그룹 ID를 만드세요—응답의 `data.conversation_id`는 아래 모든 곳에서 사용하는 g가 접두된 ID입니다.
2. 각 멤버의 아이덴티티 공개 키와 `public_key_version`을 로드하세요(**Encryption keys** 아래의 `GET` 공개 키 경로; [`GET /2/users/public_keys`](/x-api/users/get-public-keys-for-multiple-users)는 한 요청으로 여러 사용자를 가져옵니다). 사용하기 전에 `verify_key_binding`으로 각 레코드를 검증하세요([시작하기](/ko/xchat/getting-started#4-set-up-conversation-keys)의 경고 참고).
3. **모든** 멤버(자신 포함), g가 접두된 ID, 멤버/관리자 ID 목록과 함께 \*\*`prepare_group_create`\*\*을 한 번 실행하세요. 한 번의 호출로 대화 키를 생성하고, 모든 멤버에게 감싸며, `set_identity`의 세션 아이덴티티로 create에 서명합니다—**두 개**의 액션 서명(대화 키 변경과 그룹 create)을 반환합니다.
4. 그룹 members/admins, `conversation_key_version`, `conversation_participant_keys`(SDK **`encrypted_key`** → API **`encrypted_conversation_key`**), 그리고 **두 개 모두**의 `action_signatures`와 함께 `POST /2/chat/conversations/group`을 호출하세요. 검증 실패는 안정적이고 사람이 읽을 수 있는 메시지로 돌아옵니다. 예: `"Too many members: adding these members would exceed the allowed group size."` 또는 `"Cannot add all members: one or more of the requested members cannot be added to this conversation."`.
5. 암호화/복호화를 위해 **원시** 대화 키와 **버전**을 보관하세요.

`prepare_group_create`는 전달한 `title`과 `avatar_url`에 서명하여 그룹 생성 이벤트에 원본 그대로 포함시킵니다. 서버는 이를 요청과 대조하므로, POST 본문의 `group_name` / `group_avatar_url` 값은 SDK에 전달한 것과 **바이트 단위로 동일**해야 합니다—그렇지 않으면 호출이 서명 검증에 실패합니다.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # chat has keys loaded and set_identity called (see Getting Started)
    prepared = chat.prepare_group_create(
        member_public_keys,
        group_id,  # g-prefixed id from POST /2/chat/conversations/group/initialize
        member_ids, admin_ids, title="Project team",
    )
    # POST /2/chat/conversations/group with group_members, group_admins,
    # conversation_key_version, conversation_participant_keys, and BOTH
    # entries of prepared["action_signatures"]
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    const prepared = chat.prepareGroupCreate({
      publicKeys: memberPublicKeys,
      conversationId: groupId, // g-prefixed id from POST /2/chat/conversations/group/initialize
      memberIds, adminIds, title: 'Project team',
    });
    // prepared.actionSignatures has two entries — send both
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // chat has keys loaded and set_identity called (see Getting Started)
    let mut params = GroupCreateParams::new(
        member_public_keys, &group_id, member_ids, admin_ids,
    );
    params.title = Some("Project team".into());
    let prepared = chat.prepare_group_create(params)?;
    // prepared.action_signatures has two entries — send both
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    prepared, err := chat.PrepareGroupCreate(chatxdk.GroupCreateParams{
        PublicKeys: memberPublicKeys, ConversationID: groupID,
        MemberIDs: memberIDs, AdminIDs: adminIDs, Title: "Project team",
    })
    // prepared.ActionSignatures has two entries — send both
    _ = prepared
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    // chat has keys loaded and SetIdentity called (see Getting Started)
    var prepared = chat.PrepareGroupCreate(
        new GroupCreateParams(memberPublicKeys, groupId, memberIds, adminIds)
        {
            Title = "Project team",
        });
    // prepared.ActionSignatures has two entries — send both
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    // chat has keys loaded and setIdentity called (see Getting Started)
    GroupCreateParams params =
        new GroupCreateParams(memberPublicKeys, groupId, memberIds, adminIds);
    params.title = "Project team";
    PreparedConversationChange prepared = chat.prepareGroupCreate(params);
    // prepared.actionSignatures has two entries — send both
    ```
  </Tab>
</Tabs>

참여자 키와 액션 서명(`message_id`, `encoded_message_event_detail`, 중첩된 `message_event_signature`)의 본문 매핑은 [시작하기 — 대화 키](/ko/xchat/getting-started#4-set-up-conversation-keys)의 키 POST와 동일합니다.

멤버십이 변경될 때는 새 멤버 ID와 현재 명단(members, admins, pending members, 현재 title/avatar/TTL이 설정되어 있다면 포함)으로 \*\*`prepare_group_members_change`\*\*를 호출하세요. 이는 대화 키를 순환하고, 그룹 create와 마찬가지로 **두 개**의 액션 서명을 반환합니다—모두를 **add members**(`POST /2/chat/conversations/{id}/members`)에 POST하세요. 그런 다음 **키 변경** 트래픽을 예상하세요: [시작하기의 키 순환](/ko/xchat/getting-started#6-receive-and-decrypt)처럼 취급하세요(`extract_conversation_keys` / `decrypt_events`, 그 후 최신 버전으로 암호화).

`prepare_group_members_change`는 전달한 명단에만 감싸진 **새로운** 대화 키를 생성하므로, 새 멤버는 새 키 버전을 받으며 이전 버전으로 전송된 메시지는 복호화할 수 없습니다. 반대는 성립하지 않습니다: 순환은 **이전** 버전에 대한 접근을 결코 취소하지 않습니다—오래된 키를 이미 가진 사람은 그 키로 암호화된 메시지를 여전히 읽을 수 있습니다. 대화 키가 노출된 것으로 의심되면 `prepare_conversation_key_change`로 순환하세요. 이는 미래의 메시지만 보호합니다.

***

## 암호화된 그룹 메타데이터

일부 대화 필드(예: 표시 **이름** 또는 **아바타 URL**)는 대화 키로 **암호화되어** 도착할 수 있습니다. 이는 `encrypt_message`가 **아닙니다**. Chat XDK의 범용 **`encrypt` / `decrypt`** 쌍입니다(UTF-8 문자열 입력, base64 암호문 출력, **원시** 대화 키 사용).

특정 필드가 암호화되어 저장될지는 이를 쓰는 클라이언트가 결정합니다: `prepare_group_create`는 제공한 대로 정확히 title을 서명하고 전송합니다(대화 키는 그 호출이 생성할 때까지 존재하지 않으므로, 생성 시 title은 그 키로 암호화될 수 없습니다). 필드가 암호문인 대화를 읽을 때는, 필드가 작성될 당시 활성화되어 있던 키 버전으로 `decrypt`를 사용해 복호화하세요.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Decrypt a field from the conversation object (name may vary by API shape)
    group_name = chat.decrypt(conversation["group_name"], raw_conv_key)

    # Encrypt before update if your API accepts ciphertext metadata
    encrypted_name = chat.encrypt("Project team", raw_conv_key)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const groupName = chat.decrypt(conversation.groupName, rawConvKey);
    const encryptedName = chat.encrypt('Project team', rawConvKey);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let group_name = chat.decrypt(&conversation_group_name_b64, &conv_key)?;
    let encrypted_name = chat.encrypt("Project team", &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    groupName, err := chat.Decrypt(conversationGroupNameB64, rawConvKey)
    encryptedName, err := chat.Encrypt("Project team", rawConvKey)
    _ = groupName
    _ = encryptedName
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    string groupName = chat.Decrypt(conversationGroupNameB64, rawConvKey);
    string encryptedName = chat.Encrypt("Project team", rawConvKey);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String groupName = chat.decrypt(conversationGroupNameB64, rawConvKey);
    String encryptedName = chat.encrypt("Project team", rawConvKey);
    ```
  </Tab>
</Tabs>

해당 메타데이터에 적용되는 **현재** 대화 키 버전을 사용하세요. 키가 순환된 경우 필드가 작성된 당시 활성화되어 있던 버전으로 복호화하세요(또는 메타데이터가 항상 순환 시 다시 쓰인다면 제품 규칙을 따르세요).

***

## 메시지와 이벤트

원시 대화 키를 얻은 후 그룹에서의 전송과 수신은 1:1과 동일합니다:

* **전송:** `encrypt_message` → send-message API([시작하기](/ko/xchat/getting-started#5-send-a-message))
* **수신:** events API 또는 [실시간 전달](/ko/xchat/real-time-events) → `decrypt_event` / `decrypt_events`
* **미디어:** 그룹 대화 ID와 함께 [미디어](/ko/xchat/media)

멤버십에 의한 순환 이후에는 항상 **최신** 키 버전으로 암호화하세요.

***

## 체크리스트

1. `POST /2/chat/conversations/group/initialize`로 g가 접두된 ID를 생성
2. **모든** 멤버와 함께 `prepare_group_create`; 참여자 키 감싸기와 **두 개 모두**의 액션 서명을 `POST /2/chat/conversations/group`에 POST
3. 원시 키 + 버전을 캐시; 키 변경 이벤트에 따라 업데이트
4. 멤버십 변경 시 `prepare_group_members_change`(서명 두 개) → `POST /2/chat/conversations/{id}/members`
5. 필드가 암호문인 경우 `decrypt`로 그룹 메타데이터 복호화
6. 1:1과 동일한 패턴으로 송수신