Intégrer CloudTalk Phone dans une application web

Ce guide explique comment intégrer l’interface CloudTalk Phone dans votre propre application web à l’aide d’une iframe.

Niveau utilisateur :

Admin

Installer l’iFrame

Initialisation

Pour intégrer et initialiser CloudTalk Phone :

Utilisez une iframe avec le format de source suivant :
https://phone.cloudtalk.io?partner=yourappname
Remplacez yourappname par l’identifiant de votre système dans le paramètre de requête partner.

Exemple :

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

Prérequis

Dimensions minimales : 700px de hauteur × 420px de largeur
CloudTalk Phone doit être intégré dans une application monopage (SPA). Il ne doit pas être rechargé lorsque vous naviguez entre les vues de votre application.

Les notifications ne sont pas prises en charge dans la version intégrée. Dans certains cas, les utilisateurs peuvent voir un avertissement du type « Les notifications ne sont pas activées » - il s’agit d’un problème d’affichage connu, sans impact sur le fonctionnement.

Écouter les événements

Vous pouvez vous abonner aux événements de CloudTalk Phone via window.onmessage. Votre système peut ainsi réagir à des événements comme les appels entrants ou les raccrochages (par exemple en affichant un panneau de détails du contact ou en mettant le téléphone au premier plan). Le CloudTalk Phone intégré communique avec l’application parente via window.postMessage. Vous pouvez écouter avec window.onmessage ou window.addEventListener("message", ...).

Événements pris en charge

ringing – déclenché lorsqu’une notification d’appel entrant apparaît (l’appel commence à sonner dans le téléphone intégré)
dialing – déclenché lorsqu’un utilisateur lance un appel sortant (clic sur composer)
calling – déclenché lorsque l’appel est décroché (l’interlocuteur répond)
hangup – déclenché lorsque l’utilisateur clique sur le bouton rouge de fin d’appel (action de l’utilisateur)
ended – déclenché lorsque la session d’appel est entièrement terminée
contact_info – déclenché lorsque les données de contact liées à l’appel sont disponibles ou mises à jour

Comportement important des événements

Si un utilisateur met fin à un appel manuellement :

hangup se déclenche en premier (action de l’utilisateur)
ended se déclenche ensuite (fermeture de la session)

Cependant, ended peut aussi se déclencher sans hangup préalable (par exemple lorsque l’appel est rejeté, échoue ou se termine à cause d’une erreur). Utilisation recommandée :

Écoutez hangup si vous devez réagir spécifiquement à un appel terminé manuellement par l’utilisateur.
Écoutez ended si vous devez détecter qu’un appel est entièrement terminé, quelle qu’en soit la cause.

Vous souhaiterez peut-être agrandir une fenêtre de téléphone réduite lors d’un appel entrant, ou ouvrir automatiquement la fiche de contact de l’appelant dans votre système. Exemple :

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

Exemple de charge utile

{
  "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"]
    }
  }
}

Tous les événements suivent cette même structure : event + properties contenant call_uuid, external_number, internal_number et contact (si disponible).

Besoin d’aide ou vous avez une question ? Écrivez-nous simplement via notre Portail Support — nous sommes là pour vous.

Premiers pas

Numéros et portabilité

IA

AI Sales Dialer

CloudTalk Phone et Go

Messages

Dashboard

Intégrations

Facturation et abonnement

Actualités et mises à jour techniques

Ancien Dashboard

Intégrer CloudTalk Phone dans une application web

Installer l’iFrame

Initialisation

Prérequis

Écouter les événements

Événements pris en charge

Comportement important des événements

Exemple de charge utile

​Installer l’iFrame

​Initialisation

​Prérequis

​Écouter les événements

​Événements pris en charge

​Comportement important des événements

​Exemple de charge utile

Installer l’iFrame

Initialisation

Prérequis

Écouter les événements

Événements pris en charge

Comportement important des événements

Exemple de charge utile