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

# Composeur intégré

> Intégrez le composeur Allo dans votre propre application web et pilotez-le avec postMessage

Le composeur intégré vous permet de placer un composeur Allo fonctionnel dans votre propre produit web avec une seule iframe. Votre équipe passe et reçoit des appels sans quitter votre application, et votre page est notifiée de chaque événement d'appel via `window.postMessage`.

C'est le même mécanisme que celui des panneaux HubSpot et Salesforce, ouvert pour que n'importe quel produit puisse l'utiliser.

<Note>
  L'accès est accordé par site web. Écrivez à [support@withallo.com](mailto:support@withallo.com) avec les domaines depuis lesquels vous voulez intégrer le composeur, et nous les activons. Tant qu'un domaine n'est pas activé, l'iframe affiche un écran "composeur non activé".
</Note>

## Ce que vous pouvez faire

* Ajouter un bouton d'appel en un clic n'importe où dans votre application, qui ouvre le composeur Allo avec un numéro pré-rempli
* Réagir aux appels dans votre propre interface : les enregistrer, ouvrir la fiche correspondante, démarrer un minuteur
* Garder vos utilisateurs dans un seul onglet au lieu de basculer vers une application d'appel séparée

## Comment intégrer le composeur

<Steps>
  <Step title="Ajoutez l'iframe">
    ```html theme={null}
    <iframe
      id="allo-dialer"
      src="https://web.withallo.com?variant=dialer"
      allow="microphone; autoplay; clipboard-write"
      style="width: 376px; height: 640px; border: 0;"
    ></iframe>
    ```

    L'attribut `allow="microphone; autoplay"` est obligatoire. Un appel nécessite l'accès au microphone, et le navigateur ne l'accorde qu'à une iframe dont la page parente l'autorise. Si votre page est elle-même dans une autre iframe, chaque page parente doit transmettre l'autorisation.
  </Step>

  <Step title="Connectez-vous">
    Votre coéquipier se connecte à Allo dans l'iframe à la première utilisation, ou réutilise une session `web.withallo.com` existante. Le composeur émet un événement `login` dès qu'un utilisateur est authentifié.
  </Step>

  <Step title="Écoutez les événements">
    Ajoutez un écouteur `message` pour réagir aux appels (voir ci-dessous).
  </Step>

  <Step title="Envoyez un numéro à composer">
    Envoyez une commande `dial` pour pré-remplir le clavier depuis votre propre bouton d'appel (voir ci-dessous).
  </Step>
</Steps>

## Écouter les événements du composeur

Chaque message du composeur a la forme `{ source: "allo-dialer", type, payload }`.

```js theme={null}
window.addEventListener("message", (event) => {
  if (event.origin !== "https://web.withallo.com") return;
  const { source, type, payload } = event.data ?? {};
  if (source !== "allo-dialer") return;

  switch (type) {
    case "ready":         /* composeur chargé */ break;
    case "login":         /* payload : { user_id, team_id } */ break;
    case "outgoing_call": /* payload : { to, call_id } */ break;
    case "incoming_call": /* payload : { from, to, call_id } */ break;
    case "call_answered": /* payload : { call_id } */ break;
    case "call_ended":    /* payload : { call_id, duration } */ break;
  }
});
```

### Événements émis par le composeur

| Événement       | Payload                 | Quand                                                                                                              |
| --------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `ready`         | aucun                   | Composeur chargé et activé pour votre domaine                                                                      |
| `login`         | `{ user_id, team_id }`  | Un utilisateur Allo est authentifié                                                                                |
| `outgoing_call` | `{ to, call_id }`       | Un appel sortant a démarré                                                                                         |
| `incoming_call` | `{ from, to, call_id }` | Un appel entrant sonne                                                                                             |
| `call_answered` | `{ call_id }`           | L'appel en cours a été décroché                                                                                    |
| `call_ended`    | `{ call_id, duration }` | L'appel s'est terminé. `duration` est la durée de conversation en secondes, `0` si l'appel n'a jamais été décroché |

## Envoyer des commandes au composeur

Envoyez un message `{ source: "allo-host", type, payload }` à l'iframe. Ciblez toujours `https://web.withallo.com`, jamais `*`.

```js theme={null}
const iframe = document.getElementById("allo-dialer");

const send = (type, payload) =>
  iframe.contentWindow.postMessage(
    { source: "allo-host", type, payload },
    "https://web.withallo.com",
  );

// Handshake optionnel. Fait ré-annoncer `ready` au composeur, et sur les
// navigateurs qui suppriment le referrer, c'est ce qui prouve votre origine activée.
send("init");

// Appel en un clic : pré-remplit le clavier. Votre coéquipier appuie sur appeler.
send("dial", { phone_number: "+15551234567" });
```

### Commandes acceptées par le composeur

| Commande | Payload            | Effet                                           |
| -------- | ------------------ | ----------------------------------------------- |
| `init`   | aucun              | Handshake. Le composeur répond avec `ready`     |
| `dial`   | `{ phone_number }` | Pré-remplit le clavier avec un numéro à appeler |

<Note>
  `dial` pré-remplit uniquement le clavier, il ne démarre jamais un appel tout seul. Le navigateur exige un clic de votre coéquipier pour débloquer le microphone, donc l'appel démarre quand il appuie sur le bouton d'appel.
</Note>

## Exemple

```html theme={null}
<iframe
  id="allo-dialer"
  src="https://web.withallo.com?variant=dialer"
  allow="microphone; autoplay; clipboard-write"
  style="width: 376px; height: 640px; border: 0;"
></iframe>

<button id="call-lead">Appeler ce prospect</button>

<script>
  const iframe = document.getElementById("allo-dialer");
  const ALLO = "https://web.withallo.com";

  document.getElementById("call-lead").addEventListener("click", () => {
    iframe.contentWindow.postMessage(
      { source: "allo-host", type: "dial", payload: { phone_number: "+15551234567" } },
      ALLO,
    );
  });

  window.addEventListener("message", (event) => {
    if (event.origin !== ALLO) return;
    const { source, type, payload } = event.data ?? {};
    if (source !== "allo-dialer") return;

    if (type === "call_ended") {
      console.log("Appel terminé :", payload.call_id, payload.duration, "secondes");
    }
  });
</script>
```

## Sécurité

* Donnez à l'iframe au moins environ 600px de hauteur pour que le clavier complet et l'écran d'appel tiennent. Le panneau a une largeur fixe d'environ 376px.
* Le composeur n'accepte les commandes que des domaines activés, et ne renvoie les événements qu'à votre origine vérifiée.
* `event.origin` est défini par le navigateur et ne peut pas être falsifié. Vérifiez-le toujours de votre côté, comme dans les exemples.

## Dépannage

<AccordionGroup>
  <Accordion title="L'iframe affiche un écran 'composeur non activé'">
    Votre domaine n'est pas encore activé. Écrivez à [support@withallo.com](mailto:support@withallo.com) avec les origines exactes depuis lesquelles vous intégrez le composeur (par exemple `https://app.votreentreprise.com`) et nous les activons.
  </Accordion>

  <Accordion title="Les appels échouent ou le microphone ne fonctionne pas">
    Assurez-vous que l'iframe a `allow="microphone; autoplay"`. Si votre page est elle-même dans une autre iframe, chaque page parente doit transmettre la même autorisation.
  </Accordion>

  <Accordion title="J'ai envoyé une commande dial mais rien ne se passe">
    Vérifiez que vous ciblez `https://web.withallo.com` (pas `*`) et que la forme du message est `{ source: "allo-host", type: "dial", payload: { phone_number } }`. Envoyez d'abord un `init` si vous avez ajouté votre écouteur après le chargement de l'iframe.
  </Accordion>

  <Accordion title="Je ne reçois pas d'événements">
    Confirmez que votre écouteur `message` vérifie `event.origin === "https://web.withallo.com"` et `source === "allo-dialer"`. Les événements ne circulent qu'une fois votre domaine activé.
  </Accordion>
</AccordionGroup>

## Besoin d'aide ?

<CardGroup cols={2}>
  <Card title="Activer votre domaine" icon="headset" href="mailto:support@withallo.com">
    Demandez à l'équipe Allo d'activer vos domaines d'intégration
  </Card>

  <Card title="Webhooks" icon="bolt" href="/fr/integrations/webhooks">
    Recevez des notifications côté serveur pour les appels et messages
  </Card>
</CardGroup>