# Callbot TOPELEC — guide de déploiement

Ce callbot répond aux appels entrants sur votre numéro Twilio, comprend la demande
grâce à Claude (Anthropic), et remonte automatiquement les prospects et rendez-vous
dans Dolibarr. Il tourne en PHP + MySQL classique, sans aucun processus permanent :
compatible avec un hébergement mutualisé OVH standard.

**Modules couverts par cette version :**
1. **Identification** : le numéro appelant est recherché dans Dolibarr dès le
   début de l'appel ; accueil personnalisé si trouvé, sinon collecte des
   informations pour créer la fiche.
2. **Rendez-vous** : prise, modification et annulation, avec vérification de
   disponibilité et présentation des rendez-vous existants pour l'appelant
   identifié.
3. **Dépannage non urgent** : envoi d'un SMS avec le lien du portail de ticket
   Dolibarr (`https://pro.top-elec.eu/public/ticket/index.php?entity=1`).
4. **Urgences** : transfert immédiat vers le technicien, avec repli automatique
   (ticket urgent Dolibarr + SMS de confirmation + SMS d'alerte technicien) si
   personne ne répond.
5. **Facturation** : réponse simple (statut payé/impayé, montant dû) après
   vérification d'identité par code à usage unique envoyé par SMS ; sinon
   transfert vers la comptabilité.
6. **Orientation générale** : transfert vers un interlocuteur humain pour tout
   le reste, ou après plusieurs échanges infructueux.

## 0. Ce dont vous avez besoin avant de commencer

- Un hébergement OVH mutualisé avec **PHP 8.0+** et **une base MySQL** (les deux sont
  inclus dans les offres OVH standard).
- Le numéro Twilio Voice déjà acheté : **+33159482062**, avec la capacité **SMS**
  activée sur ce numéro (Console Twilio > Phone Numbers > votre numéro > vérifiez que
  la case "SMS" est cochée) — nécessaire pour le lien de dépannage, le code de
  vérification et les alertes technicien.
- Le **Account SID** Twilio (Console Twilio > Account, en haut de la page d'accueil),
  en plus de l'Auth Token déjà utilisé.
- Une clé API Anthropic (console.anthropic.com > API Keys).
- Dolibarr avec le module **"API REST"** activé (Accueil > Configuration > Modules >
  cherchez "Api", activez-le) et une clé API générée sur votre fiche utilisateur
  Dolibarr (onglet "API"). Le module **Ticket** doit également être activé si vous
  voulez la création automatique de tickets urgents (Configuration > Modules >
  "Ticket").
- Un sous-domaine libre, ex. `callbot.top-elec.eu`.
- Les numéros de transfert :
  - **Technicien** (urgences) : **+33746577002**, son mobile réel — c'est ce numéro
    que le callbot appelle directement. Ce mobile est par ailleurs configuré côté
    opérateur pour dévier vers +33159482062 (le menu du callbot) s'il n'est pas
    décroché lors d'un appel DIRECT (hors callbot). **Point à régler avant la mise
    en prod** : si quelqu'un appelle le callbot, que celui-ci tente de transférer
    au technicien, et que le technicien ne décroche pas, DEUX mécanismes de
    "non-réponse" entrent alors en compétition — celui du callbot
    (`urgence_dial_timeout_seconds`, 20s par défaut, qui déclenche le ticket
    urgent + les 2 SMS) et celui de l'opérateur mobile du technicien (délai avant
    déviation vers +33159482062, en général réglable dans les paramètres de
    déviation d'appel du mobile). Si la déviation opérateur se déclenche EN
    PREMIER, l'appel Twilio sera vu comme "décroché" (puisqu'il aboutit sur le
    menu du callbot) et le repli automatique (ticket + SMS) ne se déclenchera
    PAS — l'appelant retombera simplement sur le message d'accueil du callbot.
    **Réglez donc le délai de déviation de l'opérateur nettement au-dessus de
    20 secondes** (30s ou plus) pour que le repli du callbot ait toujours la
    priorité.
  - **Comptabilité** (demandes admin/factures) : renseigné par défaut au même
    numéro que ci-dessus (+33159482062) faute d'un numéro dédié communiqué —
    remplacez `comptabilite_number` dans `config.php` si vous avez une ligne
    comptabilité distincte.

## 1. Créer le sous-domaine sur OVH

Dans le [Manager OVH](https://www.ovh.com/manager/) > Web Cloud > votre hébergement :
1. Onglet **Multisite** > **Ajouter un domaine/sous-domaine**.
2. Choisissez `callbot.top-elec.eu` (ou le sous-domaine de votre choix), faites-le
   pointer vers un **nouveau dossier**, par exemple `callbot/`.
3. Une fois créé, activez le **certificat SSL Let's Encrypt gratuit** pour ce
   sous-domaine (onglet SSL/TLS) — obligatoire, Twilio exige du HTTPS. Ça peut
   prendre jusqu'à 1h pour être actif.

## 2. Déposer les fichiers

Connectez-vous en FTP/SFTP (identifiants dans Manager OVH > Hébergement >
FTP-SSH) et déposez l'arborescence de ce projet dans le dossier `callbot/` créé
à l'étape 1, de façon à obtenir :

```
callbot/                        <- dossier racine du sous-domaine
├── config.php                  <- créé à l'étape 3 (ne PAS committer/partager)
├── knowledge_base.php           <- créé à l'étape 3
├── callbot.log                  <- créé automatiquement au premier appel
├── lib/
│   ├── bootstrap.php
│   ├── db.php
│   ├── dolibarr_client.php
│   ├── llm_client.php
│   ├── session_store.php
│   ├── twilio_security.php
│   ├── twilio_sms.php
│   └── twiml.php
└── public/                      <- **c'est CE dossier qui doit être la racine web**
    ├── .htaccess
    ├── voice_incoming.php
    ├── voice_handle.php
    ├── voice_status.php
    └── voice_dial_status.php
```

**Important (sécurité) :** si votre offre OVH le permet, configurez la racine web
du sous-domaine directement sur `callbot/public/` (Manager OVH > Multisite > modifier
le sous-domaine > "Dossier"). Ainsi `config.php`, `knowledge_base.php` et les
fichiers du dossier `lib/` ne sont jamais accessibles par navigateur, même en cas
d'oubli du `.htaccess`. Si ce n'est pas possible sur votre offre, le `.htaccess`
fourni à la racine bloque déjà l'accès direct à ces fichiers.

## 3. Configuration

Sur le serveur (ou en local puis upload) :
1. Copiez `config.example.php` en `config.php`, remplissez :
   - Les identifiants MySQL (Manager OVH > Bases de données).
   - `twilio.auth_token` : Console Twilio > Account > **Auth Token** (cliquez sur
     "afficher"). Sert uniquement à vérifier que les appels au webhook viennent
     bien de Twilio.
   - `twilio.human_transfer_number` : le numéro vers lequel transférer un appel
     si besoin.
   - `anthropic.api_key` et éventuellement `anthropic.model` (vérifiez le nom
     exact du modèle disponible dans votre Console Anthropic).
   - `dolibarr.api_url` (ex: `https://pro.top-elec.eu/api/index.php`) et
     `dolibarr.api_key`.
   - `twilio.account_sid`, `twilio.sms_from_number`, `twilio.technicien_number`,
     `twilio.comptabilite_number` (nouveaux, voir section 0 ci-dessus).
   - `dolibarr.ticket_type_code_urgent` / `ticket_category_code` /
     `ticket_severity_code_urgent` : DÉJÀ VÉRIFIÉS et corrigés pour l'instance
     TOPELEC (`URGENT` / `DEP_URG` / `HIGH` — voir section 7). Si vous changez
     d'instance Dolibarr un jour, revérifiez ces codes dans Configuration >
     Dictionnaires avant de redéployer.
2. Copiez `knowledge_base.example.php` en `knowledge_base.php`, et **personnalisez
   le contenu** : horaires réels, services réels de TOPELEC, zone d'intervention,
   modèles de SMS (dépannage, code de vérification, alerte technicien), etc. C'est
   ce fichier qui donne au bot ses vraies connaissances métier — modifiable à tout
   moment sans toucher au reste du code.

## 4. Créer / mettre à jour la table de base de données

- **Nouvelle installation** : dans phpMyAdmin (Manager OVH > Bases de données >
  phpMyAdmin), sélectionnez votre base et importez le fichier `db_schema.sql`
  fourni (onglet "Importer"). Cela crée la table `callbot_calls`, qui stocke
  l'état de chaque appel en cours.
- **Installation déjà en place** (table `callbot_calls` déjà créée) : importez
  plutôt `db_migration_v2.sql`, qui ajoute uniquement les nouvelles colonnes
  nécessaires aux modules d'identification, d'authentification et de
  modification/annulation de RDV, sans toucher aux appels déjà enregistrés.

## 5. Configurer le numéro Twilio

Dans la [Console Twilio](https://console.twilio.com/) > **Phone Numbers** >
**Manage** > **Active numbers** > cliquez sur `+33159482062` :
- Section **Voice Configuration** :
  - "A call comes in" : **Webhook**, `https://callbot.top-elec.eu/voice_incoming.php`,
    méthode **HTTP POST**.
  - "Call status changes" (recommandé, pour ne perdre aucun appel même en cas de
    raccrochage impromptu) : `https://callbot.top-elec.eu/voice_status.php`,
    méthode **HTTP POST**.
- Enregistrez.

Le nouveau webhook `voice_dial_status.php` (repli automatique en cas d'urgence non
décrochée) n'a **rien à configurer dans la Console Twilio** : il est appelé
automatiquement via l'attribut `action` du `<Dial>` généré par le code lui-même.

## 6. Tester

Appelez le +33159482062 depuis votre téléphone. Vous devriez entendre le message
d'accueil défini dans `knowledge_base.php`, puis pouvoir parler normalement.

En cas de souci :
- Consultez `callbot.log` (à la racine du dossier `callbot/`, en dehors de
  `public/`) : toutes les erreurs y sont journalisées.
- Consultez l'onglet **Monitor > Logs > Calls** dans la Console Twilio : Twilio
  y affiche le code retour HTTP de vos webhooks et un aperçu du TwiML échangé,
  très utile pour diagnostiquer.
- Vérifiez la table `callbot_calls` en base : chaque appel y laisse une ligne
  avec la transcription complète (`transcript_json`), même en cas d'erreur.

## 7. Points à vérifier / adapter selon votre instance Dolibarr

L'intégration Dolibarr (`lib/dolibarr_client.php`) utilise les noms de champs
standards de l'API Dolibarr (`thirdparties`, `agendaevents`), mais certains
détails peuvent varier selon votre version et vos modules :
- `fk_pays` (pays) est mis à `1` en dur en supposant que la France a l'ID 1 dans
  votre dictionnaire pays — vérifiez sur votre instance
  (`https://votre-dolibarr/api/index.php/explorer/` liste les champs exacts,
  ou Configuration > Dictionnaires > Pays).
- Le champ `type_code: 'AC_RDV'` pour les événements d'agenda est le code
  standard Dolibarr pour un rendez-vous ; vérifiez qu'il existe bien dans
  Configuration > Dictionnaires > Types d'événements agenda.
- `default_user_id` dans `config.php` doit être l'ID d'un utilisateur Dolibarr
  valide (le propriétaire par défaut des RDV créés par le bot).
- **Module Ticket** : les codes `ticket_type_code_urgent`, `ticket_category_code`
  et `ticket_severity_code_urgent` dans `config.php` doivent exister dans les
  dictionnaires Configuration > Dictionnaires > "Type de tickets" / "Catégorisation
  du ticket" / "Niveaux de gravité" de votre instance. **Pour TOPELEC, ceci a été
  vérifié directement sur l'instance en ligne** : le dictionnaire "Catégorisation
  du ticket" est personnalisé avec des catégories propres à l'électricité (coupure,
  disjoncteur, danger, tableau, chauffe-eau, IRVE, portail...), et le code
  générique `SAV` n'existe pas du tout — d'où l'utilisation de `URGENT` (type,
  = "Dépannage urgent") et `DEP_URG` (catégorie parente, = "Dépannage urgent")
  dans `config.php`. Si vous créez de nouvelles catégories plus fines côté
  Dolibarr, vous pouvez affiner `ticket_category_code` en conséquence. Si la
  création échoue malgré tout (dictionnaires modifiés depuis), le repli d'urgence
  envoie quand même les deux SMS (confirmation appelant + alerte technicien) —
  seule la traçabilité dans Dolibarr manquera, sans jamais bloquer l'appel.
- **Factures** (`dolibarr_get_invoice_summary`) : utilise les champs standards de
  l'API `invoices` (`ref`, `date`/`datef`, `total_ttc`, `remaintopay`, `paye`).
  Si votre version Dolibarr nomme différemment le "reste à payer", ajustez la
  fonction dans `lib/dolibarr_client.php`.
- **Authentification par SMS** : le code de vérification est envoyé au numéro
  ayant appelé (`From` Twilio), qui est aussi celui utilisé pour retrouver la
  fiche Dolibarr — cohérent tant que le numéro de la fiche Dolibarr est à jour.

Si un appel à Dolibarr échoue (mauvais champ, permission manquante...), l'appel
téléphonique n'est **jamais interrompu** pour autant : l'erreur est journalisée,
et la transcription + les données collectées restent dans la table
`callbot_calls` (colonne `dolibarr_synced = 0`) pour un traitement manuel a
posteriori.

## 8. Coûts approximatifs

- **Twilio** : le numéro (~1$/mois) + le prix à la minute des appels entrants
  et de la reconnaissance vocale (`<Gather input="speech">`) — quelques centimes
  par appel selon la durée. Consultez la grille tarifaire Twilio pour la France.
- **Anthropic** : un modèle "Haiku" coûte quelques fractions de centime par
  échange conversationnel — négligeable au volume d'un standard téléphonique
  d'entreprise.
- **Hébergement / Dolibarr** : aucun coût supplémentaire, vous utilisez
  l'infrastructure OVH déjà en place.

Aucun abonnement mensuel à une plateforme tierce (Vapi, Bland.ai, etc.).

## 9. Sécurité — rappels importants

- `config.php` contient des secrets (mot de passe MySQL, clé API Anthropic, clé
  API Dolibarr, Auth Token Twilio). Ne le mettez jamais dans un dépôt Git public,
  ne l'envoyez jamais par email.
- La vérification de signature Twilio (`twilio.verify_signature: true`) doit
  **rester activée en production** : elle empêche quiconque d'appeler vos
  webhooks directement pour créer de faux prospects/RDV dans Dolibarr.
- Limitez si possible, via le pare-feu applicatif de votre hébergement (si
  disponible), l'accès à `voice_incoming.php`/`voice_handle.php`/`voice_status.php`
  aux seules plages d'IP de Twilio (documentées sur
  twilio.com/docs/sip-trunking/ip-addresses) — optionnel mais recommandé.
