Gerenciar grupos do WhatsApp

O que é

A API de Grupos do WhatsApp da YCloud permite que sua empresa crie grupos do WhatsApp somente por convite. Você envia um link de convite para cada pessoa, e ela escolhe se quer entrar. Se o grupo exigir aprovação, você poderá analisar a solicitação de entrada da pessoa antes de permitir o acesso dela ao grupo. Este guia aborda a configuração e o gerenciamento de grupos. O envio de mensagens para grupos e a recuperação de mensagens de grupos ainda não estão disponíveis. As conversas em grupo não aparecem na Inbox.

Antes de começar

Antes de integrar, verifique se o 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, e não o aplicativo WhatsApp Business.
O número de telefone não usa conversas com múltiplas soluções (Multi-solution Conversations).
Sua conta da YCloud tem acesso ao número de telefone.
Você tem uma URL pública HTTPS para onde a YCloud possa enviar eventos de webhook.
Antes de enviar links de convite por meio de um modelo de mensagem, você deve ter um modelo de convite de grupo aprovado.

A YCloud gerencia as assinaturas necessárias na plataforma do WhatsApp. Você só precisa configurar um endpoint de webhook da YCloud e selecionar os eventos de grupo da YCloud que deseja receber.

A YCloud e o WhatsApp verificam se o número de telefone é elegível. Se não for, verifique seu status de OBA, a configuração da Cloud API e o acesso na YCloud.

Recursos compatíveis e limites

A YCloud oferece suporte atualmente a:

Criação, listagem, recuperação e exclusão de grupos.
Recuperação e redefinição de links de convite.
Envio de um modelo de link de convite aprovado para um usuário individual do WhatsApp.
Listagem, aprovação e rejeição de solicitações de entrada.
Remoção de participantes.
Atualização do assunto e da descrição do grupo.
Atualização da foto de perfil do grupo com um arquivo JPEG.
Recebimento de webhooks de ciclo de vida do grupo, participantes, configurações e suspensão.

A plataforma WhatsApp aplica os seguintes 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 solicitaçã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 são compatíveis com a fixação ou o cancelamento da fixação de mensagens.

Como funciona

Escolha quais eventos de grupo a YCloud deve enviar para o seu endpoint de webhook.
Envie uma solicitação para criar um grupo. A YCloud retorna imediatamente um requestId.
Aguarde o webhook de ciclo de vida que informa se a criação foi bem-sucedida.
Se a criação for bem-sucedida, salve o groupId e o link de convite retornados. Armazene e use o groupId exatamente como retornado pela YCloud.
Envie o link de convite para uma pessoa de cada vez.
Se o grupo exigir aprovação, aprove ou rejeite cada solicitação de entrada.
Use eventos de participantes e a API de recuperação de grupo para manter sua lista de membros atualizada.
Use eventos de webhook para confirmar a exclusão de grupos, a 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 o endpoint de webhook da YCloud nestes eventos antes de criar um grupo:

Evento	Usar 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ções de assunto e descrição.
`whatsapp.group.status_update`	Eventos de suspensão e de liberação de suspensão de grupos.

Quando a YCloud enviar um evento, verifique YCloud-Signature, salve o evento e retorne prontamente uma resposta 2xx. Você pode processá-lo em segundo plano depois. 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 já processada. Para uma operação iniciada por meio da API, associe o webhook à solicitação original usando 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, o identificador do participante e o 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.

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:

{
  "requestId": "REQ_1",
  "status": "pending"
}

Aguarde whatsapp.group.lifecycle_update. Um evento group_create bem-sucedido contém o groupId final e o inviteLink.

{
  "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 groupId exatamente como aparece no evento com êxito. Ele diferencia maiúsculas de minúsculas. Não o decodifique, modifique ou gere 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 uma redefinição, as pessoas não poderão entrar com o link antigo. Para enviar o link pelo WhatsApp, primeiro prepare um modelo de convite aprovado. Em seguida, envie esse modelo para um usuário individual:

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 um modelo de mensagem 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:

Receba group_join_request_created ou recupere as solicitações pendentes.
Salve o joinRequestId enquanto a solicitação ainda estiver pendente.
Envie cada ID para o endpoint de aprovação ou rejeição.
Verifique os itens com sucesso e com falha na resposta, incluindo failedJoinRequests e errors.
Confirme que a pessoa entrou usando o webhook de participante adicionado ou recuperando o grupo.

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 novamente 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 em páginas. 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 o padrão é 25. Passe after para a próxima página ou before para a página anterior.

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 estiver expirado, recomece a partir da primeira página.

Manter 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 participante.

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 carregar 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 de 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 poderão chegar.

Lidar com resultados assíncronos com segurança

Armazene o requestId, a operação solicitada e 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 gere dados duplicados ou efeitos colaterais.
Espere que os eventos sejam repetidos ou 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 decida o que sua aplicação deve fazer fazendo correspondência do texto legível por humanos de message.
Para uma falha informada posteriormente, verifique o webhook do grupo. Dependendo da operação, analise 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 concluída parcialmente	Processe itens com êxito e 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 de operações do grupo atingido	Tente novamente com backoff exponencial, variação aleatória (jitter) e tentativas limitadas.
Limite de grupos por 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 participantes 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 grupo temporariamente restrita	Pare de criar grupos e revise a estratégia recente de envio de mensagens.
Número de telefone não qualificado	Verifique o status da OBA, a integração com a Cloud API e o acesso à YCloud.

Falhas comuns no link de convite também incluem links redefinidos ou expirados, grupos cheios ou usuários removidos anteriormente pela empresa. Não repita solicitações não modificadas indefinidamente.

Checklist de ponta a ponta

Antes de entrar em produção, use um número de telefone de teste qualificado para concluir todo este fluxo:

Inscreva um endpoint de webhook de teste em todos os quatro tipos de eventos de grupo.
Crie um grupo approval_required e armazene o requestId retornado.
Aguarde o evento correspondente group_create e armazene seu groupId e inviteLink.
Envie o modelo de convite aprovado para um usuário de teste.
Peça para o usuário enviar uma solicitação de entrada.
Receba ou liste a solicitação e, em seguida, aprove seu joinRequestId.
Aguarde o evento de participante adicionado.
Recupere o grupo e confirme se o participante está presente.
Remova o participante de teste e confirme o resultado assíncrono.
Exclua o grupo de teste e confirme o evento de ciclo de vida.

Os exemplos deste 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
Listar grupos	Referência da API
Recuperar um grupo	Referência da API
Excluir um grupo	Referência da API
Recuperar um link de convite	Referência da API
Redefinir um link de convite	Referência da API
Enviar uma mensagem com link de convite	Referência da API
Listar solicitações de entrada	Referência da API
Aprovar solicitações de entrada	Referência da API
Rejeitar solicitações de entrada	Referência da API
Remover participantes	Referência da API
Atualizar configurações do grupo	Referência da API

Exemplos de Webhook

Eventos de ciclo de vida

Processe resultados de criação e exclusão de grupos.

Eventos de participante

Processe entradas, solicitações de entrada, remoções e falhas no nível de participante.

Eventos de configurações

Processe resultados de atualização de assunto e descrição.

Eventos de status

Processe eventos de suspensão e remoção de suspensão de grupos.

Primeiros passos

Guias

Endpoints

Webhooks

Gerenciar grupos do WhatsApp

O que é

Antes de começar

Recursos compatíveis e limites

Como funciona

Configurar webhooks

Criar um grupo

Convidar participantes

Gerenciar solicitações de entrada

Listar grupos e solicitações de entrada

Manter um grupo

Remover participantes

Atualizar configurações

Excluir um grupo

Lidar com resultados assíncronos com segurança

Erros e solução de problemas

Checklist de ponta a ponta

Referência da API

Exemplos de Webhook

Eventos de ciclo de vida

Eventos de participante

Eventos de configurações

Eventos de status

​O que é

​Antes de começar

​Recursos compatíveis e limites

​Como funciona

​Configurar webhooks

​Criar um grupo

​Convidar participantes

​Gerenciar solicitações de entrada

​Listar grupos e solicitações de entrada

​Manter um grupo

​Remover participantes

​Atualizar configurações

​Excluir um grupo

​Lidar com resultados assíncronos com segurança

​Erros e solução de problemas

​Checklist de ponta a ponta

​Referência da API

​Exemplos de Webhook

Eventos de ciclo de vida

Eventos de participante

Eventos de configurações

Eventos de status

O que é

Antes de começar

Recursos compatíveis e limites

Como funciona

Configurar webhooks

Criar um grupo

Convidar participantes

Gerenciar solicitações de entrada

Listar grupos e solicitações de entrada

Manter um grupo

Remover participantes

Atualizar configurações

Excluir um grupo

Lidar com resultados assíncronos com segurança

Erros e solução de problemas

Checklist de ponta a ponta

Referência da API

Exemplos de Webhook