Enviar a un grupo de WhatsApp

Un envío a grupo es un POST /v1/whatsapp/messages normal cuyo to nombra un grupo en lugar de una persona: una solicitud, un mensaje, y cada participante de ese chat grupal lo recibe y puede responder donde los demás lo ven. Lo que cambia es el reporte. El mensaje lleva contadores de cuántos lo recibieron, y la entrega se confirma un participante a la vez.

Crear y administrar un grupo es independiente de enviarle mensajes. Gestión de grupos de WhatsApp cubre cómo crear uno a través de la API y compartir su enlace de invitación, y Grupos de WhatsApp cubre para qué sirve un grupo y los límites que WhatsApp impone.

Requisitos previos

Necesitas una clave de API con permiso de escritura de WhatsApp y el ID de un grupo Active (wag_…). Cópialo desde la pestaña Details del grupo en la página de Groups, léelo de to.group_id en un mensaje que llegó a través del grupo, o lista tus grupos.

Reemplaza el ID de grupo de ejemplo con el tuyo. Inicializa el cliente para tu lenguaje usando la guía de SDK de TypeScript, Python, Go o PHP. Para ejemplos de CLI, instala y autentica el CLI con acceso de escritura de WhatsApp. Usa el host API de tu región del espacio de trabajo en las solicitudes cURL.

1. Envía el mensaje

Pon el ID del grupo en to y omite from. Un grupo está vinculado al número de negocio con el que fue creado, así que ese número es el único por el que puede salir el mensaje; indicar un remitente devuelve una E15018 422.

const msg = await bird.whatsapp.send({
  to: "wag_01krdgeqcxet5s7t44vh8rt9mg",
  text: { body: "The route sheet for Tuesday is up." },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="wag_01krdgeqcxet5s7t44vh8rt9mg",
    text={"body": "The route sheet for Tuesday is up."},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:   "wag_01krdgeqcxet5s7t44vh8rt9mg",
	Text: &bird.WhatsAppTextSend{Body: "The route sheet for Tuesday is up."},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$text = (new WhatsAppMessageSendRequestText())
    ->setBody("The route sheet for Tuesday is up.");
$message = $bird->whatsapp->send(
    to: 'wag_01krdgeqcxet5s7t44vh8rt9mg',
    text: $text,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --text 'The route sheet for Tuesday is up.' \
  --to wag_01krdgeqcxet5s7t44vh8rt9mg

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "wag_01krdgeqcxet5s7t44vh8rt9mg",
      "text": { "body": "The route sheet for Tuesday is up." }
    }'

La API devuelve 202 con el grupo reflejado en to.group_id, status: accepted y recipient_count: cuántas personas había en el grupo cuando se aceptó el envío. Ese conteo es el denominador para todo en el paso 3, y queda fijo en ese momento. Alguien que se una por el enlace de invitación mientras el mensaje está en tránsito no lo recibe y no cambia el conteo.

2. Qué acepta un grupo

Un grupo acepta texto, imágenes, video, audio, stickers, documentos, una ubicación, tarjetas de contacto y una plantilla creada en tu espacio de trabajo en cualquier categoría excepto autenticación. Dos tipos de contenido se rechazan con una E15052 422, antes de que el mensaje se cree o se cobre, porque WhatsApp no entrega ninguno de los dos a un chat grupal:

• Cualquier elemento interactivo: botones de respuesta, menús de lista, botones de enlace, carruseles, y las solicitudes de ubicación e información de contacto.
• Una plantilla de autenticación. Envía el código de verificación de un solo uso directamente al participante.

Una plantilla gestionada por Bird se envía desde un número propiedad de Bird, que nunca es el número al que está vinculado un grupo, así que dirigir una a un grupo devuelve una E15001 422.

El contenido de formato libre aún necesita una ventana de servicio al cliente abierta, y un grupo tiene la suya propia: cualquier participante que escriba al grupo abre una sola ventana de 24 horas para todo el grupo, y que esa persona te escriba fuera del grupo no la abre. Cuando la ventana expira, lo que llega al grupo es una plantilla.

3. Sigue la distribución

Recupera el mensaje para ver hasta dónde ha llegado. Tres contadores reportan la distribución:

En un mensaje de grupo, status reporta el punto más avanzado que todos los destinatarios han alcanzado: cambia a delivered solo cuando delivered_count es igual a recipient_count, y permanece en sent mientras algunos han confirmado y otros no. Ningún mensaje de WhatsApp tiene un estado read, así que la lectura se refleja en read_count y read_at. delivered_at y read_at son los del primer destinatario, no los del último. failed y rejected nunca son por participante, porque hay una sola entrega a WhatsApp y una sola forma de que sea rechazada.

Un envío a un grupo al que nadie se había unido no lleva contadores en absoluto, ya que no hay denominador que reportar, así que usa to.group_id en lugar de los contadores para distinguir un mensaje de grupo de uno individual.

Para ver a qué participante corresponde una confirmación, lista los eventos del mensaje. Un envío a grupo se despliega en como máximo un whatsapp.delivered y como máximo un whatsapp.read por participante, cada uno con recipient que contiene el número de teléfono de esa persona, su ID de usuario con alcance de negocio, o ambos. Ninguno está garantizado para nadie: WhatsApp omite el acuse de entrega de un participante que ya está viendo el chat, y un acuse de lectura llega solo si abre el mensaje. Cuenta lo que llega en lugar de esperar uno de cada tipo por participante, y consulta los contadores para los totales. El único evento whatsapp.sent no lleva recipient: es la única entrega a WhatsApp, que no nombra a nadie. Los webhooks whatsapp.delivered y whatsapp.read llevan el mismo campo, que es como distingues callbacks que de otro modo serían idénticos.

4. Lee la conversación de un grupo

Pasa group_id a listar mensajes para el hilo de un grupo, en ambas direcciones:

for await (const msg of bird.whatsapp.list({ group_id: "wag_01krdgeqcxet5s7t44vh8rt9mg" })) {
  console.log(msg.id, msg.direction, msg.status);
}

for msg in client.whatsapp.list(group_id="wag_01krdgeqcxet5s7t44vh8rt9mg"):
    print(msg.id, msg.direction, msg.status)

for msg, err := range client.Whatsapp.List(context.Background(), bird.WhatsappListParams{
	GroupID: "wag_01krdgeqcxet5s7t44vh8rt9mg",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Direction, *msg.Status)
}

foreach ($bird->whatsapp->list(['group_id' => 'wag_01krdgeqcxet5s7t44vh8rt9mg']) as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird whatsapp list --group-id wag_01krdgeqcxet5s7t44vh8rt9mg

curl "https://us1.platform.bird.com/v1/whatsapp/messages?group_id=wag_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Un mensaje entrante de grupo se lee con el participante que lo escribió en from, y un to que lleva tanto tu número de negocio como group_id: el número que lo recibió, calificado por el grupo a través del cual llegó. Ni to ni from coinciden con un grupo, así que group_id es el único filtro que limita la lista a un solo grupo. Los mismos mensajes están en el registro de WhatsApp en el dashboard.

Costo

Un envío a grupo se cobra en los dos componentes que describe Enviar mensajes de WhatsApp, con una diferencia en cómo se tarifica cada uno. La tarifa de Bird se cobra una vez por el envío y se basa en el país del número de negocio por el que salió, porque un grupo puede abarcar varios países y no tiene un solo país de destino. La parte de Meta se acumula por participante al que el mensaje llegó, cada uno tarifado a la tarifa individual normal del país de ese participante, así que passthrough_amount crece a medida que llegan sus acuses. A partir del 1 de octubre de 2026, esa parte también cubre el contenido de formato libre enviado al grupo, que Meta cobra por participante alcanzado y descuenta de los 1000 mensajes de servicio gratuitos al mes del número emisor: Cambios de precios de octubre de 2026.

Solución de problemas

• 404 (E15046): El ID de grupo no corresponde a ningún grupo de este espacio de trabajo. Un grupo pertenece al espacio de trabajo que lo creó, así que un ID de otro espacio de trabajo no se encuentra aquí.
• 409 (E15047): El grupo está pendiente, suspendido, eliminado o fallido. Solo se puede enviar a un grupo Active, y un grupo permanece pendiente hasta que WhatsApp lo confirma.
• 422 (E15018): Elimina from. El grupo envía con el número con el que fue creado.
• 422 (E15052): Contenido interactivo o una plantilla de autenticación. Consulta qué acepta un grupo.
• 422 (E15044): La ventana de servicio del grupo está cerrada. Envía una plantilla, o espera a que un participante escriba al grupo.
• status atascado en sent: Menos de recipient_count participantes han confirmado la entrega. Lee los eventos del mensaje para ver quién falta.

Próximos pasos

• Recibir mensajes de grupo de WhatsApp: identifica al remitente y responde al grupo
• Gestionar grupos de WhatsApp: administra participantes, enlaces de invitación y solicitudes de unión
• Webhooks de estado de mensajes: recibe actualizaciones de entrega de tus mensajes
• IDs de usuario con alcance de negocio: identifica a un participante cuyo número de teléfono no tienes