> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Gerenciar grupos do WhatsApp > Saiba como criar grupos do WhatsApp somente para convidados, convidar pessoas, revisar solicitações de entrada e gerenciar configurações de grupo. ## O que é A API de Grupos do WhatsApp da YCloud permite que sua empresa crie grupos do WhatsApp somente para convidados. Você envia um link de convite para cada pessoa, e ela escolhe se deseja entrar. Se o grupo exigir aprovação, você poderá revisar a solicitação de entrada da pessoa antes de permitir seu acesso ao grupo. Este guia aborda a configuração do grupo, o gerenciamento e o envio de mensagens para grupos. As conversas de grupo não aparecem no Inbox. ## Antes de começar Antes de integrar, certifique-se de que seu número de telefone comercial do WhatsApp atende a estes requisitos: * A empresa tem uma Conta Comercial Oficial (OBA). * O número de telefone usa a WhatsApp Cloud API, não o aplicativo WhatsApp Business. * O número de telefone não usa Conversas com Várias Soluções. * Sua conta da YCloud tem acesso ao número de telefone. * Você tem uma URL HTTPS pública para onde a YCloud possa enviar eventos de webhook. * Antes de enviar links de convite por meio de uma mensagem de modelo, você tem um modelo de convite de grupo aprovado. A YCloud gerencia as assinaturas necessárias da plataforma WhatsApp. Você só precisa [configurar um endpoint de webhook da YCloud](/pt/api-reference/guides/api-fundamentals/configure-webhooks) e selecionar os eventos de grupo da YCloud que deseja receber. A YCloud e o WhatsApp verificam se o número de telefone é qualificado. Se não for, verifique seu status de OBA, a configuração da Cloud API e o acesso na YCloud. ## Recursos suportados e limites Atualmente, a YCloud suporta: * Criar, listar, recuperar e excluir grupos. * Recuperar e redefinir links de convite. * Enviar um modelo de link de convite aprovado para um usuário individual do WhatsApp. * Listar, aprovar e rejeitar solicitações de entrada. * Remover participantes. * Atualizar o assunto e a descrição do grupo. * Atualizar a foto de perfil do grupo com um arquivo JPEG. * Enviar mensagens de texto, mídia, figurinha e modelos suportados para um grupo. * Receber webhooks de ciclo de vida do grupo, participantes, configurações e suspensão. A plataforma WhatsApp aplica estes limites: * Um grupo pode ter até 8 participantes. * Um número de telefone comercial pode criar até 10.000 grupos. * Um grupo pode conter apenas um número de telefone comercial da Cloud API. * Uma única requisição da YCloud pode remover até 8 participantes. * O assunto de um grupo pode conter até 128 caracteres. * A descrição de um grupo pode conter até 2.048 caracteres. Essas APIs não suportam fixar ou desafixar mensagens. ## Como funciona 1. Escolha quais eventos de grupo a YCloud deve enviar para o seu endpoint de webhook. 2. Envie uma solicitação para criar um grupo. A YCloud retorna imediatamente um `requestId`. 3. Aguarde o webhook de ciclo de vida que informa se a criação foi bem-sucedida. 4. Se a criação for bem-sucedida, salve o `groupId` retornado e o link de convite. Armazene e use o `groupId` exatamente como retornado pela YCloud. 5. Envie o link de convite para uma pessoa por vez. 6. Se o grupo exigir aprovação, aprove ou rejeite cada solicitação de entrada. 7. Use os eventos de participante e a API de recuperação de grupo para manter sua lista de membros atualizada. 8. Use eventos de webhook para confirmar a exclusão de grupos, remoção de participantes e alterações de configurações. Uma resposta `200` com `status: "pending"` significa apenas que a YCloud recebeu a solicitação. A operação é concluída posteriormente. Use o evento de webhook correspondente para descobrir se ela foi bem-sucedida. ## Configurar webhooks Inscreva seu endpoint de webhook da YCloud nestes eventos antes de criar um grupo: | Evento | Usado para | | - | - | | `whatsapp.group.lifecycle_update` | Resultados de criação e exclusão de grupos. | | `whatsapp.group.participants_update` | Entradas, solicitações de entrada, remoções, saídas e falhas no nível do participante. | | `whatsapp.group.settings_update` | Resultados de atualização de assunto e descrição. | | `whatsapp.group.status_update` | Eventos de suspensão de grupo e remoção de suspensão. | Quando a YCloud enviar um evento, verifique a `YCloud-Signature`, salve o evento e retorne uma resposta `2xx` prontamente. Em seguida, você pode processá-lo em segundo plano. A YCloud pode enviar o mesmo evento mais de uma vez, e eventos diferentes podem chegar fora de ordem. Use o `id` do evento para reconhecer uma entrega que você já processou. Para uma operação iniciada por meio da API, associe o webhook à solicitação original pelo `requestId`. Ações iniciadas por um participante, como entrar ou sair, podem não incluir um `requestId`. Nesse caso, use o tipo de evento, `groupId`, identificador do participante e horário do evento. ## Criar um grupo Escolha o modo de aprovação de entrada: | Modo | Comportamento | | - | - | | `auto_approve` | Um usuário pode entrar diretamente por meio do link de convite. Este é o padrão. | | `approval_required` | Um usuário envia uma solicitação de entrada que você deve aprovar antes que ele entre. | ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "subject": "New purchase inquiry", "description": "Discuss purchase requirements with our team.", "joinApprovalMode": "approval_required" }' ``` A criação do grupo é concluída de forma assíncrona. A primeira resposta apenas confirma que a YCloud recebeu a solicitação: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "requestId": "REQ_1", "status": "pending" } ``` Aguarde por `whatsapp.group.lifecycle_update`. Um evento `group_create` bem-sucedido contém o `groupId` final e o `inviteLink`. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "evt_group_lifecycle_123", "type": "whatsapp.group.lifecycle_update", "whatsappGroup": { "type": "group_create", "requestId": "REQ_1", "status": "created", "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE", "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK" } } ``` Salve e use o `groupId` exatamente como ele aparece no evento bem-sucedido. Ele diferencia maiúsculas de minúsculas. Não decodifique, modifique nem gere esse valor por conta própria. ## Convidar participantes Você pode usar o link de convite do webhook de criação ou recuperá-lo mais tarde com o endpoint de link de convite. Redefina o link apenas quando precisar que todos os links compartilhados anteriormente parem de funcionar. Após a redefinição, as pessoas não poderão mais entrar usando o link antigo. Para enviar o link pelo WhatsApp, primeiro prepare um modelo de mensagem de convite aprovado. Em seguida, envie esse modelo para um usuário individual: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups/inviteLink/messages \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "to": "+16315552222", "templateName": "group_invite_link", "languageCode": "en_US", "parameters": [ { "type": "group_id", "group_id": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE" } ] }' ``` Este endpoint envia uma mensagem de modelo para a pessoa especificada por `to` ou `recipient`. Ele não envia uma mensagem para o grupo. Se você fornecer ambos os campos, a YCloud usará `to`. ## Gerenciar solicitações de entrada Para um grupo `auto_approve`, aguarde um webhook de participante adicionado antes de registrar o usuário como membro. Para um grupo `approval_required`: 1. Receba `group_join_request_created` ou recupere as solicitações pendentes. 2. Salve o `joinRequestId` enquanto a solicitação ainda estiver pendente. 3. Envie cada ID para o endpoint de aprovação ou rejeição. 4. Verifique os itens bem-sucedidos e com falha na resposta, incluindo `failedJoinRequests` e `errors`. 5. Confirme se a pessoa entrou usando o webhook de participante adicionado ou recuperando o grupo. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups/GROUP_ID/joinRequests/approve \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "joinRequests": ["join-request-id"] }' ``` Um usuário pode revogar uma solicitação pendente. Se uma aprovação falhar porque a solicitação não existe mais, atualize a lista de solicitações pendentes em vez de tentar o mesmo ID indefinidamente. ## Listar grupos e solicitações de entrada A lista de grupos e a lista de solicitações de entrada retornam resultados paginados. Um cursor é um valor temporário que marca sua posição na lista. `limit` controla o tamanho da página, varia de `1` a `1024` e tem como padrão `25`. Passe `after` para a próxima página ou `before` para a página anterior. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --get \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups \ --header "X-API-Key: $YCLOUD_API_KEY" \ --data-urlencode "limit=25" \ --data-urlencode "after=NEXT_CURSOR" ``` Não salve um cursor como um ID permanente. Se ele for inválido ou expirar, recomece a partir da primeira página. ## Enviar uma mensagem para o grupo Use `POST /whatsapp/groupMessages/sendDirectly` para enviar uma mensagem aos membros atuais do grupo. A YCloud recupera o grupo primeiro e fixa o snapshot de destinatários para essa mensagem. Se o grupo tiver oito participantes incluindo o remetente comercial, a YCloud criará sete resultados de membros. As pessoas que entrarem posteriormente não receberão a mensagem anterior e não serão adicionadas ao histórico dela. A resposta de envio confirma o recebimento. Use `GET /whatsapp/groupMessages/{id}` para recuperar o resultado no nível do grupo, o status de entrega de cada membro e os preços finais. O `status` no nível do grupo descreve o resultado geral do envio: aceito pela YCloud, enviado pela Meta ou com falha. Cada item em `recipients` descreve um membro e pode ter um status diferente. A YCloud suporta mensagens `text`, `image`, `video`, `audio`, `document`, `sticker` e `template` compatíveis. Modelos de autenticação e modelos com componentes interativos ou de comércio são rejeitados. Para modelos de marketing, a YCloud pode usar o canal MM Lite quando a WABA for elegível e pelo menos um destinatário tiver um preço MM Lite. Os registros de membros usarão então `group_marketing_lite`. Mensagens de utilidade e de serviço mantêm `group_utility` e `group_service` e não usam MM Lite. Se um membro não tiver preço para o canal selecionado, a YCloud ainda enviará o grupo se for possível disparar para pelo menos um membro. Ela não congela um valor estimado para o membro sem preço e não recorre ao preço do outro canal. O faturamento final usa o preço informado pelo resultado de entrega. ## Gerenciar um grupo ### Remover participantes Você pode remover até oito participantes em uma única solicitação. Remova identificadores de participantes duplicados antes de enviá-la. Alguns participantes podem ser removidos enquanto outros falham, portanto, verifique `removedParticipants`, `failedParticipants[].errors` e o `errors` de nível superior no webhook de participantes. ### Atualizar configurações Você pode atualizar `subject`, `description`, uma `profile_picture_file` JPEG ou qualquer combinação dessas configurações. Envie JSON ao alterar apenas texto. Envie `multipart/form-data` ao fazer upload de uma foto de perfil. A resposta inicial apenas confirma que a YCloud aceitou a solicitação. Aguarde o webhook de configurações e verifique cada entrada em `settings[]` para conferir o que foi realmente atualizado. ### Excluir um grupo A resposta inicial de exclusão não confirma que o grupo foi excluído. Aguarde um webhook de ciclo de vida com `type: "group_delete"` e um `status` final. Após a exclusão, o grupo não poderá ser usado novamente. Eventos que já estavam em andamento ainda podem chegar. ## Gerenciar resultados assíncronos com segurança * Armazene o `requestId`, a operação solicitada e o seu próprio ID de referência juntos. * Se você receber o mesmo evento `id` novamente, não aplique a mesma alteração duas vezes. * Certifique-se de que processar o mesmo evento novamente não crie dados duplicados ou efeitos colaterais. * Esteja preparado para eventos repetidos ou que cheguem fora de ordem. * Recupere o grupo novamente quando um evento entrar em conflito com seus dados atuais. * Verifique erros de nível superior e de nível de item em operações parciais. * Oculte chaves de API, links de convite, identificadores de participantes e dados pessoais dos logs gerais da aplicação. ## Erros e solução de problemas Uma solicitação de API pode falhar imediatamente ou após a YCloud tê-la aceito: * Para uma falha imediata, verifique a resposta de erro padrão da YCloud. O `error.code` de nível superior é um código geral da YCloud, como `BAD_REQUEST` ou `FORBIDDEN`. `error.whatsappApiError` pode conter detalhes adicionais do WhatsApp. Não determine o que sua aplicação deve fazer baseando-se no texto legível por humanos de `message`. * Para uma falha reportada posteriormente, verifique o webhook do grupo. Dependendo da operação, revise `whatsappGroup.errors`, `failedParticipants[].errors` ou `settings[].errors`. | Cenário | Ação recomendada | | - | - | | Grupo não encontrado ou indisponível | Verifique se o `groupId` é exatamente o valor retornado pela YCloud e, em seguida, recupere o estado mais recente do grupo. | | Cursor inválido ou expirado | Reinicie a paginação a partir da primeira página. | | Operação parcialmente bem-sucedida | Processe os itens bem-sucedidos e os com falha separadamente. | | Participantes duplicados | Remova os IDs de participantes duplicados antes de tentar novamente. | | Limite de participantes do grupo atingido | Pare de adicionar participantes e informe que o grupo está cheio. | | Grupo suspenso | Aguarde uma atualização de status ou entre em contato com o suporte. | | Limite de taxa (rate limit) de operações do grupo atingido | Tente novamente com backoff exponencial, jitter e limite de tentativas. | | Limite de grupos do número de telefone atingido | Remova grupos não utilizados ou entre em contato com o suporte. | | Participante não está no grupo | Atualize a lista de membros em vez de repetir a remoção. | | Solicitação de entrada não encontrada | Atualize as solicitações pendentes; ela pode ter sido revogada ou processada. | | Criação de grupos temporariamente restrita | Pare de criar grupos e revise a estratégia recente de envio de mensagens. | | Número de telefone não elegível | Verifique o status de OBA, a integração com a Cloud API e o acesso à YCloud. | Falhas comuns com links de convite também incluem um link redefinido ou expirado, um grupo cheio ou um usuário que foi removido anteriormente pela empresa. Não repita requisições inalteradas indefinidamente. ## Checklist de ponta a ponta Antes de entrar em produção, use um número de telefone de teste elegível para concluir este fluxo completo: 1. Inscreva um endpoint de webhook de teste em todos os quatro tipos de eventos de grupo. 2. Crie um grupo `approval_required` e armazene o `requestId` retornado. 3. Aguarde o evento correspondente `group_create` e armazene seu `groupId` e `inviteLink`. 4. Envie o modelo de mensagem de convite aprovado para um usuário de teste. 5. Faça com que o usuário envie uma solicitação de entrada. 6. Receba ou liste a solicitação e, em seguida, aprove seu `joinRequestId`. 7. Aguarde o evento de participante adicionado. 8. Recupere o grupo e confirme que o participante está presente. 9. Remova o participante de teste e confirme o resultado assíncrono. 10. Exclua o grupo de teste e confirme o evento de ciclo de vida. Os exemplos neste guia seguem o contrato atual da API da YCloud. Conclua este checklist com sucesso antes de usar a integração em produção. ## Referência da API | Operação | Referência | | - | - | | Criar um grupo | [Referência da API](/api-reference/whatsapp-groups/create-a-group) | | Listar grupos | [Referência da API](/api-reference/whatsapp-groups/list-groups) | | Recuperar um grupo | [Referência da API](/api-reference/whatsapp-groups/retrieve-a-group) | | Excluir um grupo | [Referência da API](/api-reference/whatsapp-groups/delete-a-group) | | Recuperar um link de convite | [Referência da API](/api-reference/whatsapp-groups/retrieve-a-group-invite-link) | | Redefinir um link de convite | [Referência da API](/api-reference/whatsapp-groups/reset-a-group-invite-link) | | Enviar uma mensagem com link de convite | [Referência da API](/api-reference/whatsapp-groups/send-a-group-invite-link-message) | | Listar solicitações de entrada | [Referência da API](/api-reference/whatsapp-groups/list-group-join-requests) | | Aprovar solicitações de entrada | [Referência da API](/api-reference/whatsapp-groups/approve-group-join-requests) | | Rejeitar solicitações de entrada | [Referência da API](/api-reference/whatsapp-groups/reject-group-join-requests) | | Remover participantes | [Referência da API](/api-reference/whatsapp-groups/remove-group-participants) | | Atualizar configurações do grupo | [Referência da API](/api-reference/whatsapp-groups/update-group-settings) | | Enviar uma mensagem de grupo diretamente | [Referência da API](/api-reference/whatsapp-group-messages/send-a-group-message-directly) | | Recuperar uma mensagem de grupo | [Referência da API](/api-reference/whatsapp-group-messages/retrieve-a-group-message) | ## Exemplos de Webhook Processe os resultados de criação e exclusão de grupos. Processe entradas, solicitações de entrada, remoções e falhas no nível de participantes. Processe os resultados de atualização de assunto e descrição. Processe eventos de suspensão de grupo e remoção de suspensão. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.