Integrar CloudTalk Phone en una aplicación web

Esta guía explica cómo integrar la interfaz de CloudTalk Phone en tu propia aplicación web mediante un iframe.

Nivel de usuario:

Admin

Instalar el iFrame

Inicialización

Para integrar e inicializar CloudTalk Phone:

Usa un iframe con el siguiente formato de origen:
https://phone.cloudtalk.io?partner=yourappname
Sustituye yourappname por el identificador de tu sistema en el parámetro de consulta partner.

Ejemplo:

<iframe src="https://phone.cloudtalk.io?partner=mycrm" allow="microphone *" height="700px" width="420px"></iframe>

Requisitos

Dimensiones mínimas: 700px de alto × 420px de ancho
CloudTalk Phone debe integrarse en una aplicación de página única (SPA). No debe recargarse al navegar entre vistas dentro de tu aplicación.

Las notificaciones no son compatibles en la versión integrada. En algunos casos, los usuarios pueden ver un aviso como «Las notificaciones no están habilitadas» - se trata de un problema visual conocido que no afecta al funcionamiento.

Escuchar eventos

Puedes registrarte para recibir los eventos de CloudTalk Phone con window.onmessage. Así tu sistema puede reaccionar a eventos como las llamadas entrantes o el fin de una llamada (por ejemplo, mostrando un panel con los detalles del contacto o poniendo el teléfono en primer plano). El CloudTalk Phone integrado se comunica con la aplicación principal mediante window.postMessage. Puedes escuchar con window.onmessage o con window.addEventListener("message", ...).

Eventos compatibles

ringing – se activa cuando aparece la notificación de una llamada entrante (la llamada empieza a sonar en el teléfono integrado)
dialing – se activa cuando un usuario inicia una llamada saliente (hace clic en marcar)
calling – se activa cuando se contesta la llamada (la otra parte descuelga)
hangup – se activa cuando el usuario hace clic en el botón rojo para finalizar la llamada (acción del usuario)
ended – se activa cuando la sesión de llamada termina por completo
contact_info – se activa cuando los datos del contacto relacionados con la llamada están disponibles o se actualizan

Comportamiento importante de los eventos

Si un usuario finaliza una llamada manualmente:

hangup se dispara primero (acción del usuario)
ended se dispara después (cierre de la sesión)

Sin embargo, ended también puede dispararse sin un hangup previo (por ejemplo, cuando la llamada se rechaza, falla o termina por un error). Uso recomendado:

Escucha hangup si necesitas reaccionar específicamente a que un usuario finalice una llamada de forma manual.
Escucha ended si necesitas detectar que la llamada ha terminado por completo, independientemente de cómo haya finalizado.

Quizá te interese maximizar una ventana del teléfono minimizada cuando entre una llamada, o abrir automáticamente la página de detalles del contacto del llamante en tu sistema. Ejemplo:

window.addEventListener("message", function (e) {
  try {
    const eventData = JSON.parse(e.data);
    console.log(eventData);

    switch (eventData.event) {
      case "ringing":
        console.log("Incoming call from:", eventData.properties.external_number);
        break;

      case "dialing":
        console.log("Outbound call started");
        break;

      case "calling":
        console.log("Call answered");
        break;

      case "hangup":
        console.log("User ended the call");
        break;

      case "ended":
        console.log("Call fully terminated");
        break;

      case "contact_info":
        console.log("Contact data received:", eventData.properties.contact);
        break;
    }
  } catch (error) {
    console.error("Invalid event data:", error);
  }
});

Ejemplo de payload

{
  "event": "ringing",
  "properties": {
    "call_uuid": "12345678-1234-1234-123a-012345a6789b",
    "external_number": "+44 20 3868 0167",
    "internal_number": "+1 888 487 1675",
    "contact": {
      "id": 1234,
      "name": "John Doe",
      "company": "Company Inc.",
      "contact_emails": [
        "[email protected]",
        "[email protected]"
      ],
      "contact_numbers": [
        "+44 20 3868 0167",
        "+44123123123"
      ],
      "external_urls": [
        {
          "external_system": "mycrm",
          "external_url": "https://mycrm.io/contact/123"
        }
      ],
      "tags": ["VIP", "Europe"]
    }
  }
}

Todos los eventos siguen esta misma estructura: event + properties con call_uuid, external_number, internal_number y contact (si está disponible).

¿Necesitas ayuda o tienes alguna pregunta? Escríbenos a través de nuestro Portal de atención al cliente — estamos aquí para ayudarte.

Primeros pasos

Números y portabilidad

IA

AI Sales Dialer

CloudTalk Phone y Go

Mensajería

Dashboard

Integraciones

Facturación y suscripción

Novedades y actualizaciones técnicas

Dashboard antiguo

Integrar CloudTalk Phone en una aplicación web

Instalar el iFrame

Inicialización

Requisitos

Escuchar eventos

Eventos compatibles

Comportamiento importante de los eventos

Ejemplo de payload

​Instalar el iFrame

​Inicialización

​Requisitos

​Escuchar eventos

​Eventos compatibles

​Comportamiento importante de los eventos

​Ejemplo de payload

Instalar el iFrame

Inicialización

Requisitos

Escuchar eventos

Eventos compatibles

Comportamiento importante de los eventos

Ejemplo de payload