Connecter votre call flow

#Vue d’ensemble

Votre call flow dialogue avec Smart Routings par de simples requêtes HTTP GET et lit des réponses JSON. Sur 3CX, construisez-le avec le Call Flow Designer ; tout IPBX dont le call flow sait envoyer une requête HTTP et lire une valeur JSON fonctionne de la même manière.

Toutes les URL ci-dessous sont relatives à l’API de votre espace :

https://your-workspace.cx-engine.com/api

Envoyez l’en-tête Accept: application/json sur chaque requête, pour que les erreurs soient elles aussi renvoyées en JSON.

Chaque lookup a besoin de votre compte, transmis via customer_account (l’identifiant de votre compte CX-Engine) ou customer_id.

#Authentification

Les endpoints de lookup demandent un jeton Bearer :

Authorization: Bearer {access-token}

Le jeton appartient à un utilisateur CX-Engine. Cet utilisateur doit avoir accès au compte et, dans son rôle, la permission Interrogation sur les ressources que le call flow interroge (Règles entrantes, Géographique, CTI).

#Jeton CFD (recommandé pour les call flows)

Un jeton CFD est un long secret conçu pour les call flows. Le call flow l’échange contre un jeton d’accès :

GET /api/smart-routings/cfd-auth/t/{cfd-token}

{
  "message": "success",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "expires_at": "2026-10-09T11:42:00+00:00",
  "user": { "id": 12, "name": "Call flows", "...": "..." }
}

Utilisez le token renvoyé comme jeton Bearer des lookups. Il porte le scope cfd, qui ne donne accès qu’aux endpoints de lookup et à l’enregistrement des enquêtes. Il est valable 1 heure : faites échanger le jeton CFD par le call flow à chaque appel. Faire expirer ou supprimer le jeton CFD révoque immédiatement ses jetons d’accès.

Un jeton CFD peut être limité à une liste d’adresses IP (hosts). Une requête venant d’une autre adresse reçoit 403 Host not authorised.

Un jeton CFD peut aussi avoir une date d’expiration (expires_at). Une fois celle-ci passée, l’échange répond 404 This token does not exists or has expired. Un jeton sans date d’expiration n’expire jamais.

Les jetons CFD se créent via l’API. Voir API CX-Engine › Smart Routings.

#Jeton OAuth

Tout jeton d’accès OAuth d’un utilisateur avec le scope client fonctionne aussi sur les lookups. Il est nécessaire pour lire les contacts de routage, que le scope cfd ne couvre pas. Voir API CX-Engine › Authentification.

#Lookup d’une règle entrante

Renvoie la destination d’une règle entrante à la date et à l’heure courantes.

GET /api/smart-routings/call-queues/lookup

day et time sont lus dans le fuseau horaire de votre compte. Servez-vous-en pour tester un planning (« que se passe-t-il le 25 décembre à 10 h ? »).

Exemple

GET /api/smart-routings/call-queues/lookup?customer_account=ACME&queue_number=800

Réponse 200 — une plage horaire correspond

{
  "reference": "open",
  "destination": "801",
  "label": null,
  "inherited": false,
  "matched": "time_span,day_of_week"
}

Réponse 200 — une exception correspond

{
  "reference": "France:christmasDay",
  "destination": "999",
  "label": "Noël",
  "inherited": false,
  "matched": "exception"
}

L’ordre d’évaluation est détaillé dans Comment la destination est choisie.

Erreurs

queue_number ne correspond qu’aux règles de type file. Pour une règle de type SDA, interrogez par queue_name ou queue_id.

#Lookup géographique

Renvoie les destinations d’une liste géographique pour un appelant.

GET /api/smart-routings/geo/destinations/lookup

Exemple

GET /api/smart-routings/geo/destinations/lookup?customer_account=ACME&list_id=1&number=0472000000

Réponse 200

{
  "destination1": "810",
  "destination2": "811",
  "destination3": null,
  "destination4": null,
  "fallback": false
}

fallback vaut true quand la zone de l’appelant n’est pas couverte par la liste : les quatre valeurs sont alors les destinations de secours de la liste. Si les quatre valeurs sont vides, l’API répond 404 No destination found matching given parameters. Une liste inconnue renvoie 404 No list found matching given parameters.

#Lookup CTI

#URL à jeton

Copiez l’URL d’interrogation depuis la page du CTI et ajoutez-y le numéro appelant. Aucune autre authentification n’est nécessaire :

GET /api/smart-routings/ctis/t/{cti-token}/{origin}

{
  "id": 42,
  "origin": "0033612345678",
  "destination": "https://erp.example.com/customers/1234"
}

L’origine doit correspondre exactement. Sans correspondance, l’API répond 404.

#Lookup authentifié

Avec un jeton Bearer (scope cfd ou client), appelez GET /api/smart-routings/ctis/lookup avec :

Exemple

GET /api/smart-routings/ctis/lookup?customer_account=ACME&cti_name=VIP%20callers&origin=0033612345678

Réponse 200

{
  "id": 42,
  "cti_id": 4,
  "origin": "0033612345678",
  "destination": "https://erp.example.com/customers/1234",
  "created_at": "2024-03-04T10:15:00.000000Z",
  "updated_at": "2024-03-04T10:15:00.000000Z"
}

Sans correspondance, l’API répond 404 avec No customer found matching given parameters., No CTI found matching given parameters. ou No destination found matching given parameters.

#Enquêtes

Les call flows peuvent aussi enregistrer les réponses d’une enquête post-appel avec POST /api/smart-routings/survey-records, avec le même jeton. Les réponses sont listées dans Routages > Enquêtes. Le format de la requête est détaillé dans API CX-Engine › Smart Routings.