Cómo gestionar y automatizar grupos de WhatsApp vía API

Introducción

¿A quién va dirigido?:

• Desarrolladores e ingenieros de software que integran funciones de WhatsApp en sistemas CRM, SaaS o de negocios personalizados;
• Integradores no-code y especialistas en automatización que utilizan Make, Zapier o n8n;

Casos de uso:

• Crear automáticamente grupos dedicados de soporte o de incorporación de clientes;
• Sincronizar las listas de participantes del grupo con los embudos de ventas de CRM;
• Transmitir anuncios y alertas transaccionales en chats grupales;
• Conectar chatbots interactivos a conversaciones grupales;

Requisitos previos:

• Un número de WhatsApp activo estándar (aplicación personal o comercial regular, no WABA oficial);
• Conocimientos básicos de solicitudes HTTP o acceso a una plataforma de automatización no-code;

Qué puedes hacer con Grupos de WhatsApp vía API

• Enviar mensajes a grupos: Envía actualizaciones, anuncios o recordatorios directamente a cualquier grupo.
• Crear nuevos grupos de WhatsApp: Genera grupos automáticamente según eventos como la incorporación de nuevos clientes o inscripciones a cursos.
• Agregar miembros a un grupo: Invita contactos al grupo de forma programática, sin aprobación manual.
• Promover miembros a administradores: Asigna o revoca derechos de administrador a participantes seleccionados.
• Obtener participantes del grupo: Recupera la lista completa de miembros para análisis o sincronización con el CRM.
• Detectar eventos en el grupo: Monitorea mensajes, ingresos y salidas usando webhooks.
• Conectar bots a grupos: Permite que los bots lean y respondan mensajes grupales según la lógica definida.

Por qué la API de grupos oficial de Meta no es viable para la mayoría de las empresas

Cómo vincular tu WhatsApp y empezar a usar la API

1. 1) Ve a tu panel y abre el Canal Predeterminado —ya está creado para ti.
2. 2) En el Paso 1 verás un código QR con instrucciones.
3. 3) En tu teléfono, abre WhatsApp → Configuración → Dispositivos vinculados → Vincular un dispositivo, luego escanea el código QR.
4. 4) Una vez conectado, ponle un nombre a tu canal (por ejemplo, "Mi Chatbot") para identificarlo fácilmente.
5. 5) Serás redirigido a la pantalla de configuración del canal, puedes omitir este paso y volver más tarde.

Ve a la configuración de WhatsApp en tu teléfono

Escanea el código QR en tu WhatsApp

Para conectar tu teléfono, usa el código QR

Tu clave API

Cómo enviar mensajes grupales de WhatsApp vía API (con ejemplos de código)

1. 1) Primero, obtén el ID del grupo. Usa el endpoint GET /groups para obtener una lista de tus grupos de WhatsApp con sus identificadores únicos. Para más detalles, consulta la documentación: Get groups.
2. 2) Una vez que tengas el ID del grupo, puedes enviar un mensaje. Genera grupos automáticamente según eventos como la incorporación de nuevos clientes. Usa el endpoint POST /messages/text, especificando el ID del grupo en el parámetro to y el contenido del mensaje en body. Para más detalles, consulta: Send text message.

1. 1) Al crear un grupo, el ID aparecerá en la respuesta de la API. Más abajo mostramos cómo hacerlo;
2. 2) Endpoint Get a list of groups;
3. 3) Endpoint Get a list of all chats;

                                            
curl --request POST \
     --url https://gate.whapi.cloud/messages/text \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "to": "[email protected]",
  "body": "Hello, this message was sent via API!"
}
'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://gate.whapi.cloud/messages/text', [
  'body' => '{"to":"[email protected]","body":"Hello, this message was sent via API!"}',
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer YOUR_API_TOKEN',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/messages/text"

payload = {
    "to": "[email protected]",
    "body": "Hello, this message was sent via API!"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://gate.whapi.cloud/messages/text',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer YOUR_API_TOKEN'
  },
  data: {to: '[email protected]', body: 'Hello, this message was sent via API!'}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"to\":\"[email protected]\",\"body\":\"Hello, this message was sent via API!\"}");
Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/messages/text")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer YOUR_API_TOKEN")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;

var options = new RestClientOptions("https://gate.whapi.cloud/messages/text");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer YOUR_API_TOKEN");
request.AddJsonBody("{\"to\":\"[email protected]\",\"body\":\"Hello, this message was sent via API!\"}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

Envío de archivos multimedia y documentos a grupos

// Send an image or PDF document to a WhatsApp group
const groupId = "[email protected]";
const res = await fetch('https://gate.whapi.cloud/messages/image', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'content-type': 'application/json',
    'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
  },
  body: JSON.stringify({
    to: groupId,
    media: "https://whapi.cloud/assets/img/whapi/logo-text.svg",
    caption: "Welcome to your automated support channel!"
  })
});
const result = await res.json();
console.log("Media message sent:", result);

Cómo enviar mensajes grupales usando herramientas no-code como Make o n8n

Ejemplo de obtención de ID de grupo en Make (Integromat)

• to: el ID del grupo.
• body: el contenido del mensaje

Ejemplo de envío de mensaje a un grupo vía Make

Ejemplo de petición personalizada para enviar mensaje a un grupo vía Zapier

Cómo crear un grupo de WhatsApp vía API

1. 1) Usa el método POST con el endpoint https://gate.whapi.cloud/groups para crear un nuevo grupo. Proporciona el nombre del grupo en el parámetro subject e incluye al menos un número en el parámetro participants —esto es necesario para crear el grupo exitosamente.
2. 2) Al crearse exitosamente, la API devolverá un ID de grupo. Necesitarás este identificador para enviar mensajes al grupo.
3. 3) Para enviar un mensaje al grupo, usa el método estándar de envío de mensajes. Especifica el ID del grupo en el parámetro to y el contenido en body.

                                            
curl --request POST \
     --url https://gate.whapi.cloud/groups \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Your_Token' \
     --header 'content-type: application/json' \
     --data '
{
  "participants": [
    "498935516106",
    "4915155985667"
  ],
  "subject": "SEO Common GmbH"
}
'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://gate.whapi.cloud/groups', [
  'body' => '{"participants":["498935516106","4915155985667"],"subject":"SEO Common GmbH"}',
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer Your_Token',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/groups"

payload = {
    "participants": ["498935516106", "4915155985667"],
    "subject": "SEO Common GmbH"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer Your_Token"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://gate.whapi.cloud/groups',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer Your_Token'
  },
  data: {participants: ['498935516106', '4915155985667'], subject: 'SEO Common GmbH'}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"participants\":[\"498935516106\",\"4915155985667\"],\"subject\":\"SEO Common GmbH\"}");
Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/groups")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer Your_Token")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;


var options = new RestClientOptions("https://gate.whapi.cloud/groups");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
request.AddJsonBody("{\"participants\":[\"498935516106\",\"4915155985667\"],\"subject\":\"SEO Common GmbH\"}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

Cómo crear un grupo de WhatsApp usando una plataforma no-code

{
  "participants": [
    "498935516106",
    "4915155985667"
  ],
  "subject": "SEO Common GmbH"
}

Ejemplo de petición personalizada para crear grupo vía Make

Cómo agregar participantes a un grupo de WhatsApp

1. 1) Asegúrate de tener el ID del grupo al que deseas agregar miembros. Es un parámetro obligatorio. Arriba explicamos cómo obtener el ID.
2. 2) Envía una petición POST a https://gate.whapi.cloud/groups/{GroupID}/participants para agregar nuevos miembros. Debes incluir el ID del grupo en la URL y proporcionar un array de números de teléfono para los participantes que deseas agregar.

Adición directa vs Enlaces de invitación

                                            
curl --request POST \
     --url https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Your_Token' \
     --header 'content-type: application/json' \
     --data '
{
  "participants": [
    "373983445541",
    "373983445542",
    "373983445543"
  ]
}
'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants', [
  'body' => '{"participants":["373983445541","373983445542","373983445543"]}',
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer Your_Token',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants"

payload = { "participants": ["373983445541", "373983445542", "373983445543"] }
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer Your_Token"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer Your_Token'
  },
  data: {participants: ['373983445541', '373983445542', '373983445543']}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"participants\":[\"373983445541\",\"373983445542\",\"373983445543\"]}");
Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer Your_Token")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;


var options = new RestClientOptions("https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
request.AddJsonBody("{\"participants\":[\"373983445541\",\"373983445542\",\"373983445543\"]}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

Cómo agregar participantes a un grupo usando herramientas no-code

{
  "participants": [
    "373983445541",
    "373983445542",
    "373983445543"
  ]
}

Automatización no-code en el mundo real: creación automática de grupos de soporte (Make y n8n)

1. Crear el grupo: envíe una solicitud POST /groups con un asunto como "Soporte al cliente: Nombre de la empresa" e incluya su número de bot principal.
2. Agregar participantes: llame a POST /groups/{groupId}/participants para agregar el número de teléfono del cliente y su gerente de cuenta asignado.
3. Enviar un mensaje de bienvenida: envíe una solicitud POST /messages/image o POST /messages/text para entregar un PDF de incorporación o un banner de bienvenida.

Cómo obtener los participantes de un grupo de WhatsApp vía API

1. 1) Asegúrate de ser miembro del grupo al que deseas acceder. Sin ser parte del grupo, no podrás obtener la lista de participantes.
2. 2) Usa el método de la API Get Groups para obtener una lista de todos los grupos asociados a tu cuenta de WhatsApp. Si ya conoces el ID del grupo deseado, consúltalo directamente usando el endpoint Get group.
3. 3) La respuesta incluirá un array de objetos grupo, cada uno con información como el ID, nombre y un campo participants con la lista de miembros. Ejemplo de respuesta:

{
  "id": "[email protected]",
  "name": "A group of researchers",
  "participants": [
    { "id": "972558557032", "rank": "member" },
    { "id": "14409416972", "rank": "creator" },
    { "id": "905589461962", "rank": "member" }
  ]
}

                                            
curl --request GET \
     --url 'https://gate.whapi.cloud/groups?count=100' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Your_Token'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://gate.whapi.cloud/groups?count=100', [
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer Your_Token',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/groups?count=100"

headers = {
    "accept": "application/json",
    "authorization": "Bearer Your_Token"
}

response = requests.get(url, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://gate.whapi.cloud/groups?count=100',
  headers: {accept: 'application/json', authorization: 'Bearer Your_Token'}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/groups?count=100")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer Your_Token")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;

var options = new RestClientOptions("https://gate.whapi.cloud/groups?count=100");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

Cómo obtener miembros de un grupo de WhatsApp vía no-code

Cómo conectar un bot a un grupo de WhatsApp

• Crear un bot de WhatsApp en Node.js;
• Crear un bot de WhatsApp en Python;
• Crear un bot de WhatsApp en PHP;
• Crear un bot de WhatsApp en Java;

Consejos, limitaciones y mejores prácticas

• No agregues usuarios a grupos sin su consentimiento. Respeta la privacidad y evita invitaciones no solicitadas;
• Evita enviar spam o contenido no deseado, ya que tu cuenta puede ser marcada o bloqueada permanentemente;
• Whapi.Cloud no impone límites estrictos de velocidad de API en los canales de pago, pero WhatsApp puede marcar las cuentas que envían más de ~20 mensajes por minuto sin historial de calentamiento. Utilice un ritmo similar al humano y retrasos aleatorios de 1.5 a 3.5 segundos entre acciones.

// PATCH https://gate.whapi.cloud/groups/{groupId}/admins
const groupId = "[email protected]";
const res = await fetch(`https://gate.whapi.cloud/groups/${groupId}/admins`, {
  method: 'PATCH',
  headers: {
    'accept': 'application/json',
    'content-type': 'application/json',
    'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
  },
  body: JSON.stringify({
    participants: ["4915155985667"]
  })
});
const status = await res.json();
console.log("Admin promotion status:", status);

Solución de problemas

El bot no responde a mensajes entrantes

El bot envía mensajes sin parar

Devoluciones de llamada de webhook y problemas comunes de automatización de grupos

• Bucle de envío del bot: asegúrese de que su código verifique el indicador from_me en las cargas útiles entrantes para evitar bucles de respuesta infinitos.
• Error de permiso denegado: esto ocurre al intentar agregar un participante mientras la cuenta del bot no es administradora del grupo. Verifique el rango del bot a través de GET /groups/{GroupID}.
• Falta de números en la lista: la sincronización de metadatos del grupo tarda hasta 15 segundos. Si llama a la API inmediatamente después de la creación, los números de teléfono de los participantes pueden tardar unos momentos en resolverse.

¿No puedes agregar un usuario al grupo?

• Debes ser administrador del grupo. Solo los admins pueden agregar nuevos miembros.
• El usuario puede tener restringidas las invitaciones a grupos en su configuración de privacidad. Si es así, no se puede agregar automáticamente vía API.
• El grupo puede haber alcanzado el tamaño máximo de 1024 participantes. En ese caso, elimina miembros inactivos o considera crear un nuevo grupo.
• Las políticas anti-spam de WhatsApp pueden bloquear la adición de ciertos números a los grupos, especialmente si el contacto no está guardado en tu libreta de direcciones o no ha interactuado contigo. Para reducir este riesgo, recomendamos encarecidamente agregar primero el contacto a tu lista mediante nuestra API de adición de contactos.

¿Mensaje no entregado?

• Verifica el ID del grupo —IDs incorrectos o expirados causarán fallos de entrega.
• Si el mensaje se envía pero no aparece en el grupo, revisa el formato. Por ejemplo, los grupos de WhatsApp pueden no mostrar ciertos tipos de contenido, como imágenes webp o botones interactivos.

¿Permiso denegado?

• Tu número no es reconocido como administrador del grupo.
• La API puede no haber sincronizado correctamente tu estado de admin o número. En ese caso, intenta reautorizar tu canal API para refrescar permisos y metadatos.

¿No se muestran los miembros del grupo?

¿Qué significa @lid en la lista de participantes?

// GET https://gate.whapi.cloud/contacts/ids/{contactLid}
const contactLid = "1524746986546@lid";
const res = await fetch(`https://gate.whapi.cloud/contacts/ids/${contactLid}`, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
  }
});
const { phone } = await res.json();
console.log("Resolved JID phone number:", phone);

Despliegue y uso de servidores

Firebase

AWS (Amazon Web Services)

Heroku

Resumen y próximos pasos