Conversas em grupo

Bate-papos em grupo usam o mesmo modelo de criptografia do X Chat 1:1: uma chave de conversa compartilhada pelos membros, empacotada para a chave pública de identidade de cada membro, com mensagens criptografadas e assinadas pelo Chat XDK. O que muda é a composição de membros, como você cria a conversa e, muitas vezes, campos de título/avatar criptografados na conversa. Fluxos 1:1 estão em Primeiros passos. Detalhes de endpoints estão em Referência da API → Conversas e mensagens.

Como os grupos diferem de 1:1

Tópico	1:1	Grupo
Identidade	Frequentemente endereçado por ID de usuário do par nos caminhos	O ID da conversa normalmente começa com `g`
Criar	Chaves + envio de mensagens para um usuário	APIs de criar / inicializar grupo, depois chaves
Participantes	Você + um par	Muitos usuários; a composição pode mudar
Metadados	Mínimos	Nome, avatar etc. podem ser texto cifrado (descriptografe com a chave da conversa)
Rotação de chave	Menos frequente	Comum quando pessoas entram ou saem

A criptografia continua sendo: Chat XDK para chaves e payloads; API do X para criar o grupo, publicar os empacotamentos de chave dos participantes, enviar mensagens e carregar eventos.

Crie o grupo e estabeleça as chaves

Gere o ID do grupo com POST /2/chat/conversations/group/initialize — o data.conversation_id da resposta é o ID com prefixo g que você usará em todos os passos abaixo.
Carregue a chave pública de identidade de cada membro e o public_key_version (rotas GET de chave pública em Chaves de criptografia; GET /2/users/public_keys busca vários usuários em uma requisição). Verifique cada registro com verify_key_binding antes de usá-lo (veja o aviso em Primeiros passos).
Execute prepare_group_create uma vez, com todos os membros (incluindo você), o ID com prefixo g e as listas de IDs de membros/administradores. Uma chamada gera a chave da conversa, empacota-a para cada membro e assina a criação com a identidade da sessão de set_identity — retorna duas assinaturas de ação (a mudança de chave da conversa e a criação do grupo).
POST /2/chat/conversations/group com os membros/administradores do grupo, conversation_key_version, conversation_participant_keys (SDK encrypted_key → API encrypted_conversation_key) e ambas as action_signatures. Falhas de validação vêm como mensagens estáveis e legíveis, por exemplo "Too many members: adding these members would exceed the allowed group size." ou "Cannot add all members: one or more of the requested members cannot be added to this conversation.".
Guarde a chave da conversa em bruto e a versão para criptografia/descriptografia.

prepare_group_create assina o title e a avatar_url que você passa e os incorpora literalmente no evento group-create. O servidor compara isso com sua requisição, então os valores de group_name / group_avatar_url no corpo do POST devem ser byte-idênticos ao que você passou ao SDK — caso contrário, a chamada falha na validação de assinatura.

# 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"]

// 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

// 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

// 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

// 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

// 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

O mapeamento do corpo para chaves de participantes e assinaturas de ação (message_id, encoded_message_event_detail, message_event_signature aninhado) é o mesmo do POST de chaves em Primeiros passos — chaves de conversa. Quando a composição mudar, chame prepare_group_members_change com os novos IDs de membros mais a lista atual (membros, administradores, membros pendentes e o título/avatar/TTL atuais, se definidos). Ele rotaciona a chave da conversa e, assim como group-create, retorna duas assinaturas de ação — faça POST de tudo isso para add members (POST /2/chat/conversations/{id}/members). Depois, espere tráfego de mudança de chave: trate-o como rotação de chave em Primeiros passos (extract_conversation_keys / decrypt_events e depois criptografe com a versão mais recente). Como prepare_group_members_change gera uma chave de conversa nova empacotada apenas para os membros que você passa, novos membros recebem a nova versão da chave e não conseguem descriptografar mensagens enviadas com versões anteriores. O contrário não é verdadeiro: a rotação nunca revoga o acesso a versões anteriores — qualquer pessoa que já possua uma chave antiga ainda pode ler as mensagens criptografadas com ela. Se você suspeitar que uma chave de conversa foi exposta, rotacione com prepare_conversation_key_change; isso protege apenas mensagens futuras.

Metadados de grupo criptografados

Alguns campos da conversa (por exemplo o nome de exibição ou a URL do avatar) podem chegar criptografados sob a chave da conversa. Isso não é encrypt_message; é o par genérico encrypt / decrypt do Chat XDK (string UTF-8 na entrada, texto cifrado em base64 na saída, com a chave da conversa em bruto). Se um determinado campo é armazenado criptografado é decidido pelo cliente que o escreve: prepare_group_create assina e envia o título exatamente como você o fornece (a chave da conversa não existe até essa chamada gerá-la, então um título no momento da criação não pode ser criptografado com ela). Ao ler uma conversa cujos campos são texto cifrado, descriptografe-os com decrypt e a versão de chave que estava ativa quando o campo foi escrito.

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

const groupName = chat.decrypt(conversation.groupName, rawConvKey);
const encryptedName = chat.encrypt('Project team', rawConvKey);

// 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)?;

groupName, err := chat.Decrypt(conversationGroupNameB64, rawConvKey)
encryptedName, err := chat.Encrypt("Project team", rawConvKey)
_ = groupName
_ = encryptedName

string groupName = chat.Decrypt(conversationGroupNameB64, rawConvKey);
string encryptedName = chat.Encrypt("Project team", rawConvKey);

String groupName = chat.decrypt(conversationGroupNameB64, rawConvKey);
String encryptedName = chat.encrypt("Project team", rawConvKey);

Use a versão atual da chave da conversa que se aplica a esse metadado. Se as chaves foram rotacionadas, descriptografe com a versão que estava ativa quando o campo foi escrito (ou siga as regras do produto se os metadados forem sempre reescritos na rotação).

Mensagens e eventos

Enviar e receber em um grupo é igual a 1:1 uma vez que você tenha a chave da conversa em bruto:

Enviar: encrypt_message → API send-message (Primeiros passos)
Receber: API de eventos ou entrega em tempo real → decrypt_event / decrypt_events
Mídia: Mídia com o ID da conversa de grupo

Sempre criptografe com a versão mais recente da chave após uma rotação motivada por mudança de composição.

Checklist

Gere o ID com prefixo g com POST /2/chat/conversations/group/initialize
prepare_group_create com todos os membros; faça POST dos empacotamentos de chave dos participantes e ambas as assinaturas de ação para POST /2/chat/conversations/group
Faça cache da chave em bruto + versão; atualize nos eventos de mudança de chave
Em mudanças de composição, prepare_group_members_change (duas assinaturas) → POST /2/chat/conversations/{id}/members
Descriptografe os metadados do grupo com decrypt quando os campos forem texto cifrado
Envie/receba com os mesmos padrões de 1:1

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Conversas em grupo

Como os grupos diferem de 1:1

Crie o grupo e estabeleça as chaves

Metadados de grupo criptografados

Mensagens e eventos

Checklist

​Como os grupos diferem de 1:1

​Crie o grupo e estabeleça as chaves

​Metadados de grupo criptografados

​Mensagens e eventos

​Checklist

Como os grupos diferem de 1:1

Crie o grupo e estabeleça as chaves

Metadados de grupo criptografados

Mensagens e eventos

Checklist