Allo

Composeur intégré

Ajoutez le composeur Allo dans votre propre application

Mis à jour le

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 :

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

Événements que vous pouvez envoyer

Pilotez le composeur depuis votre application :

ÉvénementPayloadCe qu'il fait
initAucunDemande 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énementPayloadQuand ça se produit
readyAucunLe 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 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 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 :

ChampObligatoireDescription
phone_numberOuiLe numéro à appeler, au format E.164, par exemple +33612345678
nameNonPrénom
last_nameNonNom
companyNonNom de l'entreprise
job_titleNonPoste
external_idNonVotre 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énementPayloadCe 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énementPayloadQuand ç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_ringingComme call_startedL'appel sonne
power_dialer.call_answeredPareil, avec call_idLe contact décroche
power_dialer.call_endedPareil, plus duration et resultL'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 :

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

power_dialer.session_started :

{
  "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 :

{
  "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 :

{
  "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 :

{
  "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 :

{
  "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 :

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

reasonCe que ça veut dire
user_gesture_requiredLe navigateur exige d'abord un clic dans le composeur. Votre coéquipier clique sur Start dans le composeur
no_lineVotre coéquipier n'a aucun numéro Allo pour appeler
empty_queueLa file est vide. Envoyez d'abord power_dialer.queue
not_entitledVotre 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 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

<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 ?