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

# Incorporar o CloudTalk Phone numa aplicação web

> Incorpore o CloudTalk Phone através de um iframe e trate eventos como toque de chamada e desligar.

<Note>
  Este guia explica como incorporar a interface do **CloudTalk Phone** na sua própria aplicação web através de um `iframe`.
</Note>

**Nível de utilizador:**

* Admin

***

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

<h3 id="h_4020b74e0a">
  Inicialização
</h3>

Para incorporar e inicializar o CloudTalk Phone:

* Utilize um `iframe` com o seguinte formato de origem:\
  [`https://phone.cloudtalk.io?partner=yourappname`](https://phone.cloudtalk.io?partner=yourappname)

* Substitua `yourappname` pelo identificador do seu sistema no parâmetro de consulta `partner`.

**Exemplo**:

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

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

* **Dimensões mínimas:** 700px de altura × 420px de largura

* O CloudTalk Phone tem de ser incorporado numa **Single Page Application (SPA)**. **Não deve ser recarregado** ao navegar entre vistas dentro da sua aplicação.

<Warning>
  As **notificações não são suportadas** na versão incorporada. Em alguns casos, os utilizadores podem ver um aviso como *"As notificações não estão ativadas"* - trata-se de um problema visual conhecido que não afeta o funcionamento.
</Warning>

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

Pode registar-se nos eventos do CloudTalk Phone através de `window.onmessage`. Isto permite que o seu sistema reaja a eventos como chamadas recebidas ou o fim de chamadas (por exemplo, mostrando um painel com os detalhes do contacto ou colocando o telefone em primeiro plano).

O CloudTalk Phone incorporado comunica com a aplicação principal através de `window.postMessage`. Pode escutar com `window.onmessage` ou `window.addEventListener("message", ...)`.

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

* `ringing` – acionado quando surge uma notificação de chamada recebida (a chamada começa a tocar no telefone incorporado)

* `dialing` – acionado quando um utilizador inicia uma chamada de saída (clica em marcar)

* `calling` – acionado quando a chamada é atendida (a outra parte atende)

* `hangup` – acionado quando o utilizador clica no botão vermelho de terminar chamada (ação do utilizador)

* `ended` – acionado quando a sessão da chamada é totalmente terminada

* `contact_info` – acionado quando os dados do contacto relacionados com a chamada estão disponíveis ou são atualizados

<h4 id="h_4e7794e895">
  Comportamento importante dos eventos
</h4>

Se um utilizador terminar manualmente uma chamada:

* `hangup` é acionado primeiro (ação do utilizador)

* `ended` é acionado depois (encerramento da sessão)

No entanto, `ended` também pode ser acionado sem um `hangup` anterior (por exemplo, quando a chamada é rejeitada, falha ou termina devido a um erro).

**Utilização recomendada:**

* Escute `hangup` se precisar de reagir especificamente ao facto de um utilizador terminar manualmente uma chamada.

* Escute `ended` se precisar de detetar que a chamada está totalmente concluída, independentemente de como terminou.

Pode querer **maximizar uma janela do telefone minimizada** quando existe uma chamada recebida ou **abrir automaticamente a página de detalhes do contacto de quem liga** no seu sistema.

**Exemplo**:

```
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">
  Exemplo 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 os eventos seguem esta mesma estrutura: `event` + `properties` com call\_uuid, external\_number, internal\_number e contact (se disponível).

***

*Precisa de ajuda ou tem alguma questão?* Contacte-nos através do nosso [Portal de suporte](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884)— estamos aqui para si.


## Related topics

- [Guia do CloudTalk Phone](/pt/articles/10559000-cloudtalk-phone-guide.md)
- [Implementar a CloudTalk Phone numa frota de dispositivos](/pt/articles/16801942-deploying-cloudtalk-phone-across-a-fleet.md)
- [Utilizar a CloudTalk Phone](/pt/articles/2144759-using-cloudtalk-phone.md)


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