> ## 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. # Gestionar grupos de WhatsApp > Aprende a crear grupos de WhatsApp solo por invitación, invitar personas, revisar solicitudes para unirse y administrar la configuración del grupo. ## Qué es La API de grupos de WhatsApp de YCloud permite a tu empresa crear grupos de WhatsApp solo por invitación. Envías un enlace de invitación a cada persona y esa persona decide si desea unirse. Si el grupo requiere aprobación, puedes revisar la solicitud de ingreso de la persona antes de permitirle entrar al grupo. Esta guía cubre la configuración del grupo, la gestión y los mensajes salientes del grupo. Las conversaciones de grupo no aparecen en la Bandeja de entrada. ## Antes de comenzar Antes de realizar la integración, asegúrate de que tu número de teléfono comercial de WhatsApp cumpla con estos requisitos: * La empresa tiene una Cuenta comercial oficial (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 Conversaciones multisolución. * Tu cuenta de YCloud tiene acceso al número de teléfono. * Dispones de una URL HTTPS pública donde YCloud puede enviar eventos de Webhook. * Antes de enviar enlaces de invitación a través de un mensaje de plantilla, dispones de una plantilla de invitación a grupo aprobada. YCloud gestiona las suscripciones requeridas a la plataforma de WhatsApp. Solo necesitas [configurar un endpoint de Webhook de YCloud](/es/api-reference/guides/api-fundamentals/configure-webhooks) y seleccionar los eventos de grupo de YCloud que deseas recibir. YCloud y WhatsApp comprueban si el número de teléfono es apto. Si no lo es, verifica su estado de OBA, la configuración de Cloud API y el acceso en YCloud. ## Capacidades admitidas y límites YCloud actualmente admite: * 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 para unirse. * Eliminar participantes. * Actualizar el asunto y la descripción del grupo. * Actualizar la foto de perfil del grupo con un archivo JPEG. * Enviar mensajes de texto, multimedia, stickers y mensajes de plantilla compatibles a un grupo. * Recibir webhooks sobre el ciclo de vida del grupo, participantes, configuraciones y suspensiones. La plataforma de WhatsApp aplica estos límites: * 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 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. Estas API no admiten fijar ni desfijar mensajes. ## 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 completó con éxito. 4. Si la creación se completa con é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 ingreso. 7. Utiliza los eventos de participantes y la API de recuperación de grupos para mantener tu lista de miembros actualizada. 8. Utiliza los eventos de Webhook para confirmar la eliminación de grupos, la expulsión de participantes y los cambios de configuración. Una respuesta `200` con `status: "pending"` solo significa que YCloud recibió la solicitud. La operación finaliza más tarde. Usa el evento de Webhook correspondiente para saber si se completó correctamente. ## Configurar webhooks Suscribe tu endpoint de Webhook de YCloud a estos eventos antes de crear un grupo: | Evento | Úsalo para | | - | - | | `whatsapp.group.lifecycle_update` | Resultados de creación y eliminación de grupos. | | `whatsapp.group.participants_update` | Nuevos miembros, solicitudes para unirse, eliminaciones, salidas y errores a nivel de participante. | | `whatsapp.group.settings_update` | Resultados de actualización de asunto y descripción. | | `whatsapp.group.status_update` | Eventos de suspensión de grupos y levantamiento de suspensión. | Cuando YCloud envíe un evento, verifica `YCloud-Signature`, guarda el evento y devuelve una respuesta `2xx` con prontitud. Luego podrás procesarlo en segundo plano. YCloud puede enviar el mismo evento más de una vez, y distintos eventos pueden llegar desordenados. Utiliza el `id` del evento para reconocer una entrega que ya hayas procesado. Para una operación iniciada a través de la API, relaciona el Webhook con la solicitud original mediante `requestId`. Las acciones iniciadas por un participante, como unirse o salir, podrían no incluir un `requestId`. En ese caso, utiliza el tipo de evento, `groupId`, el identificador del participante y la hora del evento. ## Crear un grupo Elige el modo de aprobación para unirse: | Modo | Comportamiento | | - | - | | `auto_approve` | Un usuario puede unirse directamente a través del enlace de invitación. Esta es la opción predeterminada. | | `approval_required` | Un usuario envía una solicitud para unirse que debes aprobar antes de que pueda entrar. | ```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" }' ``` La creación del grupo finaliza de forma asíncrona. La primera respuesta solo confirma que YCloud recibió la solicitud: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "requestId": "REQ_1", "status": "pending" } ``` Espera a `whatsapp.group.lifecycle_update`. Un evento `group_create` exitoso contiene el `groupId` final y el `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" } } ``` Guarda y utiliza `groupId` exactamente como aparece en el evento exitoso. Distingue entre mayúsculas y minúsculas. No lo decodifiques, modifiques ni generes tú mismo. ## Invitar a participantes Puedes usar el enlace de invitación del webhook de creación o recuperarlo más tarde con el endpoint de enlace de invitación. Restablece el enlace solo cuando necesites que todos los enlaces compartidos anteriormente dejen de funcionar. Después de un restablecimiento, las personas no podrán unirse con el enlace anterior. Para enviar el enlace a través de WhatsApp, primero prepara una plantilla de invitación aprobada. Luego, envía esa plantilla a un usuario 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 envía un mensaje de plantilla a la persona especificada por `to` o `recipient`. No envía un mensaje al grupo. Si proporcionas ambos campos, YCloud utiliza `to`. ## Gestionar solicitudes de unión Para un grupo `auto_approve`, espera un webhook de participante agregado antes de registrar al usuario como miembro. Para un grupo `approval_required`: 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. Verifica tanto los elementos correctos como los fallidos en la respuesta, incluidos `failedJoinRequests` y `errors`. 5. Confirma que la persona se unió mediante el webhook de participante agregado o recuperando el 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"] }' ``` Un usuario puede revocar una solicitud pendiente. Si una aprobación falla porque la solicitud ya no existe, actualiza la lista de solicitudes pendientes en lugar de reintentar el mismo ID indefinidamente. ## Listar grupos y solicitudes de unión La lista de grupos y la lista de solicitudes de unión devuelven resultados paginados. Un cursor es un valor temporal que marca tu posición en la lista. `limit` controla el tamaño de página, varía de `1` a `1024` y su valor predeterminado es `25`. Pasa `after` para la página siguiente o `before` para la 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" ``` No guardes un cursor como ID permanente. Si es inválido o expiró, comienza de nuevo desde la primera página. ## Enviar un mensaje grupal Usa `POST /whatsapp/groupMessages/sendDirectly` para enviar un mensaje a los miembros actuales del grupo. YCloud recupera primero el grupo y fija la instantánea de destinatarios para ese mensaje. Si el grupo tiene ocho participantes, incluido el remitente comercial, YCloud crea siete resultados de miembros. Las personas que se unan más tarde no recibirán el mensaje anterior ni se agregarán a su historial. La respuesta de envío confirma la aceptación. Usa `GET /whatsapp/groupMessages/{id}` para recuperar el resultado a nivel de grupo, el estado de entrega de cada miembro y el precio final. El `status` a nivel de grupo describe el resultado general del envío: aceptado por YCloud, enviado por Meta o fallido. Cada elemento en `recipients` describe a un miembro y puede tener un estado diferente. YCloud admite mensajes `text`, `image`, `video`, `audio`, `document`, `sticker` y `template` compatibles. Las plantillas de autenticación y las plantillas con componentes interactivos o de comercio son rechazadas. Para las plantillas de marketing, YCloud puede usar el canal MM Lite cuando la WABA sea apta y al menos un destinatario tenga un precio de MM Lite. Los registros de miembros usarán entonces `group_marketing_lite`. Los mensajes de utilidad y servicio mantienen `group_utility` y `group_service`, y no usan MM Lite. Si un miembro no tiene precio para el canal seleccionado, YCloud igualmente envía el grupo siempre que se pueda enviar al menos a un miembro. No congela un monto estimado para el miembro sin precio ni recurre al precio del otro canal. La facturación final utiliza el precio reportado por el resultado de entrega. ## Mantener un grupo ### Eliminar participantes Puedes eliminar hasta ocho participantes en una sola solicitud. Elimina los identificadores de participantes duplicados antes de enviarla. Es posible que algunos participantes se eliminen mientras que otros fallen, así que verifica `removedParticipants`, `failedParticipants[].errors` y el `errors` de nivel superior en el webhook de participantes. ### Actualizar configuración Puedes actualizar `subject`, `description`, una imagen JPEG `profile_picture_file` o cualquier combinación de estas configuraciones. Envía JSON cuando solo cambies texto. Envía `multipart/form-data` cuando subas una foto de perfil. La respuesta inicial solo confirma que YCloud aceptó la solicitud. Espera el webhook de configuración y revisa cada entrada de `settings[]` para ver qué se actualizó realmente. ### Eliminar un grupo La respuesta inicial de eliminación no confirma que el grupo haya sido eliminado. Espera un webhook del ciclo de vida con `type: "group_delete"` y un `status` final. Tras la eliminación, el grupo no se puede volver a utilizar. Es posible que sigan llegando eventos que ya estaban en curso. ## Gestionar resultados asíncronos de forma segura * Almacena juntos el `requestId`, la operación solicitada y tu propio ID de referencia. * Si recibes de nuevo el mismo evento `id`, no apliques el mismo cambio dos veces. * Asegúrate de que procesar el mismo evento nuevamente no cree datos duplicados ni efectos secundarios. * Ten en cuenta que los eventos pueden repetirse o llegar fuera de orden. * Recupera el grupo de nuevo cuando un evento entre en conflicto con tus datos actuales. * Revisa los errores de nivel superior y de nivel de elemento para operaciones parciales. * Oculta claves de API, enlaces de invitación, identificadores de participantes y datos personales de los registros generales de la aplicación. ## Errores y resolución de problemas Una solicitud a la API puede fallar inmediatamente o después de que YCloud la haya aceptado: * 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 comparando el texto legible por humanos de `message`. * Para un fallo notificado posteriormente, revisa el Webhook de grupos. Según la operación, revisa `whatsappGroup.errors`, `failedParticipants[].errors` o `settings[].errors`. | Escenario | Acción recomendada | | - | - | | Grupo no encontrado o no disponible | Verifica que el `groupId` sea exactamente el valor devuelto por YCloud y luego recupera el estado más reciente del grupo. | | Cursor inválido o vencido | Reinicia la paginación desde la primera página. | | Operación completada parcialmente | Procesa los elementos correctos y fallidos por separado. | | Participantes duplicados | Elimina los ID de participante duplicados antes de volver a intentarlo. | | Se alcanzó el límite de participantes del grupo | Deja de añadir participantes e informa que el grupo está lleno. | | Grupo suspendido | Espera una actualización de estado o ponte en contacto con el soporte. | | Límite de frecuencia de operaciones del grupo alcanzado | Vuelve a intentarlo con retroceso exponencial, jitter e intentos acotados. | | Se alcanzó el límite de grupos por número de teléfono | Elimina grupos sin usar o ponte en contacto con el soporte. | | El participante no está en el grupo | Actualiza los miembros en lugar de repetir la eliminación. | | Solicitud de unión no encontrada | Actualiza las solicitudes pendientes; es posible que haya sido revocada o procesada. | | Creación de grupos restringida temporalmente | Deja de crear grupos y revisa la estrategia reciente de mensajería. | | Número de teléfono no apto | Verifica el estado de OBA, la incorporación a Cloud API y el acceso a YCloud. | Entre los fallos habituales de los enlaces de invitación también se encuentran enlaces restablecidos o vencidos, un grupo lleno o un usuario que la empresa eliminó con anterioridad. No reintentes indefinidamente solicitudes sin cambios. ## Lista de comprobación de extremo a extremo Antes de pasar a producción, utiliza un número de teléfono de prueba apto para completar este flujo completo: 1. Suscribe un endpoint de Webhook de prueba a los cuatro tipos de eventos de grupo. 2. Crea un grupo de `approval_required` y guarda el `requestId` devuelto. 3. Espera el evento coincidente `group_create` y almacena 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 enumera la solicitud y, a continuación, aprueba su `joinRequestId`. 7. Espera el 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 del ciclo de vida. Los ejemplos de esta guía siguen el contrato de API actual de YCloud. Completa esta lista de comprobación con éxito antes de utilizar la integración en producción. ## Referencia de la API | Operación | Referencia | | - | - | | Crear un grupo | [Referencia de la API](/api-reference/whatsapp-groups/create-a-group) | | Listar grupos | [Referencia de la API](/api-reference/whatsapp-groups/list-groups) | | Recuperar un grupo | [Referencia de la API](/api-reference/whatsapp-groups/retrieve-a-group) | | Eliminar un grupo | [Referencia de la API](/api-reference/whatsapp-groups/delete-a-group) | | Recuperar un enlace de invitación | [Referencia de la API](/api-reference/whatsapp-groups/retrieve-a-group-invite-link) | | Restablecer un enlace de invitación | [Referencia de la API](/api-reference/whatsapp-groups/reset-a-group-invite-link) | | Enviar un mensaje con enlace de invitación | [Referencia de la API](/api-reference/whatsapp-groups/send-a-group-invite-link-message) | | Listar solicitudes de unión | [Referencia de la API](/api-reference/whatsapp-groups/list-group-join-requests) | | Aprobar solicitudes de unión | [Referencia de la API](/api-reference/whatsapp-groups/approve-group-join-requests) | | Rechazar solicitudes de unión | [Referencia de la API](/api-reference/whatsapp-groups/reject-group-join-requests) | | Eliminar participantes | [Referencia de la API](/api-reference/whatsapp-groups/remove-group-participants) | | Actualizar configuración del grupo | [Referencia de la API](/api-reference/whatsapp-groups/update-group-settings) | | Enviar un mensaje de grupo directamente | [Referencia de la API](/api-reference/whatsapp-group-messages/send-a-group-message-directly) | | Recuperar un mensaje de grupo | [Referencia de la API](/api-reference/whatsapp-group-messages/retrieve-a-group-message) | ## Ejemplos de Webhook Gestiona los resultados de la creación y eliminación de grupos. Gestiona uniones, solicitudes de unión, eliminaciones y fallos a nivel de participante. Gestiona los resultados de las actualizaciones del asunto y la descripción. Gestiona eventos de suspensión y levantamiento de suspensión de grupos. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.