# Composeur intégré

> Ajoutez le composeur Allo dans votre propre application

Vous pouvez intégrer votre propre composeur Allo directement dans votre application. Votre équipe passe et reçoit des appels sans quitter votre produit, et votre application reste synchronisée avec ce qui se passe sur chaque appel.

Ça fonctionne avec une seule iframe.

## Comment connecter

Ajoutez cette iframe là où vous voulez afficher le composeur :

```html
<iframe
  src="https://web.withallo.com?variant=dialer"
  allow="microphone; autoplay"
  style="width: 376px; height: 640px; border: 0;"
></iframe>
```

N'importe quel site peut intégrer le composeur. Il n'y a rien à activer côté Allo et aucun domaine à nous envoyer. Votre équipe se connecte à Allo dans le composeur la première fois.

L'attribut `allow="microphone"` est obligatoire : le navigateur n'accorde l'accès au micro à une iframe que si la page parente l'autorise. Si votre page est elle-même dans une iframe, chaque page parente doit transmettre l'autorisation du micro.

Si votre page envoie un en-tête `Permissions-Policy`, il doit autoriser le micro pour votre propre page et pour Allo :

```
Permissions-Policy: microphone=(self "https://web.withallo.com")
```

Si l'en-tête ne liste que `https://web.withallo.com`, Chrome bloque le micro sans rien demander. Le dialer indique alors que le micro est bloqué, alors que Chrome l'autorise pour votre site.

### Comment se connecter au composeur intégré

Connectez-vous avec votre e-mail ou votre numéro de téléphone et le code envoyé par Allo. La connexion avec Google ou Apple ne fonctionne pas dans le composeur intégré : Google et Apple empêchent leurs pages de connexion de s'afficher dans un autre site. Utilisez le composeur intégré dans Chrome ou Edge.

### Ce que contient le composeur intégré

Le composeur intégré passe et reçoit des appels. Votre application peut aussi mettre des contacts en file et lancer une session d'appels dans le composeur intégré, voir [Power dialing](#power-dialing).

## Événements que vous pouvez envoyer

Pilotez le composeur depuis votre application :

| Événement | Payload | Ce qu'il fait |
|-----------|---------|---------------|
| `init` | Aucun | Demande au composeur de renvoyer `ready`, par exemple si votre écouteur démarre après le chargement du composeur |
| `dial` | `{ phone_number }` | Ouvre le composeur avec un numéro prêt à appeler |
| `hangup` | `{ call_id }` | Raccroche l'appel en cours, ou le refuse tant qu'il sonne |

`dial` remplit le numéro, et votre collaborateur lance l'appel. `hangup` raccroche immédiatement. Passez le `call_id` reçu dans `outgoing_call` ou `incoming_call`, pour qu'un message en retard ne raccroche jamais un autre appel.

## Événements que vous recevez

Restez synchronisé avec ce qui se passe sur chaque appel :

| Événement | Payload | Quand ça se produit |
|-----------|---------|---------------------|
| `ready` | Aucun | Le composeur est chargé et prêt |
| `login` | `{ user_id, team_id }` | Un coéquipier se connecte |
| `outgoing_call` | `{ to, call_id }` | Un appel sortant démarre |
| `incoming_call` | `{ from, to, call_id }` | Un appel sonne |
| `call_answered` | `{ call_id }` | L'appel est décroché |
| `call_ended` | `{ call_id, duration }` | L'appel se termine. `duration` est le temps de conversation en secondes, `0` si personne n'a décroché |

Le `call_id` identifie l'appel dans le composeur intégré uniquement. Le `call_id` n'est pas l'`id` d'appel envoyé dans les [webhooks](/fr/help/integrations/webhooks) ou renvoyé par l'API. Pour relier un appel du composeur à un webhook, comparez les numéros de téléphone et l'heure de l'appel.

## Power dialing

Le power dialing permet à votre application d'envoyer une liste de contacts au composeur intégré et de lancer une session d'appels. Le composeur intégré appelle les contacts les uns après les autres et affiche la session à votre coéquipier. Votre application reçoit un événement à chaque étape de chaque appel. Elle peut donc ouvrir la bonne fiche dès qu'un appel démarre.

Le power dialing utilise la même file d'attente que le [Power Dialer](/fr/help/features/power-dialer) de l'application Allo. Les contacts envoyés par votre application s'ajoutent à la file Allo actuelle de votre coéquipier.

Chaque message garde la même enveloppe que les autres événements de cette page : `{ source: "allo-host", type, payload }` depuis votre application, `{ source: "allo-dialer", type, payload }` depuis le composeur intégré.

### L'objet contact

Votre application décrit chaque contact à appeler avec un objet contact :

| Champ | Obligatoire | Description |
|-------|-------------|-------------|
| `phone_number` | Oui | Le numéro à appeler, au format E.164, par exemple `+33612345678` |
| `name` | Non | Prénom |
| `last_name` | Non | Nom |
| `company` | Non | Nom de l'entreprise |
| `job_title` | Non | Poste |
| `external_id` | Non | Votre propre identifiant du contact, par exemple `person:123` |

Le composeur intégré garde l'`external_id` en mémoire avec le numéro de téléphone et le renvoie dans chaque événement qui concerne ce contact. Servez-vous de l'`external_id` pour retrouver la fiche dans votre application, sans comparer les numéros.

### Commandes de power dialing que vous pouvez envoyer

| Événement | Payload | Ce qu'il fait |
|-----------|---------|---------------|
| `power_dialer.queue` | `{ contacts, replace? }` | Ajoute les contacts à la file Allo actuelle de votre coéquipier. Avec `replace: true`, la file est d'abord vidée. Le composeur répond `power_dialer.queued` |
| `power_dialer.start` | `{}` | Lance une session sur la file actuelle. Si le navigateur exige d'abord un clic, le composeur répond `power_dialer.start_blocked` et affiche un bouton Start |
| `power_dialer.pause` | `{}` | Met la session en pause |
| `power_dialer.resume` | `{}` | Reprend une session en pause |
| `power_dialer.skip` | `{}` | Passe le contact en cours |
| `power_dialer.stop` | `{}` | Termine la session |
| `power_dialer.get_state` | `{}` | Demande l'état actuel. Le composeur répond `power_dialer.state` |

### Événements de power dialing que vous recevez

| Événement | Payload | Quand ça se produit |
|-----------|---------|---------------------|
| `power_dialer.queued` | `{ added, skipped, total }` | Après `power_dialer.queue`. `skipped` liste chaque numéro non ajouté, sous la forme `{ phone_number, reason }`. `total` est la taille de la file |
| `power_dialer.start_blocked` | `{ reason }` | La session n'a pas pu démarrer. Voir Pourquoi une session ne démarre pas, plus bas |
| `power_dialer.session_started` | `{ session_id, total, line }` | La session démarre. `line` est le numéro Allo qui passe les appels, sous la forme `{ number, name }` |
| `power_dialer.call_started` | `{ session_id, index, total, call_id, contact }` | Le composeur passe l'appel, avant la sonnerie. `call_id` peut encore valoir `null` |
| `power_dialer.call_ringing` | Comme `call_started` | L'appel sonne |
| `power_dialer.call_answered` | Pareil, avec `call_id` | Le contact décroche |
| `power_dialer.call_ended` | Pareil, plus `duration` et `result` | L'appel se termine. `duration` est le temps de conversation en secondes. `result` vaut `connected`, `no_answer`, `voicemail`, `skipped` ou `failed` |
| `power_dialer.paused` | `{ session_id }` | La session est en pause |
| `power_dialer.resumed` | `{ session_id }` | La session reprend |
| `power_dialer.session_ended` | `{ session_id, reason, stats }` | La session se termine. `reason` vaut `completed`, `stopped` ou `error` |
| `power_dialer.state` | `{ phase, session_id, index, total, current, queue }` | Après `power_dialer.get_state`, et à chaque changement de phase. `phase` vaut `idle`, `countdown`, `dialing`, `paused` ou `ended` |
| `power_dialer.error` | `{ code, message }` | Une erreur s'est produite |

Dans chaque événement `power_dialer.call_*`, `contact` est l'objet contact mis en file par votre application, `external_id` compris.

#### Exemples de payload

`power_dialer.queued` :

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.queued",
  "payload": {
    "added": 2,
    "skipped": [],
    "total": 2
  }
}
```

`power_dialer.session_started` :

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.session_started",
  "payload": {
    "session_id": "pds_8f2c1a",
    "total": 2,
    "line": { "number": "+33187654321", "name": "Ligne commerciale" }
  }
}
```

`power_dialer.call_started` :

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.call_started",
  "payload": {
    "session_id": "pds_8f2c1a",
    "index": 0,
    "total": 2,
    "call_id": null,
    "contact": {
      "phone_number": "+33612345678",
      "name": "Claire",
      "last_name": "Martin",
      "company": "Martin Plomberie",
      "job_title": "Gérante",
      "external_id": "person:123"
    }
  }
}
```

`power_dialer.call_ended` :

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.call_ended",
  "payload": {
    "session_id": "pds_8f2c1a",
    "index": 0,
    "total": 2,
    "call_id": "c_41d9",
    "contact": { "phone_number": "+33612345678", "external_id": "person:123" },
    "duration": 94,
    "result": "connected"
  }
}
```

`power_dialer.session_ended` :

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.session_ended",
  "payload": {
    "session_id": "pds_8f2c1a",
    "reason": "completed",
    "stats": { "dialed": 2, "connected": 1, "voicemail": 1, "no_answer": 0, "skipped": 0 }
  }
}
```

`power_dialer.state` :

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.state",
  "payload": {
    "phase": "dialing",
    "session_id": "pds_8f2c1a",
    "index": 0,
    "total": 2,
    "current": { "phone_number": "+33612345678", "external_id": "person:123" },
    "queue": [
      { "phone_number": "+33612345678", "external_id": "person:123" },
      { "phone_number": "+33698765432", "external_id": "person:456" }
    ]
  }
}
```

Les identifiants de ces exemples sont fictifs. Ne vous fiez pas à leur format.

### Comment se déroule une session de power dialing

1. Votre application envoie `power_dialer.queue` avec les contacts. Le composeur répond `power_dialer.queued`.
2. Votre application envoie `power_dialer.start`. Le composeur répond `power_dialer.session_started`, ou `power_dialer.start_blocked` si la session ne peut pas encore démarrer.
3. Pour chaque contact, votre application reçoit `power_dialer.call_started`, `power_dialer.call_ringing`, `power_dialer.call_answered` si le contact décroche, puis `power_dialer.call_ended`.
4. Si votre coéquipier met en pause, votre application reçoit `power_dialer.paused`, puis `power_dialer.resumed`.
5. Quand la file est terminée ou la session arrêtée, votre application reçoit `power_dialer.session_ended` avec les statistiques de la session.

Le composeur envoie aussi `power_dialer.state` à chaque changement de phase. Votre application peut ainsi refléter la session sans suivre chaque événement.

### Exemple de power dialing

Cet exemple met deux contacts en file, lance une session et ouvre la fiche correspondante dans votre application au début de chaque appel :

```html
<iframe id="allo" src="https://web.withallo.com?variant=dialer" allow="microphone; autoplay"></iframe>

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

  function send(type, payload = {}) {
    allo.postMessage({ source: "allo-host", type, payload }, ALLO);
  }

  // Mettre les contacts en file, puis lancer la session
  function startCalling() {
    send("power_dialer.queue", {
      replace: true,
      contacts: [
        { phone_number: "+33612345678", name: "Claire", last_name: "Martin", external_id: "person:123" },
        { phone_number: "+33698765432", name: "Karim", company: "Benali Électricité", external_id: "person:456" },
      ],
    });
    send("power_dialer.start");
  }

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

    switch (data.type) {
      case "power_dialer.call_started":
        // Ouvrir la fiche dans votre application, par exemple /people/123
        openRecord(data.payload.contact.external_id);
        break;
      case "power_dialer.start_blocked":
        // "user_gesture_required" : demandez à votre coéquipier de cliquer sur Start dans le composeur
        showMessage(data.payload.reason);
        break;
      case "power_dialer.session_ended":
        console.log("Session terminée :", data.payload.stats);
        break;
    }
  });
</script>
```

`openRecord` et `showMessage` représentent votre propre code.

### Pourquoi une session ne démarre pas

Les navigateurs n'autorisent une page à utiliser le micro et à jouer du son qu'après un clic de la personne dans la page. Le premier `power_dialer.start` peut donc répondre `power_dialer.start_blocked` avec la raison `user_gesture_required`. Le composeur intégré affiche alors un bouton Start, et la session démarre quand votre coéquipier clique dessus.

| `reason` | Ce que ça veut dire |
|----------|---------------------|
| `user_gesture_required` | Le navigateur exige d'abord un clic dans le composeur. Votre coéquipier clique sur Start dans le composeur |
| `no_line` | Votre coéquipier n'a aucun numéro Allo pour appeler |
| `empty_queue` | La file est vide. Envoyez d'abord `power_dialer.queue` |
| `not_entitled` | Votre coéquipier n'a pas accès au power dialing |

### Où trouver le résumé et l'enregistrement de l'appel

Le résumé, la transcription et l'enregistrement de l'appel ne figurent pas dans les événements du composeur : Allo les prépare après la fin de l'appel. Votre serveur les reçoit dans le [webhook](/fr/help/integrations/webhooks) `call.completed`. Comme pour les autres événements de cette page, le `call_id` n'est pas l'`id` d'appel du webhook : comparez les numéros de téléphone et l'heure de l'appel.

## Exemple

```html
<iframe id="allo" src="https://web.withallo.com?variant=dialer" allow="microphone; autoplay"></iframe>

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

  // Envoyer un numéro à appeler
  allo.postMessage({ source: "allo-host", type: "dial", payload: { phone_number: "+15551234567" } }, ALLO);

  // Raccrocher depuis votre propre bouton
  allo.postMessage({ source: "allo-host", type: "hangup", payload: { call_id: currentCallId } }, ALLO);

  // Réagir aux événements d'appel
  window.addEventListener("message", ({ origin, data }) => {
    if (origin !== ALLO || data?.source !== "allo-dialer") return;
    console.log("Événement Allo :", data.type, data.payload);
  });
</script>
```

## Besoin d'aide ?

<CardGroup cols={2}>
  <Card title="Contacter le support" icon="headset" href="/fr/help/support/contact">
    Un souci avec votre intégration ? Notre équipe peut vous aider
  </Card>
  <Card title="Webhooks" icon="bolt" href="/fr/help/integrations/webhooks">
    Recevez des notifications côté serveur pour les appels et messages
  </Card>
</CardGroup>
