Resumen
Utilice la API de Grupos de WhatsApp para crear y gestionar grupos de WhatsApp de forma programática. Puede crear grupos, enviar invitaciones a contactos pendientes, eliminar participantes, borrar grupos y obtener una lista de grupos activos.
Nota: La API de Grupos de WhatsApp está disponible en el plan Business.
Instrucciones
Antes de empezar
Antes de utilizar la API de Grupos de WhatsApp:
Asegúrese de que su cuenta de Wati esté en el plan Business.
Genere un token de API de Wati y manténgalo seguro.
Utilice la URL base de la API proporcionada en la documentación de la API de Wati.
Para obtener más información, consulte Autenticación. Las API de Wati utilizan autenticación mediante Bearer Token, y las solicitudes deben incluir el token de API en el encabezado Authorization.
Autenticación
Incluya los siguientes encabezados en sus solicitudes de API:
Authorization: Bearer <su_token_de_api>
Content-Type: application/json
Por ejemplo:
curl --location 'https://live-mt-server.wati.io/xxxxxx/api/ext/v3/conversations/groups' \
--header 'Authorization: Bearer <su_token_de_api>' \
--header 'Content-Type: application/json'
Nota: Utilice la URL base de la API que se muestra en su cuenta de Wati (Connectors > API Docs > API Endpoint) en lugar de la URL de ejemplo anterior.
Seguridad: Nunca comparta su token de API ni lo suba a código público. Wati recomienda almacenar las credenciales de la API en variables de entorno o en un gestor de secretos.
Endpoints disponibles
Método | Endpoint | Descripción |
|
| Crear un grupo de WhatsApp |
|
| Eliminar un grupo de WhatsApp |
|
| Enviar invitaciones a contactos pendientes |
|
| Eliminar participantes de un grupo |
|
| Listar grupos de WhatsApp activos |
1. Crear un grupo de WhatsApp
POST /api/ext/v3/conversations/groups
Crea un nuevo grupo de WhatsApp.
Puede especificar opcionalmente un canal. Si no lo hace, se utilizará el canal predeterminado. Los operadores se identifican por su dirección de correo electrónico, mientras que los contactos se identifican por número de teléfono o destino de contacto admitido.
Cuerpo de la solicitud
{
"channel": "MyChannel",
"name": "VIP Support Group",
"description": "Group for VIP customers",
"owner_email": "[email protected]",
"operator_emails": [
"[email protected]"
],
"contact_targets": [
"14155551234",
"14155555678"
],
"join_approval_mode": "auto_approve"
}Parámetros del cuerpo de la solicitud
Campo | Tipo | Descripción |
| string | El canal a utilizar. Si se omite, se utiliza el canal predeterminado. |
| string | El nombre del grupo de WhatsApp. |
| string | La descripción del grupo de WhatsApp. |
| string | Dirección de correo electrónico del propietario del grupo. |
| array | Direcciones de correo electrónico de los operadores a añadir al grupo. |
| array | Número de teléfono, BSUID o ContactId de los contactos a añadir al grupo. Máximo 7 contactos por grupo. |
| string | Especifica el modo de aprobación para unirse al grupo. |
Respuesta
Una solicitud exitosa devuelve 201 Created y los detalles del grupo recién creado.
{
"group": {
"id": "6828abc123def456789012ab",
"name": "VIP Support Group",
"description": "Group for VIP customers",
"invite_link": "",
"channel_id": "ch_123",
"conversation_id": "conv_456",
"operators": [
{
"id": "682800000000000000000001",
"operator_id": "op_id",
"name": "Owner Name",
"role": "owner",
"added_at": "2026-08-13T08:27:00.8447035Z"
}
],
"contacts": [
{
"id": "682800000000000000000003",
"contact_id": "contact_id",
"wa_id": "+14155551234",
"name": "Contact Name",
"join_status": "pending"
}
],
"created_at": "2026-08-13T08:27:00.8448051Z"
}
}Códigos de respuesta
Código | Descripción |
| El grupo se creó correctamente. |
| La solicitud no es válida. |
| La solicitud no está autorizada. |
| La solicitud está prohibida. |
| Demasiadas solicitudes. |
| Ocurrió un error inesperado. |
2. Eliminar un grupo de WhatsApp
DELETE /api/ext/v3/conversations/groups/{groupId}
Elimina el grupo de WhatsApp especificado.
Si el grupo ya ha sido eliminado, el endpoint sigue devolviendo 200 OK.
Parámetros de ruta
Parámetro | Tipo | Requerido | Descripción |
| string | Sí | El ID del grupo a eliminar. |
Respuesta
Una solicitud exitosa devuelve 200 OK.
{
"result": true
}Códigos de respuesta
Código | Descripción |
| El grupo se eliminó correctamente. |
| La solicitud no es válida. |
| La solicitud no está autorizada. |
| La solicitud está prohibida. |
| Demasiadas solicitudes. |
| Ocurrió un error inesperado. |
3. Enviar invitaciones de grupo
POST /api/ext/v3/conversations/groups/{groupId}/invites
Envía una invitación de grupo a todos los contactos que aún están pendientes.
La API verifica los contactos en el grupo, identifica aquellos con un estado de unión pendiente y envía la plantilla de invitación de grupo a la conversación 1:1 de cada contacto.
Parámetros de ruta
Parámetro | Tipo | Requerido | Descripción |
| string | Sí | El ID del grupo para el que se enviarán las invitaciones. |
Respuesta
Una solicitud exitosa devuelve el resultado de la invitación para cada contacto pendiente.
{
"total_pending": 3,
"sent": 2,
"failed": 1,
"results": [
{
"contact_name": "Alice",
"phone": "14155551234",
"success": true
},
{
"contact_name": "Bob",
"phone": "14155555678",
"success": true
},
{
"contact_name": "Charlie",
"phone": "",
"success": false,
"error": "BSUID-only contact, no phone number"
}
]
}La respuesta incluye:total_pending: Número de contactos con estado de unión pendiente.sent: Número de invitaciones enviadas correctamente.failed: Número de invitaciones que no pudieron ser enviadas.results: Resultado de la invitación para cada contacto pendiente.
Códigos de respuesta
Código | Descripción |
| Los resultados de la invitación fueron devueltos correctamente. |
| La solicitud no es válida. |
| La solicitud no está autorizada. |
| La solicitud está prohibida. |
| Demasiadas solicitudes. |
| Ocurrió un error inesperado. |
4. Eliminar participantes de un grupo de WhatsApp
DELETE /api/ext/v3/conversations/groups/{groupId}/participants
Elimina operadores y/o contactos de un grupo de WhatsApp.
Debe proporcionar al menos un correo electrónico de operador o un destino de contacto.
Parámetros de ruta
Parámetro | Tipo | Requerido | Descripción |
| string | Sí | El ID del grupo del que se eliminarán los participantes. |
Cuerpo de la solicitud
{
"operator_emails": [
"[email protected]"
],
"contact_targets": [
"14155551234"
]
}Parámetros del cuerpo de la solicitud
Campo | Tipo | Descripción |
| array | Direcciones de correo electrónico de los operadores a eliminar del grupo. |
| array | Número de teléfono, BSUID o ContactId de los contactos a añadir al grupo. Máximo 7 contactos por grupo. |
Puede proporcionar operator_emails, contact_targets, o ambos. Se debe proporcionar al menos uno.
Respuesta
Una solicitud exitosa devuelve 200 OK.
{
"result": true
}Códigos de respuesta
Código | Descripción |
| Los participantes se eliminaron correctamente. |
| La solicitud no es válida. |
| La solicitud no está autorizada. |
| La solicitud está prohibida. |
| Demasiadas solicitudes. |
| Ocurrió un error inesperado. |
5. Listar grupos de WhatsApp activos
POST /api/ext/v3/conversations/groups/list
Devuelve una lista paginada por cursor de grupos de WhatsApp activos.
Puede filtrar opcionalmente los resultados por canal o por IDs de grupo específicos. Si no especifica un canal, se utiliza el canal predeterminado.
Cuerpo de la solicitud
{
"channel": "MyChannel",
"limit": 20
}Parámetros del cuerpo de la solicitud
Campo | Tipo | Descripción |
| string | El canal a utilizar. Si se omite, se utiliza el canal predeterminado. |
| integer | El número de grupos a devolver en la respuesta. |
Respuesta
Una solicitud exitosa devuelve 200 OK con los grupos activos e información de paginación.
{
"groups": [
{
"id": "6828abc123def456789012ab",
"name": "VIP Support Group",
"description": "Group for VIP customers",
"invite_link": "https://chat.whatsapp.com/abc123",
"channel_id": "ch_123",
"conversation_id": "conv_456",
"operators": [
{
"id": "682800000000000000000001",
"operator_id": "op_id",
"name": "Owner",
"role": "owner",
"added_at": "2026-08-13T08:27:00.8595387Z"
}
],
"contacts": [
{
"id": "682800000000000000000003",
"contact_id": "contact_id",
"wa_id": "+14155551234",
"name": "Alice",
"join_status": "joined",
"joined_at": "2026-08-13T08:27:00.8595402Z"
}
],
"created_at": "2026-08-13T08:27:00.8595404Z"
}
],
"continuous_token": "eyJsIjoiNjgyOGFiYzEyM2RlZjQ1Njc4OTAxMmFiIn0=",
"total": 5
}Paginación
El endpoint List Groups devuelve resultados en páginas.
Si hay más grupos disponibles, la respuesta incluye un continuous_token. Utilice este token para recuperar páginas posteriores.
Cuando continuous_token está ausente o es null, no hay más resultados.
Códigos de respuesta
Código | Descripción |
| La lista de grupos activos fue devuelta correctamente. |
| La solicitud no es válida. |
| La solicitud no está autorizada. |
| La solicitud está prohibida. |
| Demasiadas solicitudes. |
| Ocurrió un error inesperado. |
Respuestas de error
Los siguientes códigos de estado HTTP pueden ser devueltos por los endpoints de la API de Grupos de WhatsApp:
Código | Descripción |
| La solicitud no es válida. |
| La solicitud no está autorizada. |
| La solicitud está prohibida. |
| Demasiadas solicitudes. |
| Ocurrió un error inesperado. |
Para las respuestas 400, 403 y 500, la API puede devolver detalles adicionales como un código de error, un mensaje y una marca de tiempo.
Ejemplo de respuesta de error
{
"details": "string",
"code": 0,
"message": "string",
"timestamp": "2026-08-13T09:01:03.204Z"
}Para errores relacionados con la autenticación, verifique que su solicitud incluya un token de API válido en el encabezado Authorization. Consulte Autenticación para obtener más información.