Composants (I/O & métriques)

Introduction¶

Cette page constitue la source unique pour les interfaces (I/O) et métriques de chaque composant SalamBot. Elle détaille les entrées, sorties, dépendances et indicateurs de performance pour faciliter l'intégration et le monitoring. Pour l'architecture globale et les flux, consulter Architecture.

Conventions globales I/O¶

Schema version: schema_version = "1.0"
Casing: snake_case pour toutes les clés
Horodatage: timestamp en UTC RFC3339 (ex: 2025-08-14T10:00:00Z)
Locale: BCP-47 (ex: fr-MA, ar, en)
Taille: text_max_len = 2000 (entrée utilisateur), attachments_total_max = 20MB, max_attachment_count = 10

Envelope I/O commun (toutes API internes)¶

Toutes les communications entre composants utilisent un envelope standardisé avec les champs obligatoires suivants :

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "facebook",
  "message_id": "msg_123",
  "correlation_id": "corr_abc",
  "timestamp": "2025-08-14T10:00:00Z",
  "locale": "fr-MA",
  "data": {
    /* payload spécifique au composant */
  }
}

Clés d'envelope¶

Clé	Description
schema_version	version de schéma (ex: "1.0")
tenant	identifiant client
channel	facebook / whatsapp / webchat / email / system / admin / chrome
message_id	id source
correlation_id	id de traçage bout-à-bout
timestamp	RFC3339
locale	BCP-47 (ex: fr-MA, ar, en)

Flux de données inter-composants¶

Le diagramme suivant illustre la circulation des messages JSON standardisés entre les composants :

sequenceDiagram
    participant U as Utilisateur
    participant GW as API Gateway
    participant ORC as Orchestrateur
    participant NLU as NLU
    participant RAG as RAG
    participant LLM as LLM Router
    participant ADM as Admin

    U->>GW: Message utilisateur
    Note over GW: Envelope JSON<br/>+ validation

    GW->>ORC: {schema_version, tenant,<br/>channel, message_id,<br/>correlation_id, data}

    ORC->>NLU: {text, lang}
    NLU->>ORC: {intent, entities,<br/>confidence}

    alt Context nécessaire
        ORC->>RAG: {query, filters}
        RAG->>ORC: {passages, ids,<br/>relevance_score}
    end

    ORC->>ADM: {tenant}
    ADM->>ORC: {policies, branding}

    ORC->>LLM: {prompt, context,<br/>policies}
    LLM->>ORC: {reply_text, tokens,<br/>confidence}

    ORC->>GW: {reply_text, metadata}
    GW->>U: Réponse finale

    Note over ORC,LLM: Tous les échanges<br/>utilisent l'envelope<br/>JSON standardisé

Résumé des composants¶

Composant	Entrée (mots-clés)	Sortie (mots-clés)	Dépendances
NLU	text, lang	intent, entities	-
Recherche (RAG)	query, filters	passages, ids	Qdrant
LLM Router	prompt, context	reply_text, confidence	vLLM/Ollama
Social Ingestion	webhook	message, meta	Gateway
Incident/Broadcast	trigger	ticket, event	Postgres
Escalade/Ticketing	incident, msg	ticket_id, status	Helpdesk
Admin & Branding	policies	ack	Postgres
Observabilité	spans, logs	traces	OTel
Extension Chrome	selection	suggestion	Router
Webchat	message	reply_text	Router

Architecture des composants¶

Le diagramme suivant illustre les relations et flux de données entre les composants principaux de SalamBot :

graph TB
    %% Couche d'entrée
    WH[Webhooks Sociaux] --> GW[API Gateway]
    WC[Webchat] --> GW
    CHR[Extension Chrome] --> GW

    %% Orchestration centrale
    GW --> ORC[Orchestrateur]

    %% Services de traitement
    ORC --> NLU[NLU & Linguistique]
    ORC --> RAG[Recherche RAG]
    ORC --> LLM[LLM Router]
    ORC --> ADM[Admin & Branding]

    %% Services opérationnels
    ORC --> INC[Incident/Broadcast]
    ORC --> ESC[Escalade/Ticketing]

    %% Stockage et cache
    NLU --> CACHE[(Cache Redis)]
    RAG --> KB[(Knowledge Base)]
    ADM --> DB[(PostgreSQL)]
    INC --> DB
    ESC --> DB

    %% Services externes
    LLM --> EXT[LLM Externes]
    ESC --> HELP[Helpdesk Externe]

    %% Observabilité
    ORC --> OBS[Observabilité]
    NLU --> OBS
    RAG --> OBS
    LLM --> OBS

    %% Styling
    classDef entry fill:#e1f5fe
    classDef core fill:#f3e5f5
    classDef storage fill:#e8f5e8
    classDef external fill:#fff3e0

    class WH,WC,CHR entry
    class GW,ORC,NLU,RAG,LLM,ADM,INC,ESC core
    class CACHE,KB,DB storage
    class EXT,HELP,OBS external

Énumérations officielles¶

Clé	Valeurs
channel	facebook, whatsapp, webchat, email, system, admin, chrome
language	fr, ar, en, darija_arabizi, darija_arabic
sentiment	positive, neutral, negative
urgency	low, medium, high

NLU & Linguistique¶

Rôle Analyse linguistique des messages entrants pour extraire l'intention utilisateur et les entités nommées. Supporte le français et l'arabe avec détection automatique.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "facebook",
  "message_id": "msg_123",
  "correlation_id": "corr_abc",
  "timestamp": "2025-08-14T10:00:00Z",
  "data": {
    "text": "Je veux annuler ma commande",
    "lang": "fr"
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "facebook",
  "message_id": "msg_123",
  "correlation_id": "corr_abc",
  "timestamp": "2025-08-14T10:00:00Z",
  "data": {
    "intent": "cancel_order",
    "confidence": 0.95,
    "entities": [{ "type": "order", "value": "commande" }]
  }
}

Exemples

// Request
{
  "schema_version": "1.0",
  "tenant": "shop",
  "channel": "whatsapp",
  "message_id": "msg_456",
  "correlation_id": "corr_def",
  "timestamp": "2025-08-14T10:01:00Z",
  "data": {
    "text": "أريد إلغاء طلبي",
    "lang": "ar"
  }
}

// Response
{
  "schema_version": "1.0",
  "tenant": "shop",
  "channel": "whatsapp",
  "message_id": "msg_456",
  "correlation_id": "corr_def",
  "timestamp": "2025-08-14T10:01:00Z",
  "data": {
    "intent": "cancel_order",
    "confidence": 0.92,
    "entities": []
  }
}

Dépendances

Modèles linguistiques locaux
Configuration tenant (langues supportées)

Métriques

KPI	Clé	Cible
latence p95	nlu_p95_ms	≤ 200
taux succès	nlu_success_rate	≥ 98%
confiance moyenne	nlu_confidence_avg	≥ 0.8

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation longueur texte (≤ 2000 chars)
Timeout 5s par requête
Fallback intent "unknown" si confidence < 0.5
Masquage PII automatique (emails, téléphones)

Événements

nlu.analyzed (intent détecté)

Recherche (RAG Retrieval)¶

Rôle Recherche contextuelle dans la base de connaissances via embeddings sémantiques. Filtre par tenant et re-rank les résultats selon la pertinence.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_789",
  "correlation_id": "corr_ghi",
  "timestamp": "2025-08-14T10:02:00Z",
  "data": {
    "query": "politique de remboursement",
    "filters": { "category": "faq" },
    "limit": 5
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_789",
  "correlation_id": "corr_ghi",
  "timestamp": "2025-08-14T10:02:00Z",
  "data": {
    "passages": ["Les remboursements sont..."],
    "ids": ["doc_123"],
    "scores": [0.89]
  }
}

Exemples

// Request
{
  "schema_version": "1.0",
  "tenant": "shop",
  "channel": "facebook",
  "message_id": "msg_101",
  "correlation_id": "corr_jkl",
  "timestamp": "2025-08-14T10:03:00Z",
  "data": {
    "query": "horaires ouverture",
    "filters": {}
  }
}

// Response
{
  "schema_version": "1.0",
  "tenant": "shop",
  "channel": "facebook",
  "message_id": "msg_101",
  "correlation_id": "corr_jkl",
  "timestamp": "2025-08-14T10:03:00Z",
  "data": {
    "passages": ["Ouvert 9h-18h du lundi au vendredi"],
    "scores": [0.92]
  }
}

Dépendances

Qdrant (base vectorielle)
Modèle embedding (sentence-transformers)
Index par tenant

Métriques

KPI	Clé	Cible
latence p95	rag_p95_ms	≤ 500
taux succès	rag_success_rate	≥ 99%
pertinence moyenne	rag_relevance_avg	≥ 0.7
hit rate	rag_hit_rate	≥ 85%

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation query non vide
Timeout 3s par recherche
Limite 50 résultats max
Isolation stricte par tenant

Événements

rag.retrieved (requête traitée)

LLM Router & Guardrails¶

Rôle Sélection et routage vers le modèle LLM approprié selon le contexte. Applique les garde-fous de sécurité et génère les réponses finales.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_202",
  "correlation_id": "corr_mno",
  "timestamp": "2025-08-14T10:04:00Z",
  "data": {
    "prompt": "Réponds à: {user_msg}",
    "context": ["passage1", "passage2"],
    "model": "auto"
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_202",
  "correlation_id": "corr_mno",
  "timestamp": "2025-08-14T10:04:00Z",
  "data": {
    "reply_text": "Voici la réponse...",
    "model_used": "llama3-8b",
    "tokens": 45,
    "confidence": 0.87,
    "filtered": false
  }
}

Exemples

// Request
{
  "schema_version": "1.0",
  "tenant": "shop",
  "channel": "whatsapp",
  "message_id": "msg_303",
  "correlation_id": "corr_pqr",
  "timestamp": "2025-08-14T10:05:00Z",
  "data": {
    "prompt": "Explique la garantie",
    "context": ["Garantie 2 ans"]
  }
}

// Response
{
  "schema_version": "1.0",
  "tenant": "shop",
  "channel": "whatsapp",
  "message_id": "msg_303",
  "correlation_id": "corr_pqr",
  "timestamp": "2025-08-14T10:05:00Z",
  "data": {
    "reply_text": "Notre garantie couvre...",
    "tokens": 32,
    "confidence": 0.91,
    "filtered": false
  }
}

Dépendances

vLLM/Ollama (serveurs de modèles)
Règles de filtrage par tenant
Templates de prompts

Métriques

KPI	Clé	Cible
latence p95	llm_p95_ms	≤ 2000
taux succès	llm_success_rate	≥ 97%
tokens/sec	llm_throughput	≥ 50
taux filtrage	llm_filter_rate	≤ 5%

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation prompt ≤ 4000 tokens
Timeout 30s par génération
Filtrage contenu inapproprié
Rate limiting par tenant

Événements

router.generated (réponse créée)

Rôle Ingestion et normalisation des messages depuis les canaux sociaux. Gère les webhooks, validation et routage vers l'orchestrateur.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "facebook",
  "message_id": "msg_404",
  "correlation_id": "corr_stu",
  "timestamp": "2025-08-14T10:06:00Z",
  "data": {
    "webhook_data": {"object": "page", "entry": [...]},
    "signature": "sha256=..."
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "facebook",
  "message_id": "msg_404",
  "correlation_id": "corr_stu",
  "timestamp": "2025-08-14T10:06:00Z",
  "data": {
    "message": "Bonjour, j'ai un problème",
    "meta": { "user_id": "123", "timestamp": 1234567890 }
  }
}

Exemples

// Request (WhatsApp)
{
  "tenant": "shop",
  "channel": "whatsapp",
  "message_id": "msg_505",
  "correlation_id": "corr_vwx",
  "timestamp": "2025-08-14T10:07:00Z",
  "data": {
    "webhook_data": {"messages": [{"text": {"body": "Hello"}}]}
  }
}

// Response
{
  "tenant": "shop",
  "channel": "whatsapp",
  "message_id": "msg_505",
  "correlation_id": "corr_vwx",
  "timestamp": "2025-08-14T10:07:00Z",
  "data": {
    "message": "Hello",
    "meta": {"user_id": "wa_456"}
  }
}

Dépendances

API Gateway (authentification)
Configuration webhooks par tenant
Mapping canaux → tenants

Métriques

KPI	Clé	Cible
latence p95	ingestion_p95_ms	≤ 300
taux succès	ingestion_success_rate	≥ 99.5%
messages/min	ingestion_throughput	≥ 1000

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation signature webhook
Timeout 10s par traitement
Déduplication messages
Rate limiting par canal

Événements

social.ingested (message reçu)

Incident/Broadcast¶

Rôle Gestion des incidents système et diffusion de messages en masse. Crée des tickets automatiques et notifie les équipes concernées.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "system",
  "message_id": "msg_606",
  "correlation_id": "corr_yz1",
  "timestamp": "2025-08-14T10:08:00Z",
  "data": {
    "trigger": "high_error_rate",
    "severity": "critical",
    "details": { "service": "llm", "error_rate": 15 }
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "system",
  "message_id": "msg_606",
  "correlation_id": "corr_yz1",
  "timestamp": "2025-08-14T10:08:00Z",
  "data": {
    "ticket_id": "INC-2024-001",
    "event": "incident_created",
    "status": "open",
    "assignee": "ops-team"
  }
}

Exemples

// Request (Broadcast)
{
  "tenant": "shop",
  "channel": "system",
  "message_id": "msg_707",
  "correlation_id": "corr_234",
  "timestamp": "2025-08-14T10:09:00Z",
  "data": {
    "trigger": "maintenance",
    "message": "Maintenance prévue 14h-16h"
  }
}

// Response
{
  "tenant": "shop",
  "channel": "system",
  "message_id": "msg_707",
  "correlation_id": "corr_234",
  "timestamp": "2025-08-14T10:09:00Z",
  "data": {
    "event": "broadcast_sent",
    "recipients": 1250,
    "status": "delivered"
  }
}

Dépendances

PostgreSQL (tickets, historique)
Système de notification (email, Slack)
Règles d'escalade par tenant

Métriques

KPI	Clé	Cible
temps résolution	incident_mttr_hours	≤ 4
taux auto-résolution	incident_auto_resolve	≥ 60%
couverture broadcast	broadcast_delivery_rate	≥ 98%

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation seuils d'alerte
Prévention spam (max 1 incident/5min)
Approbation manuelle pour broadcasts critiques

Événements

incident.opened

Escalade & Ticketing¶

Rôle Transfert vers support humain quand l'IA ne peut pas répondre. Crée et suit les tickets dans le système helpdesk intégré.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_808",
  "correlation_id": "corr_567",
  "timestamp": "2025-08-14T10:10:00Z",
  "data": {
    "incident": "Problème complexe non résolu",
    "user_context": {"id": "user_123", "history": [...]},
    "priority": "high"
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_808",
  "correlation_id": "corr_567",
  "timestamp": "2025-08-14T10:10:00Z",
  "data": {
    "ticket_id": "TKT-2024-456",
    "status": "assigned",
    "agent": "sarah.martin",
    "eta_hours": 2
  }
}

Exemples

// Request
{
  "tenant": "shop",
  "channel": "facebook",
  "message_id": "msg_909",
  "correlation_id": "corr_890",
  "timestamp": "2025-08-14T10:11:00Z",
  "data": {
    "incident": "Remboursement urgent",
    "priority": "critical"
  }
}

// Response
{
  "tenant": "shop",
  "channel": "facebook",
  "message_id": "msg_909",
  "correlation_id": "corr_890",
  "timestamp": "2025-08-14T10:11:00Z",
  "data": {
    "ticket_id": "TKT-789",
    "status": "escalated",
    "eta_hours": 1
  }
}

Dépendances

TODO: connecter Zendesk/Freshdesk
PostgreSQL (suivi interne)
Règles de routage par expertise

Métriques

KPI	Clé	Cible
temps première réponse	ticket_frt_hours	≤ 1
taux résolution J+1	ticket_resolve_24h	≥ 80%
satisfaction client	ticket_csat_avg	≥ 4.2

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation contexte utilisateur
Prévention tickets dupliqués
Escalade automatique si SLA dépassé

Événements

ticket.created

Admin & Branding¶

Rôle Configuration des politiques tenant, personnalisation de l'interface et gestion des paramètres de branding par organisation.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "admin",
  "message_id": "msg_010",
  "correlation_id": "corr_abc",
  "timestamp": "2025-08-14T10:12:00Z",
  "data": {
    "policies": {
      "max_tokens": 1000,
      "allowed_models": ["llama3"],
      "branding": { "logo_url": "https://...", "colors": "#123456" }
    }
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "admin",
  "message_id": "msg_010",
  "correlation_id": "corr_abc",
  "timestamp": "2025-08-14T10:12:00Z",
  "data": {
    "ack": "policies_updated",
    "version": "v2.1",
    "applied_at": "2025-08-14T10:30:00Z"
  }
}

Exemples

// Request
{
  "tenant": "shop",
  "channel": "admin",
  "message_id": "msg_111",
  "correlation_id": "corr_def",
  "timestamp": "2025-08-14T10:13:00Z",
  "data": {
    "policies": {"rate_limit": 100, "lang": ["fr", "ar"]}
  }
}

// Response
{
  "tenant": "shop",
  "channel": "admin",
  "message_id": "msg_111",
  "correlation_id": "corr_def",
  "timestamp": "2025-08-14T10:13:00Z",
  "data": {
    "ack": "config_saved",
    "restart_required": false
  }
}

Dépendances

PostgreSQL (configuration persistante)
Cache Redis (politiques actives)
CDN (assets de branding)

Métriques

KPI	Clé	Cible
temps application config	admin_apply_ms	≤ 500
taux succès	admin_success_rate	≥ 99%
cohérence cache	admin_cache_hit	≥ 95%

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation schéma configuration
Sauvegarde avant modification
Rollback automatique si erreur

Événements

admin.policy_updated

Observabilité¶

Rôle Collecte et corrélation des traces, métriques et logs distribués. Fournit la visibilité end-to-end sur les performances système.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "system",
  "message_id": "msg_212",
  "correlation_id": "corr_ghi",
  "timestamp": "2025-08-14T10:14:00Z",
  "data": {
    "spans": [{ "trace_id": "abc123", "operation": "nlu.analyze" }],
    "logs": [{ "level": "error", "message": "Timeout" }]
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "system",
  "message_id": "msg_212",
  "correlation_id": "corr_ghi",
  "timestamp": "2025-08-14T10:14:00Z",
  "data": {
    "traces": [{ "trace_id": "abc123", "duration_ms": 1250 }],
    "alerts": ["high_latency_detected"]
  }
}

Exemples

// Request
{
  "tenant": "shop",
  "channel": "system",
  "message_id": "msg_313",
  "correlation_id": "corr_jkl",
  "timestamp": "2025-08-14T10:15:00Z",
  "data": {
    "spans": [{"operation": "llm.generate", "duration_ms": 3000}]
  }
}

// Response
{
  "tenant": "shop",
  "channel": "system",
  "message_id": "msg_313",
  "correlation_id": "corr_jkl",
  "timestamp": "2025-08-14T10:15:00Z",
  "data": {
    "traces": ["trace_xyz"],
    "alerts": ["sla_breach"]
  }
}

Dépendances

OpenTelemetry Collector
Jaeger/Tempo (traces)
Prometheus (métriques)

Métriques

KPI	Clé	Cible
ingestion rate	otel_spans_per_sec	≥ 10000
rétention traces	otel_retention_days	7
alertes/jour	otel_alerts_daily	≤ 50

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Sampling adaptatif (1-100%)
Limite taille span (1MB)
Anonymisation données sensibles

Événements

obs.alert_triggered

Extension Chrome¶

Rôle Extension navigateur pour suggestions contextuelles lors de la rédaction. Analyse le texte sélectionné et propose des améliorations via l'IA.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "chrome",
  "message_id": "msg_414",
  "correlation_id": "corr_mno",
  "timestamp": "2025-08-14T10:16:00Z",
  "data": {
    "selection": "Merci pour votre retour",
    "context": "email_reply",
    "lang": "fr"
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "chrome",
  "message_id": "msg_414",
  "correlation_id": "corr_mno",
  "timestamp": "2025-08-14T10:16:00Z",
  "data": {
    "suggestion": "Merci pour votre précieux retour",
    "confidence": 0.87,
    "type": "enhancement"
  }
}

Exemples

// Request
{
  "tenant": "shop",
  "channel": "chrome",
  "message_id": "msg_515",
  "correlation_id": "corr_pqr",
  "timestamp": "2025-08-14T10:17:00Z",
  "data": {
    "selection": "Je suis pas content",
    "context": "customer_service"
  }
}

// Response
{
  "tenant": "shop",
  "channel": "chrome",
  "message_id": "msg_515",
  "correlation_id": "corr_pqr",
  "timestamp": "2025-08-14T10:17:00Z",
  "data": {
    "suggestion": "Je ne suis pas satisfait",
    "type": "tone_improvement"
  }
}

Dépendances

LLM Router (génération suggestions)
API Gateway (authentification)
Cache suggestions fréquentes

Métriques

KPI	Clé	Cible
latence suggestion	chrome_p95_ms	≤ 800
taux adoption	chrome_accept_rate	≥ 40%
utilisateurs actifs	chrome_dau	croissance

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation longueur sélection (≤ 500 chars)
Timeout 5s par suggestion
Respect vie privée (pas de stockage)

Événements

ext.suggestion_proposed

Webchat¶

Rôle Widget de chat intégrable sur sites web. Interface temps réel avec WebSocket pour conversations fluides avec l'IA.

Interfaces (I/O)

Entrée

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_616",
  "correlation_id": "corr_stu",
  "timestamp": "2025-08-14T10:18:00Z",
  "data": {
    "message": "Bonjour, j'ai une question",
    "session_id": "sess_789",
    "widget_config": { "theme": "dark" }
  }
}

Sortie

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "msg_616",
  "correlation_id": "corr_stu",
  "timestamp": "2025-08-14T10:18:00Z",
  "data": {
    "reply_text": "Bonjour ! Je suis là pour vous aider.",
    "typing_indicator": false,
    "suggestions": ["Voir nos produits", "Contacter support"]
  }
}

Exemples

// Request
{
  "tenant": "shop",
  "channel": "webchat",
  "message_id": "msg_717",
  "correlation_id": "corr_vwx",
  "timestamp": "2025-08-14T10:19:00Z",
  "data": {
    "message": "Vos horaires ?",
    "session_id": "sess_123"
  }
}

// Response
{
  "tenant": "shop",
  "channel": "webchat",
  "message_id": "msg_717",
  "correlation_id": "corr_vwx",
  "timestamp": "2025-08-14T10:19:00Z",
  "data": {
    "reply_text": "Nous sommes ouverts 9h-18h",
    "suggestions": ["Nous contacter"]
  }
}

Dépendances

LLM Router (génération réponses)
WebSocket server (temps réel)
Session store (contexte conversation)

Métriques

KPI	Clé	Cible
latence réponse	webchat_p95_ms	≤ 1500
taux résolution	webchat_resolve_rate	≥ 75%
sessions/jour	webchat_sessions_daily	croissance
durée moyenne	webchat_duration_avg	3-5 min

Erreurs & garde-fous

PII masking (policy tenant) ; Retention: 30–90 jours (configurable)
invalid_input, rate_limited, timeout, upstream_error, permission_denied
Validation message ≤ 1000 chars
Rate limiting par IP
Détection spam/abus
Escalade automatique si échec

Événements

webchat.message_sent

Mapping erreurs ↔ HTTP¶

erreur	http
invalid_input	400
unauthorized	401
permission_denied	403
rate_limited	429
internal_error	500
upstream_error	502
timeout	504

Exemple bout-à-bout (NLU → RAG → Router)¶

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "facebook",
  "message_id": "msg_9fa2",
  "correlation_id": "corr_42",
  "timestamp": "2025-08-14T10:00:00Z",
  "data": {
    "user_text": "salam 3afak fin n9der nshouf la facture ?"
  }
}

NLU → data: { "language":"darija_arabizi", "intent":"billing_view", "entities":[{"type":"account_id","value":"TODO"}], "sentiment":"neutral", "urgency":"low", "confidence":0.86 }

RAG → data: { "query":"facture consultation", "filters":{"tenant":"acme"}, "passages":[{"id":"kb_12","score":0.82}], "citations":[{"id":"kb_12","loc":"#voir-facture"}] }

Router → data: { "reply_text":"يمكنك الاطلاع على فاتورتك عبر ... / Vous pouvez consulter votre facture via ...", "language":"fr", "confidence":0.79 }

Composants (I/O & métriques)

Introduction¶

Conventions globales I/O¶

Envelope I/O commun (toutes API internes)¶

Clés d'envelope¶

Flux de données inter-composants¶

Résumé des composants¶

Architecture des composants¶

Énumérations officielles¶

NLU & Linguistique¶

Recherche (RAG Retrieval)¶

LLM Router & Guardrails¶

Social Ingestion (Facebook/WhatsApp/Webhook)¶

Incident/Broadcast¶

Escalade & Ticketing¶

Admin & Branding¶

Observabilité¶

Extension Chrome¶

Webchat¶

Mapping erreurs ↔ HTTP¶

Exemple bout-à-bout (NLU → RAG → Router)¶

Références croisées¶