WhatsApp Business API para difusión de equipo — crear grupo de whatsapp

Descripción del caso de uso

Este escenario usa la API groups con operación create para aprovisionar un grupo de WhatsApp nombrado para difusiones de equipo. No se requiere ventana de sesión de 24 horas porque la llamada es una acción de gestión de canal.

Ejemplo de plantilla

Grupo interno creado para difusión de ventas — comparte el enlace de invitación con tu equipo.

La creación de grupo es una llamada API de gestión — no un mensaje de sesión; webhook está deshabilitado para este perfil.

Cuándo usarlo

• difusión interna de ventas

Valor para el negocio

• Team setup event fires from CRM or internal admin workflow
• groups create provisions Sales team Q1 with internal broadcast description
• Invite link is retrieved and stored for distribution
• Managers join the WhatsApp group via the invite URL
• Broadcast campaigns can target the group from approved tooling

Flujo de trabajo

1. Un evento de admin o CRM dispara el aprovisionamiento del grupo de equipo.
2. groups create establece el nombre del grupo y la descripción de difusión interna.
3. La API devuelve metadatos del grupo incluyendo el enlace de invitación.
4. Tu sistema comparte la URL de invitación con miembros autorizados del equipo.
5. El progreso de entrega se reporta de forma asíncrona — típicamente sent, luego delivered (o failed/undelivered).
6. Tu sistema recibe el estado vía webhook (hooks[]) o consulta el estado de entrega y maneja fallos si es necesario.

Implementación técnica

Requisitos previos

• Canal 1MSG con permisos de gestión de groups.
• Workflow de backend para almacenar y distribuir de forma segura el enlace de invitación devuelto.

Ejemplos de código

#!/usr/bin/env node

// === Configuration (replace "___" placeholders) ===
const API_BASE_URL = "https://api.1msg.io"; // production 1MSG API base URL
const CHANNEL_ID = "___";                   // channel ID from 1MSG dashboard
const API_TOKEN = "___";                    // channel JWT token (Bearer)



async function createWhatsAppGroup() {
  const url = `${API_BASE_URL}/${CHANNEL_ID}/groups`;
  const requestBody = {
    groupName: "Sales team Q1",
    description: "Internal broadcast",
  };

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_TOKEN}`,
    },
    body: JSON.stringify(requestBody),
  });

  const raw = await res.text();
  let data;
  try {
    data = JSON.parse(raw);
  } catch {
    data = null;
  }

  if (!res.ok || !data || data.created !== true) {
    console.error("Send failed.");
    console.error(raw);
    process.exit(1);
  }

  console.log("API response:", raw);
  return data;
}

if (require.main === module) {
  createWhatsAppGroup().catch((err) => {
    console.error("Execution failed:", err.message);
    process.exit(1);
  });
}

module.exports = { createWhatsAppGroup };

Respuesta inmediata de la API (síncrona)

• HTTP 2xx y JSON "sent": true significan que 1MSG aceptó el mensaje para envío — no que ya llegó al teléfono del cliente.
• Guarda el campo `id` de la respuesta (valor tipo wamid.…). Úsalo para correlacionar callbacks de entrega o polling.
• La respuesta también puede incluir message y description — solo informativos.

Estado de entrega (asíncrono)

• Registra un webhook (POST …/webhook) para que 1MSG envíe actualizaciones de entrega a tu endpoint HTTPS en un payload `hooks[]` separado (sent, delivered, read, o failed/undelivered cuando aplique).
• Opcionalmente consulta: GET {base}/{channel}/hookInfo?messageId=<id de sendTemplate>.
• En la práctica, la entrega suele completarse en pocos segundos — pero eso no está garantizado por el contrato de la API.

Errores frecuentes

• Ventana de sesión cerrada (sin mensaje del cliente en 24 horas)
• Número de teléfono inválido o no normalizado
• Cuerpo del mensaje / URL de media ausente o inválida
• Fallo de entrega — revisa el webhook de estado y la política de reintentos

Preguntas frecuentes

• ¿Necesito una plantilla? No — este escenario usa un mensaje de sesión dentro de la ventana de atención de 24 horas.
• ¿Cuándo se cierra la ventana de sesión? Si el cliente no escribió ni respondió en 24 horas, sendMessage fallará hasta que una plantilla reabra el chat.
• ¿Cómo verifico la entrega? sent: true solo confirma aceptación. Rastrea la entrega vía webhook hooks[] o polling.
• ¿Qué pasa si no se entrega? Registra el hook failed/undelivered, verifica la ventana de sesión, luego reintenta o usa una plantilla.
• ¿Puedo conectarlo a mi CRM o backend? Sí — dispara la llamada a la API desde tu webhook entrante o motor de flujos.

Recursos relacionados

• Base de conocimiento
• Crear una plantilla
• Enviar una plantilla
• SDK