ConnexionContact
Parcourir la documentation

Déployer

Campagnes d'appels sortants

Une campagne appelle les contacts d'une file d'attente, avec un seul agent et depuis un seul numéro. Vous remplissez la file, lancez la campagne et consultez les résultats à mesure que les appels se terminent.

Cycle de vie

  1. Créer

    POST/v1/campaigns avec un name, un agentId et un phoneId. La campagne est créée inactive, sauf si vous envoyez isActive: true.

  2. Ajouter des contacts

    POST/v1/campaigns/{campaignId}/contacts crée ou met à jour chaque contact d'après son numéro de téléphone et met un appel en file d'attente par contact.

  3. Démarrer

    Envoyez un PATCH sur la campagne avec isActive: true. Les appels en file d'attente sont composés dans la limite des appels par seconde du trunk, et les contacts ajoutés ensuite sont appelés à mesure qu'ils arrivent.

  4. Suivre

    Consultez les totaux avec GET/v1/campaigns/{campaignId} et les appels avec GET /v1/calls?campaignId=.

  5. Relancer

    POST/v1/campaigns/{campaignId}/retry crée une nouvelle campagne, inactive, pour les contacts que vous n'avez pas joints et qui n'ont jamais rappelé.

Ajouter des contacts

JSON
{
  "contacts": [
    {
      "salutation": "ms",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "phoneNumber": "+33612345678",
      "email": "ada@example.com",
      "metadata": { "plan": "pro", "renewal": "2026-11-15" }
    }
  ]
}
  • phoneNumber est obligatoire, au format E.164 : normalisez les numéros avant de les envoyer.
  • Un email présent mais vide ou mal formé fait échouer toute la requête avec une erreur 400 : omettez le champ si vous n'êtes pas sûr de sa valeur. error.issues[].path désigne le contact fautif, par exemple ["contacts", 0, "email"].
  • metadata accepte n'importe quel objet JSON et est transmis au prompt de l'agent (voir Variables).
Une campagne active appelle aussitôt

Quand la campagne est active, les appels partent dès que les contacts sont ajoutés. Envoyez d'abord un lot de test d'un ou deux numéros internes.

Démarrage, arrêt et horaires d'appel

isActive démarre et arrête la campagne. Une campagne n'a pas de plage horaire propre : pour respecter les horaires d'appel légaux, programmez la bascule de votre côté, au début et à la fin de chaque plage.

Arrêt automatique sur appels refusés

Une campagne s'arrête d'elle-même quand trop de ses appels récents sont rejetés dès leur émission, ce qui signifie généralement que l'opérateur bloque le numéro. Les appels récents désignent ses 40 derniers appels terminés au cours des 10 dernières minutes ; le calcul ne commence qu'une fois 30 appels terminés. declinedStopRatio fixe le seuil, de 0,35 (14 appels sur 40) à 0,7 (28 sur 40), 0,5 par défaut. C'est un réglage avancé : un compte sur lequel il n'est pas activé reçoit une erreur 403 ; demandez-le à votre chargé de compte.

Supprimer les appels en file d'attente

DELETE/v1/campaigns/{campaignId}/calls avec ?status=READY supprime les appels qui attendent encore d'être composés : tous, ou ceux des phoneNumbers que vous envoyez. Les appels déjà passés ne sont jamais touchés. Les totaux de la campagne sont calculés à partir des appels restants.

Désinscriptions

Quand un contact demande à ne plus être appelé, POST/v1/contact-opted-out marque son numéro. Ses appels en file d'attente et à venir se terminent avec le motif contact-opted-out, sans être composés. Une entrée boolean comme A demandé à être désinscrit dans les informations à collecter de l'agent permet à votre webhook de le faire automatiquement.