Gestionar grupos de WhatsApp

​

Qué es

​

Antes de empezar

• La empresa tiene una Official Business Account (OBA).
• El número de teléfono utiliza la WhatsApp Cloud API, no la aplicación WhatsApp Business.
• El número de teléfono no utiliza Multi-solution Conversations.
• Tu cuenta de YCloud tiene acceso al número de teléfono.
• Dispones de una URL pública HTTPS donde YCloud pueda enviar eventos de webhook.
• Antes de enviar enlaces de invitación a través de un mensaje de plantilla, dispones de una plantilla de mensaje de invitación al grupo aprobada.

​

Funcionalidades admitidas y límites

• Crear, listar, recuperar y eliminar grupos.
• Recuperar y restablecer enlaces de invitación.
• Enviar una plantilla aprobada de enlace de invitación a un usuario individual de WhatsApp.
• Listar, aprobar y rechazar solicitudes de unión.
• Eliminar participantes.
• Actualizar el asunto y la descripción del grupo.
• Actualizar la foto de perfil del grupo con un archivo JPEG.
• Recibir webhooks sobre el ciclo de vida del grupo, participantes, configuración y suspensión.

• Un grupo puede tener hasta 8 participantes.
• Un número de teléfono comercial puede crear hasta 10.000 grupos.
• Un grupo solo puede contener un número de teléfono comercial de la Cloud API.
• Una sola solicitud de YCloud puede eliminar hasta 8 participantes.
• El asunto de un grupo puede contener hasta 128 caracteres.
• La descripción de un grupo puede contener hasta 2.048 caracteres.

​

Cómo funciona

1. Elige qué eventos de grupo debe enviar YCloud a tu endpoint de webhook.
2. Envía una solicitud para crear un grupo. YCloud devuelve inmediatamente un requestId.
3. Espera el webhook de ciclo de vida que informa si la creación se realizó con éxito.
4. Si la creación tiene éxito, guarda el groupId devuelto y el enlace de invitación. Almacena y utiliza el groupId exactamente como lo devuelve YCloud.
5. Envía el enlace de invitación a una persona a la vez.
6. Si el grupo requiere aprobación, aprueba o rechaza cada solicitud de unión.
7. Usa los eventos de participantes y la API para recuperar grupos para mantener tu lista de miembros actualizada.
8. Usa eventos de webhook para confirmar la eliminación de grupos, la salida de participantes y los cambios de configuración.

​

Configurar webhooks

​

Crear un grupo

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"
  }'

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

{
  "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"
  }
}

​

Invitar a participantes

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"
      }
    ]
  }'

​

Gestionar solicitudes de unión

1. Recibe group_join_request_created o recupera las solicitudes pendientes.
2. Guarda el joinRequestId mientras la solicitud siga pendiente.
3. Envía cada ID al endpoint de aprobación o rechazo.
4. Comprueba tanto los elementos exitosos como los fallidos en la respuesta, incluidos failedJoinRequests y errors.
5. Confirma que la persona se unió utilizando el webhook de participante añadido o recuperando el 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"]
  }'

​

Listar grupos y solicitudes de unión

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"

​

Mantener un grupo

​

Eliminar participantes

​

Actualizar la configuración

​

Eliminar un grupo

​

Gestionar resultados asíncronos de forma segura

• Guarda el requestId, la operación solicitada y tu propio ID de referencia juntos.
• Si vuelves a recibir el mismo id del evento, no apliques el mismo cambio dos veces.
• Asegúrate de que procesar el mismo evento de nuevo no genere datos duplicados ni efectos secundarios.
• Espera que los eventos puedan repetirse o llegar fuera de orden.
• Recupera el grupo nuevamente cuando un evento entre en conflicto con tus datos actuales.
• Comprueba los errores de nivel superior y a nivel de elemento para operaciones parciales.
• Oculta las claves de API, enlaces de invitación, identificadores de participantes y datos personales de los registros generales de la aplicación.

​

Errores y solución de problemas

• Para un fallo inmediato, consulta la respuesta de error estándar de YCloud. El error.code de nivel superior es un código general de YCloud como BAD_REQUEST o FORBIDDEN. error.whatsappApiError puede contener detalles adicionales de WhatsApp. No decidas qué debe hacer tu aplicación basándote en el texto legible por humanos de message.
• Para un fallo reportado más adelante, revisa el webhook del grupo. Dependiendo de la operación, revisa whatsappGroup.errors, failedParticipants[].errors o settings[].errors.

​

Lista de comprobación de extremo a extremo

1. Suscribe un endpoint de webhook de prueba a los cuatro tipos de eventos de grupo.
2. Crea un grupo approval_required y guarda el requestId devuelto.
3. Espera al evento group_create coincidente y guarda su groupId y inviteLink.
4. Envía la plantilla de invitación aprobada a un usuario de prueba.
5. Haz que el usuario envíe una solicitud de unión.
6. Recibe o lista la solicitud y, a continuación, aprueba su joinRequestId.
7. Espera al evento de participante añadido.
8. Recupera el grupo y confirma que el participante esté presente.
9. Elimina al participante de prueba y confirma el resultado asíncrono.
10. Elimina el grupo de prueba y confirma el evento de ciclo de vida.

​

Referencia de la API

​

Ejemplos de webhook