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. Puede ser cualquiera de las acciones de la centralita: asistente de IA, menú de opciones, desvío a un teléfono, a una extensión o a un grupo de salto, aplicar un escenario guardado (la llamada hace exactamente lo que ese escenario tenga configurado), 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.

Un escenario es una combinación de «qué hace la llamada» guardada en el panel con un nombre y una clave: modo de entrada, saludo, menú, desvío, música de espera, grabación, encuesta y buzón. Se guardan desde Recepción de llamadas (botón Guardar como escenario) y su servidor los aplica devolviendo solo su clave:

      { "escenario": "soporte-vip" }

Por qué conviene. Las acciones sueltas de esta especificación (ia, ivr, desviar, buzon…) son menos de lo que se puede montar en el panel: con un escenario la llamada hace exactamente lo configurado, sin describirlo campo a campo en cada respuesta. Su servidor decide quién llama; el panel decide qué se hace con él.

• No hace falta `accion`: si viene `escenario`, esa es la acción.
• Lo que envíe ADEMÁS (`texto`, `idioma`, `grabar`) manda sobre el escenario: de lo general a lo particular.
• Un escenario nunca cambia el horario, los festivos, el número ni la URL de integración: eso es del número, y así ninguna respuesta puede abrir su centralita un domingo.
• Si la clave no existe en su cuenta, se ignora y la llamada sigue por su acción por defecto.
• Qué lleva un escenario: acción, saludo, menú, destino del desvío, qué pasa fuera de horario, música de espera, grabación, encuesta y buzón. Qué no lleva: horario, festivos, número y URL de integración.

En cualquier respuesta puede incluir el objeto contacto con los datos del llamante según su CRM. Este es el ejemplo completo —quién llama y qué hacemos con él— y es la forma recomendada de integrarse:

      {
        "escenario": "soporte-vip",
        "contacto": {
          "nombre":  "Ana Perez",
          "empresa": "Talleres Prieto",
          "nota":    "Cliente VIP - 12.480 EUR facturados - contrato hasta 03/2027",
          "enlace":  "https://sucrm.example/clientes/8812"
        }
      }

Qué ocurre con esos datos:

La ficha se guarda con la llamada, no solo mientras suena: la app de teléfono la muestra en la pantalla de llamada y en el historial sin volver a consultar su servidor —no le pedimos nada con el timbre sonando, ni una vez por cada aparato—, y desde ese historial el agente puede dar de alta el contacto en la agenda de la cuenta con un toque. A partir de ahí, ese número ya sale identificado en las siguientes llamadas aunque su servidor no conteste.

Los campos que no están en la tabla se ignoran, y los textos se recortan al límite indicado: al otro lado hay un móvil sonando y una nota de dos mil caracteres no cabe en esa pantalla.