Integración de la Centralita Virtual con su propio servidor: cuando alguien llama a uno de sus números de voz, hacemos una petición POST (JSON, firmada) a la URL que usted configure y ejecutamos en la llamada la acción que su servidor responda: hablar con el asistente de IA, reproducir un texto, desviar a un teléfono/extensión/grupo, ofrecer un menú de opciones, buzón de voz o colgar.

De esta forma su propia lógica de negocio decide, en tiempo real y llamada a llamada, qué hacer con cada llamante: enrutar por cliente VIP, por horario propio, por estado de un pedido, identificar al llamante contra su CRM, etc.

En su panel: Voz → Recepción de llamadas, seleccione el número y elija «Preguntar a mi servidor (integración por URL)». Configure:
- URL de su servidor: debe ser https y un host público (no se admiten IPs privadas ni redirecciones).
- Tiempo máximo de espera: 2 a 8 segundos. La llamada está sonando mientras su servidor responde: responda lo más rápido posible.
- Acción por defecto: qué hacemos si su servidor no responde a tiempo, devuelve un error o un JSON inválido (asistente de IA, menú, desvío, buzón o colgar).
- Clave de verificación: se genera al guardar; con ella firmamos cada petición para que pueda comprobar que somos nosotros.

El botón Probar del panel lanza una petición de prueba real contra su URL y le muestra el diagnóstico (código HTTP, JSON recibido y acción que se ejecutaría).

Cada petición incluye la cabecera X-Mensatek-Signature con el HMAC-SHA256 (en hexadecimal) del cuerpo crudo de la petición, calculado con su clave de verificación:

X-Mensatek-Signature: sha256=HMAC_SHA256(cuerpo, clave)

Ejemplo de verificación en PHP:

      $clave  = 'SU_CLAVE_DE_VERIFICACION';
      $cuerpo = file_get_contents('php://input');
      $firma  = $_SERVER['HTTP_X_MENSATEK_SIGNATURE'] ?? '';
      if (!hash_equals('sha256='.hash_hmac('sha256', $cuerpo, $clave), $firma)) {
        http_response_code(401); exit;
      }
      $datos = json_decode($cuerpo, true);

Recomendamos rechazar (401) cualquier petición cuya firma no verifique.

Si su servidor no responde dentro del tiempo configurado, responde con un código distinto de 2xx o el cuerpo no es un JSON válido, la llamada no se pierde: se ejecuta automáticamente la acción por defecto configurada en su panel. Su servidor debe responder 2xx con Content-Type: application/json.

Responda un objeto JSON con el campo accion y los campos adicionales que apliquen a esa acción (los demás se ignoran):

Campos comunes opcionales, aplicables a cualquier acción:
- idioma: voz e idioma del TTS con el formato xx-XX:n (n: 1 mujer, 2 hombre). Ej.: es-ES:1, pt-PT:1, en-US:1.
- grabar: true/false, activa o desactiva la grabación de esta llamada.

Ejemplos de respuesta:

      // Desviar un cliente VIP a su gestor
      { "accion": "desviar", "destino": "+34600000001" }

      // Desviar al grupo de salto 2 (suena en varias extensiones)
      { "accion": "desviar", "destino": "grupo:2" }

      // Saludo personalizado y asistente de IA
      { "accion": "ia", "texto": "Hola Sr. Garcia, le atiende el asistente de MiEmpresa." }

      // Menu guardado en el panel
      { "accion": "ivr", "plantilla": "Menu principal" }

      // Leer un aviso y colgar
      { "accion": "reproducir", "texto": "Su pedido 1234 sale hoy. Gracias por su llamada." }

      // Buzon con aviso propio y grabacion activada
      { "accion": "buzon", "texto": "Ahora no podemos atenderle, deje su mensaje.", "grabar": true }

Formato del menú en línea (menu): el mismo objeto que genera el editor visual del panel. Claves: locucion (texto que se lee ofreciendo las opciones; admite los marcadores (MP3:fichero) y (PAUSA:segundos)), esMenuDTMF = 1, y una clave por tecla con la opción: Accion (1 repetir · 2 aviso a URL · 3 aviso por email · 4 transferir a teléfono · 6 colgar · 7 asistente de IA · 8 transferir a extensión · 9 transferir a grupo), Valor (destino de la acción), Palabra (opcional: el llamante puede DECIRLA en vez de pulsar), LocucionPrevia y LocucionFinal (opcionales, antes y después de la acción).

      {
        "accion": "ivr",
        "menu": {
          "locucion": "Para comercial, diga comercial o pulse 1. Para soporte, pulse 2.",
          "esMenuDTMF": 1,
          "1": { "Accion": "9", "Valor": "grupo:1", "Palabra": "comercial", "LocucionPrevia": "Le paso con comercial." },
          "2": { "Accion": "8", "Valor": "ext:102" }
        }
      }

El campo evento de la petición identifica el momento de la llamada en que le consultamos (ignore los eventos que no reconozca respondiendo su acción por defecto):

La especificación irá incorporando nuevos eventos manteniendo el mismo formato y firma.

En cualquier respuesta puede incluir el objeto contacto con los datos del llamante según su CRM:

      { "accion": "desviar", "destino": "grupo:2",
        "contacto": { "nombre": "Jose Munoz (VIP)", "email": "jmunoz@cliente.com", "variable_1": "Pedido 8812" } }

El campo nombre se muestra en el softphone del agente al transferir la llamada (con prioridad sobre los contactos guardados en el panel). El resto de campos se usarán en próximas funciones (buzón inteligente).