Gerenciar grupos do WhatsApp

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

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 retornado e o link de convite. Armazene e use o groupId exatamente como retornado pela YCloud.
Envie o link de convite para uma pessoa por vez.
Se o grupo exigir aprovação, aprove ou rejeite cada solicitação de entrada.
Use os eventos de participante 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, 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.

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 por 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 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:

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:

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 bem-sucedidos e com falha na resposta, incluindo failedJoinRequests e errors.
Confirme se 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 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.

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:

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 mensagem de convite aprovado para um usuário de teste.
Faça com que o usuário envie 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 que 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 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
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
Enviar uma mensagem de grupo diretamente	Referência da API
Recuperar uma mensagem de grupo	Referência da API

Exemplos de Webhook

Eventos de ciclo de vida

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

Eventos de participantes

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

Eventos de configurações

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

Eventos de status

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

Primeiros passos

Guias

Endpoints

Webhooks

Gerenciar grupos do WhatsApp

O que é

Antes de começar

Recursos suportados e limites

Como funciona

Configurar webhooks

Criar um grupo

Convidar participantes

Gerenciar solicitações de entrada

Listar grupos e solicitações de entrada

Enviar uma mensagem para o grupo

Gerenciar um grupo

Remover participantes

Atualizar configurações

Excluir um grupo

Gerenciar 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 participantes

Eventos de configurações

Eventos de status

​O que é

​Antes de começar

​Recursos suportados e limites

​Como funciona

​Configurar webhooks

​Criar um grupo

​Convidar participantes

​Gerenciar solicitações de entrada

​Listar grupos e solicitações de entrada

​Enviar uma mensagem para o grupo

​Gerenciar um grupo

​Remover participantes

​Atualizar configurações

​Excluir um grupo

​Gerenciar 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 participantes

Eventos de configurações

Eventos de status

O que é

Antes de começar

Recursos suportados e limites

Como funciona

Configurar webhooks

Criar um grupo

Convidar participantes

Gerenciar solicitações de entrada

Listar grupos e solicitações de entrada

Enviar uma mensagem para o grupo

Gerenciar um grupo

Remover participantes

Atualizar configurações

Excluir um grupo

Gerenciar resultados assíncronos com segurança

Erros e solução de problemas

Checklist de ponta a ponta

Referência da API

Exemplos de Webhook