Customer Lifecycle Tracking

This document explains how to notify Alvio of a contact's status (lead, paying customer, or churned) so that handling and responses can be adapted automatically.

Overview

Alvio lets you categorize contacts by lifecycle so you can:

• Adapt responses: A paying customer gets different support than a prospect
• Prioritize interactions: Active customers are handled first
• Measure conversion: Track leads that convert after Alvio's intervention
• Manage churn: Identify and treat former customers differently

Using the lifecycle_stage field

Lifecycle tracking uses the same webhook endpoint as sending leads. Simply add the lifecycle_stage field to your JSON payload.

Accepted values

Note: If lifecycle_stage is not set, Alvio treats the contact as lead by default.

Use cases

Scenario 1: Initial lead send

On first send, the contact is treated as a 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"
  }
}

You can also omit the field (same behavior):

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

Scenario 2: Notify conversion to customer

When a prospect becomes a paying customer, send a payload with the same phone number and the new status:

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

Full payload with conversion metadata (recommended):

{
  "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"
  }
}

Optional fields in conversion:

• date — Conversion date (ISO 8601 or free format)
• amount — Sale amount
• currency — Currency (EUR, USD, etc.)
• product — Product/service purchased
• Any additional fields are accepted

Scenario 3: Report churn

When a customer churns or becomes inactive:

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

cURL examples

Lead to 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"
    }
  }'

Report 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"
    }
  }'

Contact identification

Alvio uses the phone number as the primary identifier to find and update an existing contact.

Identifiers (by priority):

1. phone_number — Primary (required)
2. crm_contact_id — Optional secondary for your internal reference

Best practices:

• Use E.164 format for the phone number (+33612345678)
• crm_contact_id helps link to your CRM but is not required
• Use the same phone number for a given contact when updating

Workflow integration

Typical workflow

1. Lead captured in your CRM
   ↓
2. Alvio webhook: {"lifecycle_stage": "lead", ...}
   ↓
3. Alvio engages the prospect
   ↓
4. Prospect converts → Deal closed in CRM
   ↓
5. Alvio webhook: {"lifecycle_stage": "customer", ...}
   ↓
6. Alvio adapts its responses automatically

CRM integration

Most modern CRMs (HubSpot, Salesforce, Pipedrive, etc.) can trigger webhooks on events such as:

• Deal won → Send with lifecycle_stage: "customer"
• Contact churned → Send with lifecycle_stage: "churned"
• Deal reopened → Send with lifecycle_stage: "lead"

Configure these triggers in your CRM to keep statuses in sync.

Responses and error handling

Responses match the standard webhook endpoint:

• 200 OK — Status updated successfully

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

• 4xx — Client error (invalid JSON, missing api-key, etc.)
• 5xx — Server error (retry with exponential backoff)

FAQ

Can I change the status more than once?

Yes. You can update lifecycle_stage as often as needed, e.g.:

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

What if I send the same status again?

Alvio will accept the request without error. It is idempotent.

Can I send extra fields on update?

Yes. You can include all fields from your usual payload. Alvio will update the contact. For example:

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

How do I know if a contact already exists?

You don't need to. Alvio will:

• Create the contact if it doesn't exist
• Update the contact if it already exists

Identification is mainly via phone_number, so use a consistent format (E.164 recommended).

Need help integrating lifecycle tracking? Contact our technical team for personalized support.