Gestionar grupos de WhatsApp

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

Elige qué eventos de grupo debe enviar YCloud a tu endpoint de Webhook.
Envía una solicitud para crear un grupo. YCloud devuelve inmediatamente un requestId.
Espera el Webhook de ciclo de vida que informa si la creación se completó con éxito.
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.
Envía el enlace de invitación a una persona a la vez.
Si el grupo requiere aprobación, aprueba o rechaza cada solicitud de ingreso.
Utiliza los eventos de participantes y la API de recuperación de grupos para mantener tu lista de miembros actualizada.
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.

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:

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

Espera a whatsapp.group.lifecycle_update. Un evento group_create exitoso contiene el groupId final y el 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"
  }
}

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:

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:

Recibe group_join_request_created o recupera las solicitudes pendientes.
Guarda el joinRequestId mientras la solicitud siga pendiente.
Envía cada ID al endpoint de aprobación o rechazo.
Verifica tanto los elementos correctos como los fallidos en la respuesta, incluidos failedJoinRequests y errors.
Confirma que la persona se unió mediante el webhook de participante agregado 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"]
  }'

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.

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:

Suscribe un endpoint de Webhook de prueba a los cuatro tipos de eventos de grupo.
Crea un grupo de approval_required y guarda el requestId devuelto.
Espera el evento coincidente group_create y almacena su groupId y inviteLink.
Envía la plantilla de invitación aprobada a un usuario de prueba.
Haz que el usuario envíe una solicitud de unión.
Recibe o enumera la solicitud y, a continuación, aprueba su joinRequestId.
Espera el evento de participante añadido.
Recupera el grupo y confirma que el participante esté presente.
Elimina al participante de prueba y confirma el resultado asíncrono.
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
Listar grupos	Referencia de la API
Recuperar un grupo	Referencia de la API
Eliminar un grupo	Referencia de la API
Recuperar un enlace de invitación	Referencia de la API
Restablecer un enlace de invitación	Referencia de la API
Enviar un mensaje con enlace de invitación	Referencia de la API
Listar solicitudes de unión	Referencia de la API
Aprobar solicitudes de unión	Referencia de la API
Rechazar solicitudes de unión	Referencia de la API
Eliminar participantes	Referencia de la API
Actualizar configuración del grupo	Referencia de la API
Enviar un mensaje de grupo directamente	Referencia de la API
Recuperar un mensaje de grupo	Referencia de la API

Ejemplos de Webhook

Eventos del ciclo de vida

Gestiona los resultados de la creación y eliminación de grupos.

Eventos de participantes

Gestiona uniones, solicitudes de unión, eliminaciones y fallos a nivel de participante.

Eventos de configuración

Gestiona los resultados de las actualizaciones del asunto y la descripción.

Eventos de estado

Gestiona eventos de suspensión y levantamiento de suspensión de grupos.

Primeros pasos

Guías

Endpoints

Webhooks

Gestionar grupos de WhatsApp

Qué es

Antes de comenzar

Capacidades admitidas y límites

Cómo funciona

Configurar webhooks

Crear un grupo

Invitar a participantes

Gestionar solicitudes de unión

Listar grupos y solicitudes de unión

Enviar un mensaje grupal

Mantener un grupo

Eliminar participantes

Actualizar configuración

Eliminar un grupo

Gestionar resultados asíncronos de forma segura

Errores y resolución de problemas

Lista de comprobación de extremo a extremo

Referencia de la API

Ejemplos de Webhook

Eventos del ciclo de vida

Eventos de participantes

Eventos de configuración

Eventos de estado

​Qué es

​Antes de comenzar

​Capacidades admitidas y límites

​Cómo funciona

​Configurar webhooks

​Crear un grupo

​Invitar a participantes

​Gestionar solicitudes de unión

​Listar grupos y solicitudes de unión

​Enviar un mensaje grupal

​Mantener un grupo

​Eliminar participantes

​Actualizar configuración

​Eliminar un grupo

​Gestionar resultados asíncronos de forma segura

​Errores y resolución de problemas

​Lista de comprobación de extremo a extremo

​Referencia de la API

​Ejemplos de Webhook

Eventos del ciclo de vida

Eventos de participantes

Eventos de configuración

Eventos de estado

Qué es

Antes de comenzar

Capacidades admitidas y límites

Cómo funciona

Configurar webhooks

Crear un grupo

Invitar a participantes

Gestionar solicitudes de unión

Listar grupos y solicitudes de unión

Enviar un mensaje grupal

Mantener un grupo

Eliminar participantes

Actualizar configuración

Eliminar un grupo

Gestionar resultados asíncronos de forma segura

Errores y resolución de problemas

Lista de comprobación de extremo a extremo

Referencia de la API

Ejemplos de Webhook