Conversational Agent Interface (CAI)

1. Présentation

La Conversational Agent Interface (CAI) est l’interface standard d’OMB Cloud AES pour intégrer un prestataire externe d’agent conversationnel aux canaux numériques d’un client. Elle couvre la captation par formulaires, chat web et canaux de messagerie, ainsi que la conduite de la conversation jusqu’à un rendez-vous pris ou un résultat consigné.

La répartition du travail est délibérée et circonscrite. Le Prestataire apporte l’intelligence conversationnelle. AES apporte le flux de contacts, le routage et l’enregistrement permanent. Tout ce que le client consulte, mesure et exploite continue de vivre dans AES.

L’entreprise qui met en œuvre cette interface est désignée ci-après comme le Prestataire. Chaque Prestataire reçoit un provider_code et un jeu d’identifiants lors de son intégration.

Cette spécification est versionnée et commune à tous les Prestataires. Les valeurs propres à chaque environnement — code prestataire, catalogue, identifiants, adresses autorisées — sont remises séparément dans une annexe privée.

2. Responsabilités

2.1 Interfaces

Les deux sens fonctionnent en mode push. Aucune des parties n’interroge l’autre, et cette interface n’expose aucun point de lecture. Cela maintient une latence faible, supprime toute synchronisation périodique, et réduit l’intégration à exactement deux pièces mobiles.

3. Cycle de vie

  1. Contact      Remplit un formulaire ou écrit sur un canal numérique.

  2. AES          Crée l'enregistrement, résout l'unité de destination et
                  attribue un lead_id qui accompagne la relation.

  3. AES → Prest. [Interface A] Remet la mission de contact avec l'unité
                  et le contexte de la demande.

  4. Prestataire  Choisit le numéro d'origine de cette unité et engage
                  la conversation.

  5. Prest. → AES [Interface B] Retourne la conversation au fil de l'eau,
                  puis l'issue : rendez-vous pris ou motif de clôture.

  6. AES          Consigne les deux sur le lead, marqués du provider_code.
                  Le client poursuit le suivi.

L’unité de destination est résolue au moment de la captation, là où sont connus la page d’atterrissage, la campagne et la localisation demandée. Elle voyage dans le champ branch_code de chaque mission, de sorte qu’un Prestataire n’a jamais à maintenir ni à mettre à jour une logique de routage lorsqu’un client ouvre de nouvelles unités.

4. Interface A — Missions de contact

POST {provider_endpoint}/contact-jobs
Content-Type:    application/json
X-CAI-Source:    aes
X-CAI-Signature: sha256=<hmac_hex>
X-CAI-Timestamp: 1787923271

AES signe ses envois avec le mécanisme de la section 6, en utilisant le secret opposé de la paire. Le Prestataire doit les vérifier comme AES vérifie les siens : même algorithme, même fenêtre de 300 secondes, comparaison en temps constant.

AES remet chaque contact que le Prestataire doit traiter, au moment de la captation.

4.1 Corps de la requête

{
  "lead_id":        "AES-38-104772",
  "event_id":       "job_9f2c1a8e4b",
  "branch_code":    "ACME-NORD",
  "city":           "Lyon",
  "contact": {
    "name":         "Marie Fernande Rios",
    "phone_e164":   "+33612345678",
    "email":        "mfrios@example.com",
    "language":     "fr-FR"
  },
  "origin": {
    "channel":      "landing_form",
    "source":       "example.com/nord/service",
    "campaign":     "printemps-nord",
    "captured_at":  "2026-08-27T14:02:11+02:00"
  },
  "brief": {
    "intent":       "book_appointment",
    "notes":        "Souhaite un créneau en soirée."
  },
  "callback_url":   "https://omb.cloud/app/api/cai_events.php"
}

4.2 Champs

4.3 Réponse attendue

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "provider_job_id":      "prv_77219",
  "assigned_number_e164": "+33712345678"
}

Communiquer le numéro attribué permet à AES d’attribuer correctement les messages entrants de ce contact, et de conserver une conversation unique s’il revient plus tard par un autre canal.

5. Interface B — Événements de conversation

POST https://omb.cloud/app/api/cai_events.php
Content-Type:    application/json
X-CAI-Provider:  {provider_code}
X-CAI-Signature: sha256=<hmac_hex>
X-CAI-Timestamp: 1787923271

Un point d’entrée unique reçoit tout ce que le Prestataire retourne. Il est conçu pour l’écriture en temps réel, signé et idempotent, afin que le Prestataire puisse envoyer et réessayer sans risque de doublon.

5.1 conversation.message

Un événement par message, dans les deux sens, au fil de l’eau. L’enregistrement complet permet au client de voir le travail de l’agent tel qu’il s’est déroulé et d’attribuer précisément les rendez-vous obtenus.

{
  "event":            "conversation.message",
  "event_id":         "evt_4b81c07f",
  "lead_id":          "AES-38-104772",
  "provider_job_id":  "prv_77219",
  "channel":          "whatsapp",
  "from_number_e164": "+33712345678",
  "direction":        "outbound",
  "author":           "agent",
  "text":             "Bonjour Marie Fernande, je vous écris de...",
  "occurred_at":      "2026-08-27T14:04:39+02:00"
}

Champs de l’événement. event et event_id sont obligatoires sur chaque événement ; le reste dépend du type :

5.2 Événements de rendez-vous

Envoyés lors de la prise, du report ou de l’annulation. AES consigne le rendez-vous et le reporte sur le tableau de l’unité concernée.

{
  "event":        "appointment.booked",
  "event_id":     "evt_4b93a112",
  "lead_id":      "AES-38-104772",
  "branch_code":  "ACME-NORD",
  "scheduled_at": "2026-08-29T11:30:00+02:00",
  "service":      "premiere_visite",
  "notes":        "Préfère le matin.",
  "occurred_at":  "2026-08-27T14:11:02+02:00"
}

Valeurs acceptées pour event : appointment.booked, appointment.rescheduled, appointment.cancelled.

5.3 job.closed

Envoyé lorsque le traitement se termine sans rendez-vous. Permet au client de reprendre par d’autres moyens et évite un contact en doublon.

{
  "event":       "job.closed",
  "event_id":    "evt_4ba7d290",
  "lead_id":     "AES-38-104772",
  "outcome":     "no_answer",
  "attempts":    4,
  "occurred_at": "2026-08-29T18:00:00+02:00"
}

5.4 Idempotence et reprises

Chaque événement porte un event_id unique (jusqu’à 120 caractères). AES écarte les doublons et répond 202 avec {"ok": true, "duplicate": true}, de sorte qu’une reprise ne produit jamais d’enregistrement en double. En pratique, tout 2xx signifie accepté.

Un lead_id que AES ne reconnaît pas ne constitue pas une erreur : l’événement est accepté avec 202 et consigné pour rapprochement entre les deux équipes.

6. Authentification

Les deux sens sont signés en HMAC-SHA256 sur le corps de la requête, avec un secret partagé indépendant par sens. C’est le mécanisme qu’AES exploite déjà avec ses intégrations de messagerie et de paiement.

signature = HMAC_SHA256(secret, timestamp + "." + raw_body)
header    = "sha256=" + hex(signature)

6.1 Exemple résolu

Vérifiez votre implémentation avec ces valeurs exactes avant d’écrire le reste de l’intégration.

secret     cai_test_5f3a9c21b7e04d8a
timestamp  1787923271
body       {"event":"conversation.message","event_id":"evt_4b81c07f","lead_id":"AES-38-104772"}

signature = HMAC_SHA256(secret, timestamp + "." + body)

X-CAI-Signature: sha256=a893b6460bbb5063910f16ed0b8bbaa44204ea83d9a0ceaa6ac539e0d7bd9f1a

Ce qui est signé, c’est l’horodatage, un point littéral, et le corps brut tel qu’il est transmis : sans re-sérialiser, sans modifier les espaces, sans réordonner les clés. C’est là que la plupart des implémentations perdent du temps.

7. Environnements et catalogue d’unités

Chaque déploiement dispose de son environnement : un provider_code, une paire d’identifiants, et un catalogue de valeurs branch_code avec leur libellé. AES tient le catalogue à jour à mesure que le client ouvre des unités. Le Prestataire associe chaque code à son numéro d’origine.

Le routage voyageant avec la mission, une nouvelle unité n’exige aucune modification d’intégration de part et d’autre. Le Prestataire ajoute une ligne à sa table de correspondance ; rien d’autre ne bouge.

Le catalogue, les identifiants et les adresses autorisées figurent dans l’annexe privée qui accompagne cette spécification pour chaque déploiement.

Avec les identifiants de production, une paire d’identifiants d’essai est remise : mêmes URL, même schéma de signature, mais les données atterrissent dans un espace de test isolé. Tout ce que décrit ce document peut être exercé de bout en bout avec eux avant de toucher une donnée réelle, y compris la réception d’une mission d’exemple émise par AES.

8. Périmètre de la version 1.0

Cette première version se concentre sur ce qui produit des résultats dès le premier jour : joindre le contact, tenir la conversation, obtenir le rendez-vous. La garder circonscrite permet aux deux parties d’atteindre la production rapidement et à faible risque.

8.1 Inclus

• Remise en temps réel des contacts depuis tous les canaux numériques.
• Routage par unité, résolu par AES et transmis avec chaque mission.
• Enregistrement de la conversation complète, dans les deux sens.
• Rendez-vous pris, reportés et annulés.
• Issues motivées, pour coordonner le suivi.
• Attribution de chaque résultat au code du Prestataire.

8.2 Prévu pour des versions ultérieures

• Canaux supplémentaires, à mesure que les résultats sont validés sur ceux déjà en service.
• Disponibilité par unité, pour que l’agent propose des créneaux déjà confirmés.
• Événements postérieurs au rendez-vous, présence et suivi, pour boucler la mesure.
• Reporting étendu, selon ce que les deux équipes jugeront utile en exploitation.

8.3 Hors périmètre de cette interface

CAI est une interface push dans les deux sens et n’expose aucun point de lecture. Les chiffres d’exploitation dont un Prestataire a besoin pour son propre reporting sont remis par AES selon une périodicité convenue, comme décrit en section 9.

Dans les secteurs réglementés, les dossiers hébergés dans le système d’exploitation du client — dossiers médicaux, historiques financiers, pièces de dossier — restent hors de cette interface, puisqu’ils n’interviennent pas dans la prise de rendez-vous. Lorsqu’une donnée précise est réellement nécessaire à une conversation, elle est examinée au cas par cas avec le client.

9. Reporting et données personnelles

9.1 Reporting

AES remet au Prestataire un rapport périodique sur sa propre exploitation : missions reçues, délai de premier contact, conversations tenues, rendez-vous générés et issues. La fréquence et les champs sont convenus entre les deux équipes.

Parce qu’AES le produit, le rapport est calculé sur la même base que celle vue par le client. La mesure du service et celle du client coïncident toujours, sans réconciliation de chiffres entre plateformes.

9.2 Données personnelles

Le Prestataire agit en qualité de sous-traitant pour le compte du client : il utilise les informations aux seules fins de cette interface, ne les transfère pas à des tiers, ne les emploie à aucune autre fin y compris l’entraînement de modèles, et les supprime au terme de la relation contractuelle.

AES conserve l’enregistrement intégral de chaque conversation au titre de ses obligations de conservation envers le client. Cela garantit également la continuité de service en cas d’incident sur l’une ou l’autre plateforme.

10. Niveaux de service

Objectifs de référence. Ajustés par déploiement selon le modèle d’exploitation réel du Prestataire.

11. Devenir Prestataire

1. Confirmer le schéma de cette spécification.
2. Fournir la documentation du point d’entrée des missions et les IP de sortie.
3. Fournir les numéros ou identités d’origine disponibles par région.
4. Échanger les secrets en environnement de test.
5. Exécuter des tests de bout en bout sur un environnement de test fourni par AES.
6. Piloter sur une seule unité pendant deux semaines.
7. Déployer sur les unités restantes.

Piloter sur une unité permet aux deux équipes d’ajuster le script, les délais et la qualité des données à volume maîtrisé avant d’ouvrir le reste.

12. Gestion des versions

Ce document décrit la version 1.0. De nouveaux champs peuvent être ajoutés sans préavis et les champs non reconnus doivent être ignorés. Aucun champ n’est supprimé ni ne change de sens au sein d’une même version majeure. Les extensions de périmètre sont convenues entre les deux équipes et donnent lieu à une nouvelle version.

Annexe A — Énumérations

A.1 origin.channel

landing_form | contact_form | webchat | whatsapp_button | phone | referral

A.2 brief.intent

book_appointment | pricing_information | service_information |
reschedule | follow_up | other

A.3 author

agent    Agent conversationnel du Prestataire
contact  La personne contactée
human    Opérateur humain du Prestataire

A.4 outcome

A.5 Formats

A.6 channel et direction (Interface B)

channel:    whatsapp | webchat | sms | phone | email
direction:  inbound | outbound

Contact

Pour devenir Prestataire, ou pour toute question sur cette spécification, écrire à developers@omb.cloud.