Enviar WhatsApp a través de la API de Integración

Autenticación

La autenticación utiliza una Clave API Local dentro del cuerpo de la solicitud (campo `api_key`), no en un encabezado HTTP. Cada negocio tiene una Clave API Local (UUID) que se genera automáticamente cuando se crea el negocio.

Cómo obtener la Clave API Local

1. Inicia sesión en el panel de cshub en /app.
2. Abre Configuración → Clave API (o Perfil → Integración).
3. Copia la Clave API Local. Puedes regenerarla en cualquier momento: la clave antigua se vuelve inválida de inmediato.

Endpoint

Un solo endpoint cubre cada envío de WhatsApp No Oficial (whatsmeow). Elige method = text para mensajes de formato libre, o method = template para enviar una plantilla que ya configuraste en el panel.

Campos del cuerpo

El cuerpo es JSON. Los campos a continuación son paridad con whatscrmhub Laravel: al migrar desde la versión anterior, la forma de la solicitud es idéntica.

Ejemplos de solicitud

1. Enviar un mensaje de texto simple

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "6281234567890",
    "method": "text",
    "text": "Halo, makasih udah order ya!"
  }'

2. Enviar una plantilla con sustitución de variables

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "6281234567890",
    "method": "template",
    "template": "<TEMPLATE_ID>",
    "variables": {
      "$name": "Pak Budi",
      "$order_id": "INV-20260602-001"
    }
  }'

3. Enviar a un grupo (usar JID de grupo)

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "120363012345678901@g.us",
    "method": "text",
    "text": "Pengumuman: order minggu ini ditutup pukul 17:00.",
    "is_group": true
  }'

Respuesta de éxito (200 OK)

{
  "status": true,
  "message": "berhasil mengirim pesan"
}

Códigos de error y soluciones

Notas y límites

• Hay un límite de daily_send por dispositivo. Evita enviar más de ~10 mensajes/segundo desde un solo dispositivo para evitar prohibiciones de WhatsApp.
• Si tu negocio tiene `api_device_use = required`, el campo `device_key` es obligatorio. Con él opcional, el servidor elige un dispositivo activo basado en la configuración de `whatsapp_sender_notif` (`sequence` / `spin` / `random`).
• La sustitución de variables utiliza `str_replace` literal: los marcadores de posición pueden ser cualquier cadena (por ejemplo, `$name`, `{name}`, `[NAME]`). Solo necesita coincidir exactamente con el texto dentro del mensaje de plantilla.
• Siempre formatea sin "+" y sin espacios/guiones. Ejemplo: 6281234567890 (Indonesia), 60123456789 (Malasia). Para grupos, usa el JID completo con el sufijo `@g.us`.
• Iteración MVP: la carga de archivos binarios a través de multipart/form-data aún no es compatible. Para enviar medios, usa method=template con una plantilla que ya tenga una imagen configurada en el panel.

API de Integración vs API de Panel Interno

cshub mantiene deliberadamente dos caminos para enviar mensajes. La API de Integración es para desarrolladores de terceros y automatización; la API Interna alimenta el panel web de cshub y la app móvil. Diferente audiencia, diferente autenticación, diferente forma de respuesta.