Skip to content

Instantly share code, notes, and snippets.

@cosydney

cosydney/ADMVALUE_ALVIO_EVENT_FORMATS.md

Last active April 9, 2026 11:49
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save cosydney/06e98ecd465af577f9b5f625de5b3fde to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save cosydney/06e98ecd465af577f9b5f625de5b3fde to your computer and use it in GitHub Desktop.
Download ZIP
Admvalue x Alvio integration guide
Raw
ADMVALUE_ALVIO_EVENT_FORMATS.md

Admvalue x Alvio Integration Guide

Overview

This document describes the data formats exchanged between Alvio and Admvalue for the following event types:

  • update
  • availability_request
  • meeting

These formats are designed to be:

  • easy to consume in CRM or middleware workflows
  • stable over time
  • explicit enough for operational teams
  • compatible with raw source lead data provided by Admvalue

Target Endpoint

All examples below use the following target endpoint:

  • URL: https://ws.admvalue.fr/RBT3/alvio-api/
  • Header: Authorization: Bearer <token>
  • Content type: application/json

Reference example:

curl --location 'https://ws.admvalue.fr/RBT3/alvio-api/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"test":"ALVIO"}'

Integration Flow

The expected business flow is the following:

  1. A lead is received by Alvio.
  2. Alvio checks whether the lead has WhatsApp.
  3. If the lead does not have WhatsApp, Alvio sends an update event with event_name = NO_WHATSAPP.
  4. If the lead has WhatsApp, Alvio starts or continues the conversation.
  5. During the conversation:
    • if a booking flow is needed, Alvio requests availabilities, proposes slots, and sends a meeting event once the slot is confirmed
  6. As the conversation progresses, Alvio can send additional update events when new business-relevant information becomes available.

Common Event Envelope

All outgoing payloads should follow the same top-level structure.

Design Principles

  • event_type describes the category of event
  • event_name describes the specific business event
  • external_references contains Admvalue or CRM identifiers
  • alvio contains Alvio-specific context
  • data contains event-specific fields
  • source_data contains the original lead payload sent by Admvalue

Recommended Common Payload

{
  "event_id": "evt_01JXYZ...",
  "event_type": "update",
  "event_name": "NO_WHATSAPP",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T10:30:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456",
    "account_id": "acc_789"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": "conv_123",
    "conversation_url": "https://alvio.ai/inbox/conversations/conv_123",
    "business_phone": "+33100000000",
    "has_whatsapp": false
  },
  "data": {},
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}

Required Fields

The following fields are strongly recommended on all events:

  • event_id
  • event_type
  • event_name
  • version
  • occurred_at
  • lead.phone
  • external_references.contact_id when available
  • external_references.deal_id when available
  • alvio.campaign_id when available
  • alvio.conversation_id when available
  • alvio.conversation_url when available
  • alvio.has_whatsapp
  • data
  • source_data

Event Reference

1. Update Events

update is used by Alvio to push a business status or progressive lead enrichment payloads to Admvalue.

Supported Event Names

  • LEAD_RECEIVED
  • NO_WHATSAPP
  • CONVERSATION_STARTED
  • LEAD_UPDATED

1.1 NO_WHATSAPP

Use this event when a lead has been received, but the WhatsApp check fails and no WhatsApp conversation can be started.

Recommended Payload

{
  "event_id": "evt_01JXYZ001",
  "event_type": "update",
  "event_name": "NO_WHATSAPP",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T10:31:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": null,
    "conversation_url": null,
    "business_phone": "+33100000000",
    "has_whatsapp": false
  },
  "data": {
    "status": "no_whatsapp",
    "reason": "phone_not_on_whatsapp",
    "recommended_action": "phone_callback"
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}

cURL Example

curl --location 'https://ws.admvalue.fr/RBT3/alvio-api/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "event_id": "evt_01JXYZ001",
  "event_type": "update",
  "event_name": "NO_WHATSAPP",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T10:31:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": null,
    "conversation_url": null,
    "business_phone": "+33100000000",
    "has_whatsapp": false
  },
  "data": {
    "status": "no_whatsapp",
    "reason": "phone_not_on_whatsapp",
    "recommended_action": "phone_callback"
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}'

1.2 LEAD_UPDATED

Use this event whenever Alvio has new lead information worth sharing externally, including qualification, summary, sentiment, or booking status.

Recommended Payload

{
  "event_id": "evt_01JXYZ999",
  "event_type": "update",
  "event_name": "LEAD_UPDATED",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T11:05:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": "conv_123",
    "conversation_url": "https://alvio.ai/inbox/conversations/conv_123",
    "business_phone": "+33100000000",
    "has_whatsapp": true
  },
  "data": {
    "status": "active",
    "qualification": "qualified",
    "summary": "Le prospect souhaite etre rappele demain matin.",
    "sentiment": "positive",
    "meeting_booked": false
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}

cURL Example

curl --location 'https://ws.admvalue.fr/RBT3/alvio-api/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "event_id": "evt_01JXYZ999",
  "event_type": "update",
  "event_name": "LEAD_UPDATED",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T11:05:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": "conv_123",
    "conversation_url": "https://alvio.ai/inbox/conversations/conv_123",
    "business_phone": "+33100000000",
    "has_whatsapp": true
  },
  "data": {
    "status": "active",
    "qualification": "qualified",
    "summary": "Le prospect souhaite etre rappele demain matin.",
    "sentiment": "positive",
    "meeting_booked": false
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}'

2. Availability Request Events

availability_request is used by Alvio when it needs available slots from Admvalue in order to propose a meeting to the lead.

Supported Event Names

  • AVAILABILITY_REQUESTED

2.1 AVAILABILITY_REQUESTED

Recommended Payload

{
  "event_id": "evt_01JXYZ300",
  "event_type": "availability_request",
  "event_name": "AVAILABILITY_REQUESTED",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T10:50:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": "conv_123",
    "conversation_url": "https://alvio.ai/inbox/conversations/conv_123",
    "business_phone": "+33100000000",
    "has_whatsapp": true
  },
  "data": {
    "requested_window_start": "2026-04-09T00:00:00+02:00",
    "requested_window_end": "2026-04-12T23:59:59+02:00",
    "timezone": "Europe/Paris",
    "slot_duration_minutes": 30,
    "max_slots": 5,
    "request_reason": "Le prospect souhaite planifier un rappel ou un rendez-vous."
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}

cURL Example

curl --location 'https://ws.admvalue.fr/RBT3/alvio-api/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "event_id": "evt_01JXYZ300",
  "event_type": "availability_request",
  "event_name": "AVAILABILITY_REQUESTED",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T10:50:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": "conv_123",
    "conversation_url": "https://alvio.ai/inbox/conversations/conv_123",
    "business_phone": "+33100000000",
    "has_whatsapp": true
  },
  "data": {
    "requested_window_start": "2026-04-09T00:00:00+02:00",
    "requested_window_end": "2026-04-12T23:59:59+02:00",
    "timezone": "Europe/Paris",
    "slot_duration_minutes": 30,
    "max_slots": 5,
    "request_reason": "Le prospect souhaite planifier un rappel ou un rendez-vous."
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}'

Expected Response

Because availability_request is designed to retrieve usable slots, Admvalue should return a structured response.

Success Response

{
  "request_id": "evt_01JXYZ300",
  "status": "success",
  "timezone": "Europe/Paris",
  "slots": [
    {
      "start": "2026-04-09T09:30:00+02:00",
      "end": "2026-04-09T10:00:00+02:00",
      "label": "Mercredi 9 avril - 09h30"
    },
    {
      "start": "2026-04-09T14:00:00+02:00",
      "end": "2026-04-09T14:30:00+02:00",
      "label": "Mercredi 9 avril - 14h00"
    }
  ]
}

Error Response

{
  "request_id": "evt_01JXYZ300",
  "status": "error",
  "error_code": "NO_AVAILABILITY_FOUND",
  "message": "Aucun creneau disponible sur la periode demandee."
}

3. Meeting Events

meeting is used when an appointment has been successfully booked.

Supported Event Names

  • MEETING_BOOKED

3.1 MEETING_BOOKED

Recommended Payload

{
  "event_id": "evt_01JXYZ400",
  "event_type": "meeting",
  "event_name": "MEETING_BOOKED",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T10:55:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": "conv_123",
    "conversation_url": "https://alvio.ai/inbox/conversations/conv_123",
    "business_phone": "+33100000000",
    "has_whatsapp": true
  },
  "data": {
    "meeting_type": "appointment",
    "booking_status": "confirmed",
    "start": "2026-04-09T09:30:00+02:00",
    "end": "2026-04-09T10:00:00+02:00",
    "timezone": "Europe/Paris",
    "assigned_to": "commercial_42",
    "location": "phone",
    "notes": "Le prospect prefere etre rappele sur sa ligne directe."
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}

cURL Example

curl --location 'https://ws.admvalue.fr/RBT3/alvio-api/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "event_id": "evt_01JXYZ400",
  "event_type": "meeting",
  "event_name": "MEETING_BOOKED",
  "version": "2026-04-08",
  "occurred_at": "2026-04-08T10:55:00Z",
  "lead": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "email": "jane@example.com"
  },
  "external_references": {
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  },
  "alvio": {
    "campaign_id": "cmp_123",
    "campaign_name": "Rappel prospects chauds",
    "conversation_id": "conv_123",
    "conversation_url": "https://alvio.ai/inbox/conversations/conv_123",
    "business_phone": "+33100000000",
    "has_whatsapp": true
  },
  "data": {
    "meeting_type": "appointment",
    "booking_status": "confirmed",
    "start": "2026-04-09T09:30:00+02:00",
    "end": "2026-04-09T10:00:00+02:00",
    "timezone": "Europe/Paris",
    "assigned_to": "commercial_42",
    "location": "phone",
    "notes": "Le prospect prefere etre rappele sur sa ligne directe."
  },
  "source_data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+33612345678",
    "contact_id": "crm_contact_123",
    "deal_id": "deal_456"
  }
}'

Operational Notes

  • conversation_url is included to help Admvalue teams open the relevant Alvio conversation directly.
  • source_data should contain the original payload sent by Admvalue, or a lightly sanitized version if sensitive fields need to be excluded.
  • meeting_type can be appointment, visit, or any other agreed business value.
  • availability_request is the only event type that should return an immediate structured response.
  • If needed, the contract can later be extended with stricter enums for reason, qualification, booking_status, and meeting_type.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment