Documentation · Téléphoner

Lancer des appels depuis vos logiciels (API)

Votre CRM, votre site ou un script peut faire appeler un numéro en votre nom : votre téléphone sonne, vous décrochez, et LeBigo compose le numéro. C'est le clic pour appeler, piloté par vos outils.

Comment ça marche

1. Votre logiciel envoie une demande d'appel à LeBigo avec une clé API.
2. Tous vos appareils sonnent, comme pour un appel reçu : poste fixe, application sur l'ordinateur et sur le téléphone.
3. Vous décrochez sur celui de votre choix : les autres s'arrêtent, et LeBigo compose le numéro demandé, avec votre numéro habituel.

L'API ne relie jamais deux numéros extérieurs entre eux : c'est toujours vous qui décrochez en premier.

Créer sa clé

Une clé personnelle n'appelle que depuis votre ligne et ne voit que vos appels. Pour pouvoir en créer une, il faut que votre entreprise l'autorise ; sinon, la section n'apparaît pas.

1. Ouvrez Paramètres › Avancé, section CLÉS API.
2. Touchez Créer une clé, donnez-lui un Nom (à quoi elle sert, par exemple « CRM ») et une Validité (Sans échéance, 30 jours, 90 jours ou 1 an), puis Créer.
3. La clé s'affiche une seule fois : Copier, collez-la dans votre logiciel, puis C'est noté.

Des clés d'entreprise, qui peuvent appeler au nom de n'importe quel utilisateur, se créent côté administration : demandez-les à votre partenaire LeBigo.

Lancer un appel

curl -X POST "https://app.lebigo.io/api/v1/calls" \
      -H "Authorization: Bearer lbk_VOTRE_CLE" \
      -H "Content-Type: application/json" \
      -d '{"to": "+33612345678"}'

• to (obligatoire) : le numéro à appeler, ou le numéro interne d'un collègue ou d'un groupe.
• via : ce qui sonne. all (par défaut) : tous vos appareils, vous décrochez où vous voulez. Pour n'en faire sonner qu'un : desk (poste fixe, qui décroche tout seul), app (application), gsm (mobile), ou l'identifiant d'un appareil rendu par GET /api/v1/devices.
• user : avec une clé d'entreprise seulement, la personne pour qui appeler (adresse e-mail ou numéro interne).
• En-tête Idempotency-Key : renvoyer la même valeur dans les dix minutes ne relance pas un second appel.

Sans réponse sur aucun appareil, l'appel s'arrête là : il ne part jamais sur votre messagerie, et il n'apparaît pas en appel manqué.

La réponse (202) donne l'identifiant de l'appel et son état :

{"call_id": "…", "state": "ringing", "to": "+33612345678", "via": "all"}

Pour suivre l'appel : GET /api/v1/calls/{call_id}. Pour raccrocher : DELETE /api/v1/calls/{call_id}. L'état passe par ringing (votre appareil sonne), dialing (le correspondant sonne), answered et ended.

Ce que l'API ne compose pas

• Les numéros d'urgence et les codes étoile.
• Ce que vos autorisations d'appel vous interdisent déjà.
• Par défaut, tout ce qui n'est pas un fixe ou un mobile français : ni l'international, ni les numéros surtaxés, ni les numéros courts. Votre entreprise peut élargir ce réglage.

Se connecter à un groupe

Quand un groupe d'appel laisse ses membres se connecter et se déconnecter, votre logiciel peut le faire à leur place, comme *40 et *41 depuis un poste :

curl -X POST "https://app.lebigo.io/api/v1/groups/600/logout" \
      -H "Authorization: Bearer lbk_VOTRE_CLE"

• GET /api/v1/groups : vos groupes, et si vous y êtes connecté (logged_in). login vaut false pour un groupe où tout le monde sonne toujours.
• POST /api/v1/groups/{groupe}/login et …/logout : le groupe se nomme par son numéro interne ou son identifiant. Avec une clé d'entreprise, ajoutez {"user": "…"} pour nommer la personne.

Être prévenu : les webhooks

Votre logiciel peut recevoir les étapes de ses appels sur sa propre adresse :

curl -X POST "https://app.lebigo.io/api/v1/webhooks" \
      -H "Authorization: Bearer lbk_VOTRE_CLE" \
      -H "Content-Type: application/json" \
      -d '{"url": "https://crm.exemple.fr/lebigo", "events": ["call.ended"]}'

La réponse contient un secret, affiché une seule fois. Les événements sont call.ringing, call.answered et call.ended (avec la durée et l'issue), pour les appels lancés par l'API. L'adresse doit être en https.

Chaque envoi porte l'en-tête X-LB-Signature: t=…,v1=… : v1 est le HMAC-SHA256 de t, d'un point et du corps reçu, avec le secret. Vérifiez-le, et refusez un t vieux de plus de cinq minutes. X-LB-Delivery reste le même d'un essai à l'autre : il sert à ignorer un doublon. Sans réponse 2xx, LeBigo réessaie pendant quelques heures.

Codes de réponse