> ## Documentation Index
> Fetch the complete documentation index at: https://help.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrar CloudTalk Phone en una aplicación web

> Integra CloudTalk Phone mediante un iframe y gestiona eventos como el timbrado y el colgado.

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

**Nivel de usuario:**

* Admin

***

<h2 id="h_fd3f8a4e71">
  Instalar el iFrame
</h2>

<h3 id="h_4020b74e0a">
  Inicialización
</h3>

Para integrar e inicializar CloudTalk Phone:

* Usa un `iframe` con el siguiente formato de origen:\
  [`https://phone.cloudtalk.io?partner=yourappname`](https://phone.cloudtalk.io?partner=yourappname)

* Sustituye `yourappname` por el identificador de tu sistema en el parámetro de consulta `partner`.

**Ejemplo**:

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

<h3 id="h_d707360075">
  Requisitos
</h3>

* **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.

<Warning>
  **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.
</Warning>

<h2 id="h_d44a194390">
  Escuchar eventos
</h2>

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", ...)`.

<h3 id="h_0f5943ef25">
  Eventos compatibles
</h3>

* `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

<h4 id="h_4e7794e895">
  Comportamiento importante de los eventos
</h4>

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);
  }
});
```

<h3 id="h_9ef8c42217">
  Ejemplo de payload
</h3>

```json theme={"system"}
{
  "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": [
        "john.doe@company.io",
        "j.doe@gmail.com"
      ],
      "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](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — estamos aquí para ayudarte.


## Related topics

- [Guía de CloudTalk Phone](/es/articles/10559000-cloudtalk-phone-guide.md)
- [Introducción a CloudTalk e instalación de CloudTalk Phone](/es/articles/5349174-cloudtalk-introduction-installing-cloudtalk-phone.md)
- [Cómo usar CloudTalk Phone](/es/articles/2144759-using-cloudtalk-phone.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.