Utiliser les Webhooks Kavkom

Un webhook permet à une application d’envoyer automatiquement des informations à une autre lorsqu’un événement se produit.

Avec Kavkom, les événements téléphoniques que vous sélectionnez sont transmis vers l’URL de votre choix à l’aide de requêtes HTTP POST. Le format du corps dépend de l’événement : le POST de transcription est notamment envoyé en application/x-www-form-urlencoded, avec une valeur contenant du JSON.

Vous pouvez notamment recevoir des informations :

• pendant un appel entrant ;
• pendant un appel sortant ;
• après la fin d’un appel grâce au CDR (Call Detail Record).

Exemples d’utilisation

Configurer un webhook Kavkom

Avant de commencer, assurez-vous de disposer d’un endpoint capable :

• de recevoir des requêtes HTTP POST ;
• de traiter le contenu selon son Content-Type, notamment les données JSON lorsqu’elles sont envoyées sous ce format et le formulaire application/x-www-form-urlencoded pour la transcription ;
• de retourner une réponse HTTP.

Connectez-vous à Kavkom avec un compte disposant des autorisations nécessaires, puis rendez-vous dans :

La fenêtre de configuration regroupe les six zones présentées ci-dessous.

1Endpoint et test de connexion.

2Headers HTTP personnalisés.

3Variables personnalisées.

4Choix des types d’appels à pousser.

5Mapping des appels en direct.

6Mapping des CDR après la fin de l’appel.

1. Indiquer l’Endpoint

Dans le champ Endpoint, saisissez l’URL vers laquelle Kavkom doit envoyer les requêtes.

1Saisissez l’URL de réception de votre webhook.

2Test envoie une requête vide afin de vérifier que le receveur répond.

https://example.com/webhooks/kavkom

Tester l’Endpoint

Après avoir renseigné l’adresse, cliquez sur le bouton Test.

Kavkom envoie alors une requête vide vers l’endpoint et attend une réponse du serveur destinataire.

2. Configurer les Headers

La section Headers permet d’ajouter des informations aux en-têtes HTTP envoyés avec les requêtes.

1Key : nom de l’en-tête HTTP.

2Value : valeur transmise avec l’en-tête.

3Ajouter : ajoute une nouvelle paire Key / Value.

Chaque header est constitué d’une paire Key / Value. Ils peuvent notamment servir à transmettre les informations nécessaires à l’authentification de votre endpoint.

Key: Authorization
Value: Bearer votre_token

3. Ajouter des Variables

La section Variables permet d’ajouter des paramètres personnalisés sous forme de paires Key / Value.

1Key : nom de la variable personnalisée.

2Value : valeur associée.

3Ajouter : ajoute une nouvelle variable.

Ces variables peuvent servir à transmettre des informations complémentaires propres à votre intégration, par exemple un identifiant d’environnement, de compte ou de traitement.

4. Choisir les appels à transmettre

Dans la section What calls should be pushed?, sélectionnez les catégories d’événements que Kavkom doit envoyer vers votre endpoint.

1Entrants : événements des appels entrants en direct.

2Sortants : événements des appels sortants en direct.

3CDR : données envoyées après la fin de l’appel.

Vous pouvez activer plusieurs catégories simultanément.

5. Configurer le mapping des données

Kavkom propose deux mappings indépendants :

• Mapping for life calls pour les appels en direct ;
• Mapping for CDR pour les appels terminés.

Si vous configurez un mapping, vous pouvez associer une clé de votre choix au champ Kavkom attendu par votre application.

Mapping for life calls

1Définissez la clé de sortie attendue par votre système.

2Sélectionnez le champ Kavkom à associer.

3Ajouter permet de créer une correspondance supplémentaire.

Ce mapping concerne les événements des appels entrants et sortants en direct.

Mapping for CDR

1Définissez la clé de sortie attendue par votre système.

2Sélectionnez le champ CDR Kavkom à associer.

3Ajouter permet de créer une correspondance supplémentaire.

Ce mapping concerne les données finales envoyées après la fin de l’appel.

Données disponibles pour les appels en direct

À quoi sert le champ state ?

Le champ state permet à votre application de suivre l’évolution d’un appel et d’adapter son traitement selon les événements reçus.

Données disponibles pour les appels terminés

Le Mapping for CDR permet d’exploiter les informations disponibles après la fin d’un appel.

Recevoir la transcription d’un appel

Lorsqu’une transcription est disponible, Kavkom peut envoyer le texte de l’appel dans une requête HTTP POST distincte de celle du CDR. Cette requête contient deux paramètres principaux : cdr_uuid et transcription_data.

Structure du corps HTTP

Voici un exemple simplifié de requête, avec un identifiant et une transcription fictifs :

POST /votre-endpoint HTTP/1.1
Content-Type: application/x-www-form-urlencoded

cdr_uuid=927ec63d-1fa1-4b83-a548-907d612b5842&transcription_data=%5B%7B%22transcript%22%3A%22Bonjour%2C+je+souhaite+une+information.%22%7D%5D

Comment interpréter les données reçues ?

1. Lire le corps comme un formulaire application/x-www-form-urlencoded pour retrouver les valeurs de cdr_uuid et transcription_data.
2. Décoder la valeur de transcription_data (son encodage de formulaire, puis le JSON qu’elle contient) afin d’obtenir un tableau d’objets.
3. Lire la propriété transcript des objets de ce tableau pour accéder au texte de transcription.
4. Rapprocher la valeur de cdr_uuid avec xml_cdr_uuid pour associer la transcription au bon appel.

Après décodage, les mêmes données peuvent être représentées ainsi dans votre application. Ce bloc est une représentation logique ; il ne correspond pas au corps HTTP brut envoyé par Kavkom :

{
  "cdr_uuid": "927ec63d-1fa1-4b83-a548-907d612b5842",
  "transcription_data": [
    {
      "transcript": "Bonjour, je souhaite une information."
    }
  ]
}

Associer la transcription au CDR

Deux noms de champs différents désignent ici le même identifiant d’appel :

Exemple de traitement en JavaScript

Une fois le corps HTTP brut récupéré par votre serveur, vous pouvez le décoder comme suit :

// rawBody : contenu brut de la requête HTTP POST
const params = new URLSearchParams(rawBody);
const cdrUuid = params.get("cdr_uuid");
const transcription = JSON.parse(params.get("transcription_data") || "[]");

// Chaque élément peut contenir une propriété "transcript".
const textes = transcription.map(item => item.transcript);

// Rattacher l'ensemble à un CDR dont xml_cdr_uuid === cdrUuid.

Le décodage d’un formulaire est généralement effectué par le framework backend ; dans ce cas, analysez directement la chaîne reçue dans le paramètre transcription_data comme du JSON, sans la décoder deux fois.

Une transcription peut contenir des informations confidentielles ou personnelles. Protégez l’accès à ces données et appliquez les règles de conservation et d’accès adaptées.

Enregistrement d’appel

Lorsqu’un appel a été enregistré et qu’une URL est disponible, elle peut être transmise à votre application dans le champ :

recording_url

Votre application peut ensuite décider comment exploiter cette URL : l’associer à une activité CRM, l’utiliser dans une application métier, déclencher un traitement externe ou l’intégrer à votre propre processus d’archivage.

Appels en direct et CDR : quelle différence ?

Exemple d’utilisation avec un CRM

1. Un appel entrant est reçu sur Kavkom.
2. Kavkom envoie un événement vers votre endpoint.
3. Votre application récupère le numéro et les informations disponibles.
4. Le CRM peut rechercher le contact correspondant et créer ou mettre à jour une activité.
5. Les événements suivants permettent de suivre l’évolution de l’appel.
6. Lorsque l’appel se termine, Kavkom envoie le CDR.
7. Votre application peut enregistrer le statut, la durée et les autres informations finales disponibles.
8. Si un enregistrement existe, son URL peut être associée à l’activité.
9. Lorsqu’une transcription est reçue, le CRM peut la rattacher à cette même activité grâce à cdr_uuid et xml_cdr_uuid.

Bonnes pratiques