WPSwitch · WPSwitch

Resumen del proceso

1 Requisitos previos en Meta — App, número certificado, umbral de conversaciones
2 Obtener credenciales de Meta — Token de sistema, WABA ID, App ID, Phone Number ID
3 Activar llamadas en Meta API — Habilitar SIP y obtener contraseña SIP
4 Configurar cuenta Meta en el portal — Token, WABA ID, App ID, entorno
5 Agregar y provisionar el número — SIP password, servidor destino, Phone Number ID
6 Configurar IPs autorizadas (ACL) — Controla desde qué IPs puede salir una llamada
7 Llamadas salientes — permisos de destinatario — Flujo automático y configuración del mensaje de solicitud

1

Requisitos previos en Meta

✓ Tener una App de Meta (Facebook Developers) aprobada para WhatsApp Business. El número debe estar certificado y la cuenta debe tener un medio de pago activo.
✓ Para acceder a la API de llamadas, la empresa debe haber alcanzado al menos 2.000 conversaciones iniciadas por la empresa en un período de 24 horas.
! Si usas un BSP (Business Solution Provider) como 360Dialog, debes coordinarlo con ellos para obtener las credenciales SIP. El proceso es el mismo pero se gestiona a través de su plataforma.

Las llamadas no están habilitadas por defecto en un número de WhatsApp Business. Deben activarse explícitamente en Meta (Paso 3).

2

Obtener credenciales de Meta

Desde Meta Business Suite / Facebook Developers, reúne los siguientes datos antes de configurar el portal:

Dato	Dónde encontrarlo	Usado en
System User Token	Meta Business Manager → Usuarios del Sistema → Generar token con permisos `whatsapp_business_messaging` y `whatsapp_business_management`	Cuenta Meta en el portal; llamadas a la API de Meta
WABA ID	Meta Business Manager → Cuentas de WhatsApp Business → ID de la cuenta	Cuenta Meta en el portal
App ID	Facebook Developers → Tu App → Panel de App → ID de la aplicación	Cuenta Meta en el portal
Business Manager ID	Meta Business Manager → Configuración del negocio → ID de la empresa	Cuenta Meta en el portal
Phone Number ID	Meta Business Manager → Cuentas de WhatsApp Business → Números → ID del número	Número de teléfono en el portal; llamadas a la API de Meta
SIP Password	Se obtiene en el Paso 3 ejecutando el cURL de credenciales SIP	Número de teléfono en el portal

Token de Sistema vs Token temporal: Usa siempre un token de usuario del sistema (nunca vence, a menos que lo revoques). Los tokens temporales de usuario expiran en 60 días y cortarán el servicio.

3

Activar llamadas en Meta API

3.1 Habilitar llamadas y configurar servidor SIP

Ejecuta este comando reemplazando PHONE_NUMBER_ID y SYSTEM_USER_TOKEN:

curl -X POST \
  "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID/settings" \
  -H "Authorization: Bearer SYSTEM_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calling": {
      "status": "ENABLED",
      "call_icon_visibility": "DEFAULT",
      "callback_permission_status": "ENABLED",
      "srtp_key_exchange_protocol": "SDES",
      "sip": {
        "status": "ENABLED",
        "servers": [
          { "hostname": "gwp.voipcentral.net", "port": 5061 }
        ]
      }
    }
  }'

Respuesta esperada:

{
  "success": true
}

Esto activa el módulo de llamadas con el servidor SIP de WPSwitch (gwp.voipcentral.net:5061) como destino de las llamadas entrantes desde WhatsApp.

3.2 Obtener la contraseña SIP del número

Una vez habilitadas las llamadas, consulta las credenciales SIP generadas por Meta:

curl -X GET \
  "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID/settings?include_sip_credentials=true" \
  -H "Authorization: Bearer SYSTEM_USER_TOKEN"

Respuesta (guarda el valor de sip_user_password):

{
  "calling": {
    "status": "ENABLED",
    "sip": {
      "servers": [
        {
          "hostname": "gwp.voipcentral.net",
          "port": 5061,
          "sip_user_name": "573001234567",
          "sip_user_password": "TU_SIP_PASSWORD_AQUI"
        }
      ]
    }
  }
}

Anota la contraseña SIP. La necesitarás al registrar el número en el portal (Paso 5). Meta no la muestra de nuevo una vez que cambias la configuración.

4

Configurar cuenta Meta en el portal

Ve a Configuración en el menú de navegación y busca la sección Cuenta Meta (WhatsApp Business).

1
Crear o editar la cuenta Meta

Haz clic en Editar (si ya existe) o Crear cuenta. Completa los campos:
- Business Manager ID — ID de tu empresa en Meta
- WABA ID — ID de tu cuenta de WhatsApp Business
- App ID — ID de tu aplicación en Facebook Developers
- System User Token — Token permanente de usuario del sistema
- Entorno — production para clientes reales, sandbox para pruebas (los límites de permisos de llamada son más flexibles en sandbox)
2

Verificar el token

Después de guardar, haz clic en Verificar Token. El sistema consultará la API de Meta para confirmar que el token es válido y tiene los permisos correctos. Si el estado cambia a active, el token es correcto.

¿Por qué se necesitan todos estos datos?
El token + WABA ID + Phone Number ID permiten que WPSwitch consulte en tiempo real si un número de destino ha otorgado permiso para ser llamado, y envíe solicitudes de permiso cuando sea necesario. Sin esta configuración, las llamadas salientes quedan bloqueadas.

5

Agregar y provisionar el número

1
Ve a Mis Números → Agregar Número

Completa el formulario con:
- Número en formato E.164 (ej: +573001234567)
- Nombre para mostrar (ej: "Soporte Principal")
- Contraseña SIP de Meta — obtenida en el Paso 3.2
- Servidor SIP de destino — IP o hostname de tu PBX (ej: 192.168.1.50 o pbx.miempresa.com)
- Puerto SIP — generalmente 5060
- Cuenta Meta — selecciona la cuenta creada en el Paso 4
- Meta Phone Number ID — el ID del número obtenido en el Paso 2
2
Provisionar el número

Haz clic en Provisionar. WPSwitch creará automáticamente en CustomPBX:
- Gateway SIP para registro con Meta
- Extensión de directorio
- Regla de dialplan de entrada (enruta llamadas entrantes de WhatsApp a tu PBX)
- Regla de dialplan de salida (filtra por IPs autorizadas)
Cuando el estado cambie a active, el número está listo para recibir llamadas entrantes desde WhatsApp.

6

Configurar IPs autorizadas (ACL para salientes)

Las IPs autorizadas controlan qué servidores pueden iniciar llamadas salientes a través de WPSwitch. Si la lista está vacía, se permiten llamadas desde cualquier IP. Si tiene IPs, solo esas IPs podrán originar llamadas salientes.

¿Qué IP debo agregar?

Agrega la IP pública del servidor PBX desde donde se originan las llamadas salientes. Esta es la IP con la que tu PBX se conecta a internet, no la IP interna de la red local.

Cómo configurar las IPs autorizadas

A. Ve a Configuración → sección IPs Autorizadas para Llamadas Salientes.

B. Escribe la IP pública de tu PBX en formato IPv4 (ej: 203.0.113.45) o IPv6 y haz clic en Agregar IP.

C. Al guardar, WPSwitch actualiza automáticamente el dialplan de salida en CustomPBX para todos tus números activos.

Sin IPs configuradas

Cualquier servidor puede originar una llamada saliente. Útil solo durante pruebas iniciales.

Con IPs configuradas

Solo los servidores en la lista pueden originar llamadas salientes. Recomendado para producción.

7

Llamadas salientes — permisos del destinatario (flujo automático)

Requisito de Meta: Para realizar una llamada saliente de WhatsApp Business, el destinatario debe haber otorgado permiso explícito para ser llamado. WPSwitch consulta este permiso en tiempo real antes de permitir cada llamada.

Cómo funciona el flujo de permisos

1

Tu PBX origina la llamada

WPSwitch intercepta la llamada saliente y ejecuta la validación de permisos antes de conectarla.
2

WPSwitch consulta a Meta

Llama a GET /PHONE_NUMBER_ID/call_permissions?user_wa_id=DESTINO y verifica si start_call.can_perform_action es true.
✓

Permiso aprobado → llamada conectada

La llamada pasa y se registra el resultado (atendida / no atendida).
✗

Sin permiso → llamada bloqueada + solicitud automática

La llamada no se conecta. WPSwitch envía automáticamente una solicitud de permiso al destinatario (si hay mensaje configurado y Meta lo permite).

Estados de permiso posibles

Aprobado El destinatario otorgó permiso. La llamada puede realizarse.

Pendiente Se envió una solicitud y está esperando respuesta. No se puede llamar aún ni enviar otra solicitud.

Rechazado El destinatario rechazó el permiso. Consulta los límites para saber si se puede reenviar.

Sin permiso No hay permiso registrado. Se puede enviar una solicitud (sujeto a límites diarios/semanales).

Solicitud automática de permiso

Cuando el plan de marcado saliente intenta una llamada y Meta responde que no hay permiso, WPSwitch envía automáticamente una solicitud de permiso al destinatario vía WhatsApp — sin intervención del operador. El destinatario recibe un mensaje interactivo con la opción de Aceptar o Rechazar.

1. Antes de conectar cada llamada saliente, WPSwitch consulta a Meta en tiempo real para verificar si el destinatario tiene permiso activo.
2. Si no hay permiso y Meta permite enviar una solicitud, WPSwitch la envía automáticamente usando el mensaje configurado en la cuenta Meta del portal.
3. La llamada se bloquea y el llamante escucha un audio indicando que se envió la solicitud al destinatario.
4. Cuando el destinatario acepta, la siguiente llamada ya pasará la validación y se conectará normalmente.

Configurar el mensaje de solicitud automática

En Configuración → sección Cuenta Meta, hay un campo Mensaje automático de solicitud de permiso. El texto que se ingrese ahí es el que WPSwitch enviará al destinatario cuando el dialplan detecte que no hay permiso. Si este campo queda vacío, la solicitud automática no se envía.

Límites de Meta: En producción solo se puede enviar 1 solicitud por día y 2 por semana al mismo destinatario. En sandbox los límites son más altos (25/día, 100/semana). Si ya se envió una solicitud y está pendiente de respuesta, no se enviará otra aunque el cliente vuelva a marcar.

Herramienta de diagnóstico (solo para administradores)

La sección Consulta y solicitud de permisos en Configuración es una herramienta de debug para verificar en línea el estado actual de un permiso y, si es necesario, enviar manualmente una solicitud puntual. No forma parte del flujo normal de operación — el proceso automático descrito arriba se encarga de las solicitudes durante las llamadas.

Consultar el estado de permiso directamente en Meta

curl -X GET \
  "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID/call_permissions?user_wa_id=NUMERO_DESTINO" \
  -H "Authorization: Bearer SYSTEM_USER_TOKEN"

Respuesta cuando el permiso está aprobado:

{
  "permission": {
    "status": "approved",
    "expiration_time": 1800000000
  },
  "actions": [
    {
      "action_type": "start_call",
      "can_perform_action": true
    }
  ]
}

Respuesta cuando no hay permiso (pero se puede solicitar):

{
  "permission": {
    "status": "no_permission"
  },
  "actions": [
    {
      "action_type": "start_call",
      "can_perform_action": false
    },
    {
      "action_type": "send_call_permission_request",
      "can_perform_action": true,
      "limits": [
        { "time_period": "day",  "max_allowed": 1, "current_usage": 0 },
        { "time_period": "week", "max_allowed": 2, "current_usage": 0 }
      ]
    }
  ]
}

Guardia local de WPSwitch

Además de la validación de Meta, WPSwitch bloquea llamadas salientes si el destinatario no atiende de forma consecutiva: en producción, al alcanzar 2 llamadas sin respuesta consecutivas se bloquea temporalmente. En sandbox el umbral es de 5 llamadas. Este contador se resetea automáticamente cuando el destinatario atiende una llamada.

Preguntas frecuentes

¿Por qué el número queda en estado error después de provisionar?

Verifica que el servidor SIP de destino y el puerto sean correctos, y que sea accesible desde internet. Revisa también que la contraseña SIP de Meta esté bien copiada.

¿Las llamadas entrantes funcionan sin la cuenta Meta configurada?

Sí. Las llamadas entrantes de WhatsApp solo requieren que el número esté provisionado con la contraseña SIP correcta. La cuenta Meta solo es obligatoria para llamadas salientes.

¿Qué pasa si el token de Meta expira?

Las llamadas salientes quedan bloqueadas (WPSwitch no puede consultar permisos). El estado de la cuenta en Configuración cambiará a expired. Actualiza el token lo antes posible. Por eso se recomienda siempre un token de usuario del sistema (no vence).

¿El cambio de IPs autorizadas afecta las llamadas en curso?

No interrumpe las llamadas activas, pero WPSwitch reprovisiona el dialplan de salida en CustomPBX automáticamente al guardar. Las nuevas llamadas usarán las IPs actualizadas.

Centro de Ayuda — Guía de Activación