Suivi du cycle de vie client

Ce document explique comment notifier Alvio du statut d'un contact (lead, client payant, ou churned) afin d'adapter automatiquement la gestion et les réponses.

Vue d'ensemble

Alvio permet de catégoriser vos contacts selon leur cycle de vie pour :

• Adapter les réponses : Un client payant reçoit un support différencié vs un simple prospect
• Prioriser les interactions : Les clients actifs sont traités en priorité
• Mesurer la conversion : Tracker les leads convertis suite à l'intervention Alvio
• Gérer le churn : Identifier et traiter différemment les anciens clients

Utilisation du champ lifecycle_stage

Le suivi du cycle de vie utilise le même endpoint webhook que l'envoi de leads. Ajoutez simplement le champ lifecycle_stage à votre payload JSON.

Valeurs acceptées

Note : Si lifecycle_stage n'est pas spécifié, Alvio considère le contact comme lead par défaut.

Scénarios d'utilisation

Scénario 1 : Envoi initial d'un lead

Lors de l'envoi initial, le contact est considéré comme un prospect :

{
  "phone_number": "+33612345678",
  "crm_contact_id": "12345-abc",
  "lifecycle_stage": "lead",
  "contact": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "campaign": {
    "source": "facebook",
    "campaign_name": "summer_promo"
  }
}

Vous pouvez aussi omettre le champ (comportement identique) :

{
  "phone_number": "+33612345678",
  "contact": {
    "name": "Jane Doe"
  }
}

Scénario 2 : Notification de conversion en client

Lorsqu'un prospect devient client payant, renvoyez un payload avec le même numéro de téléphone et le nouveau statut :

{
  "phone_number": "+33612345678",
  "lifecycle_stage": "customer"
}

Payload complet avec métadonnées de conversion (recommandé) :

{
  "phone_number": "+33612345678",
  "crm_contact_id": "12345-abc",
  "lifecycle_stage": "customer",
  "conversion": {
    "date": "2025-01-15",
    "amount": 5000,
    "currency": "EUR",
    "product": "Premium Package",
    "contract_duration": "12 months"
  }
}

Champs optionnels dans conversion :

• date — Date de conversion (ISO 8601 ou format libre)
• amount — Montant de la vente
• currency — Devise (EUR, USD, etc.)
• product — Produit/service acheté
• Tous champs supplémentaires sont acceptés

Scénario 3 : Signalement de churn

Lorsqu'un client résilie ou devient inactif :

{
  "phone_number": "+33612345678",
  "lifecycle_stage": "churned",
  "churn": {
    "date": "2025-03-20",
    "reason": "price",
    "notes": "Migrated to competitor"
  }
}

Exemples cURL

Conversion d'un lead en customer (Test)

curl -X POST 'https://webhooks.alvio.ai/6i8qsza7zhyt76' \
  -H 'api-key: test' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+33612345678",
    "lifecycle_stage": "customer",
    "conversion": {
      "date": "2025-01-15",
      "amount": 5000,
      "currency": "EUR"
    }
  }'

Signalement de churn (Production)

curl -X POST 'https://webhooks.alvio.ai/celqs5mur1l7p8' \
  -H 'api-key: 48FBBD88-78C1-4AC8-AFCB-1475C5F7236D' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+33612345678",
    "lifecycle_stage": "churned",
    "churn": {
      "date": "2025-03-20",
      "reason": "price"
    }
  }'

Identification des contacts

Alvio utilise le numéro de téléphone comme identifiant principal pour identifier et mettre à jour un contact existant.

Identifiants utilisés (par ordre de priorité) :

1. phone_number — Identifiant principal (requis)
2. crm_contact_id — Identifiant secondaire optionnel pour vos références internes

Bonnes pratiques :

• Utilisez toujours le format E.164 pour le numéro de téléphone (+33612345678)
• Le crm_contact_id est utile pour faire le lien avec votre CRM mais n'est pas obligatoire
• Assurez-vous d'utiliser le même numéro de téléphone pour un contact donné lors des mises à jour

Intégration dans votre workflow

Workflow typique

1. Lead capturé dans votre CRM
   ↓
2. Webhook Alvio : {"lifecycle_stage": "lead", ...}
   ↓
3. Alvio engage le prospect
   ↓
4. Prospect convertit → Deal fermé dans CRM
   ↓
5. Webhook Alvio : {"lifecycle_stage": "customer", ...}
   ↓
6. Alvio adapte automatiquement ses réponses

Intégration CRM

La plupart des CRMs modernes (HubSpot, Salesforce, Pipedrive, etc.) permettent de déclencher des webhooks sur des événements comme :

• Deal won → Envoi avec lifecycle_stage: "customer"
• Contact churned → Envoi avec lifecycle_stage: "churned"
• Deal reopened → Envoi avec lifecycle_stage: "lead"

Configurez ces triggers dans votre CRM pour synchroniser automatiquement les statuts.

Réponses et gestion d'erreurs

Les réponses sont identiques à l'endpoint webhook standard :

• 200 OK — Statut mis à jour avec succès

{
  "status": "SUCCESS",
  "message": "Contact lifecycle updated to customer",
  "request_id": "req_5bT84S86WHssLLHWD2FX"
}

• 4xx — Erreur client (JSON invalide, api-key manquant, etc.)
• 5xx — Erreur serveur (réessayez avec backoff exponentiel)

Questions fréquentes

Puis-je changer le statut plusieurs fois ?

Oui, vous pouvez mettre à jour le lifecycle_stage autant de fois que nécessaire. Par exemple :

• lead → customer → churned → lead (re-engagement)

Que se passe-t-il si je renvoie le même statut ?

Alvio acceptera la requête sans erreur. C'est idempotent.

Puis-je envoyer des champs supplémentaires lors d'une mise à jour ?

Oui, vous pouvez inclure tous les champs de votre payload habituel. Alvio mettra à jour les informations du contact. Par exemple :

{
  "phone_number": "+33612345678",
  "lifecycle_stage": "customer",
  "contact": {
    "email": "new.email@example.com",
    "company": "New Company Name"
  }
}

Comment savoir si un contact existe déjà ?

Vous n'avez pas besoin de le savoir. Alvio :

• Créera le contact s'il n'existe pas
• Mettra à jour le contact s'il existe déjà

L'identification se fait principalement via phone_number. C'est pourquoi il est important d'utiliser toujours le même format (E.164 recommandé).

Besoin d'aide pour intégrer le lifecycle tracking ? Contactez notre équipe technique pour un accompagnement personnalisé.