# Configuration du module SMS

## Variables d'environnement requises

Pour utiliser le module SMS avec Twilio, vous devez configurer les variables d'environnement suivantes :

```bash
TWILIO_ACCOUNT_SID=your_twilio_account_sid_here
TWILIO_AUTH_TOKEN=your_twilio_auth_token_here
TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # Votre Messaging Service SID
TWILIO_WEBHOOK_URL=https://your-domain.com/twilio-webhook/receive  # Optionnel
```

**Note** : `TWILIO_WEBHOOK_URL` est optionnel. Si défini, il sera utilisé comme webhook par défaut pour tous les SMS envoyés (sauf si un `webUrl` est spécifié dans la requête).

## Comment obtenir vos identifiants Twilio

1. Connectez-vous à votre compte Twilio (https://console.twilio.com/)
2. Sur le tableau de bord, vous trouverez :
   - **Account SID** : Identifiant de votre compte
   - **Auth Token** : Token d'authentification (cliquez sur "view" pour le révéler)
3. Pour obtenir un Messaging Service SID :
   - Allez dans **Messaging** > **Services** > **Create Messaging Service**
   - Ou utilisez un Messaging Service existant
   - Le SID commence par `MG` (ex: `MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
   - Assurez-vous d'avoir au moins un numéro de téléphone associé au Messaging Service
4. Copiez ces valeurs et ajoutez-les à votre fichier `.env`

## Utilisation du module SMS

### Endpoints disponibles

- `POST /sms/send` - Envoyer un SMS unique
- `POST /sms/send-bulk` - Envoyer plusieurs SMS

### Exemple de requête pour envoyer un SMS

```json
{
  "to": "+33123456789",
  "message": "Hello! This is a test SMS from Twilio.",
  "sender": "MyApp",
  "webUrl": "https://your-domain.com/twilio-webhook/receive"
}
```

**Paramètres :**
- `to` : Numéro de téléphone (requis, format E.164 recommandé, ex: +33123456789)
- `message` : Contenu du SMS (requis)
- `sender` : Nom de l'expéditeur (optionnel, non utilisé par Twilio mais conservé pour compatibilité)
- `webUrl` : URL du webhook pour suivre les événements (optionnel, peut aussi être défini via `TWILIO_WEBHOOK_URL`)

**Note** : Le paramètre `sender` est conservé pour compatibilité mais n'est pas utilisé par Twilio. Les SMS sont envoyés via le Messaging Service défini dans `TWILIO_MESSAGING_SERVICE_SID`.

### Exemple de requête pour envoyer plusieurs SMS

```json
{
  "smsList": [
    {
      "to": "+33123456789",
      "message": "Hello! This is a test SMS from Twilio.",
      "sender": "MyApp"
    },
    {
      "to": "+33987654321",
      "message": "Another test SMS.",
      "sender": "MyApp"
    }
  ]
}
```

## Configuration du fichier .env

Créez un fichier `.env` à la racine du dossier `server` avec le contenu suivant :

```bash
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_WEBHOOK_URL=https://your-domain.com/twilio-webhook/receive
NODE_ENV=development
PORT=3000
```

## Format des numéros de téléphone

Twilio recommande d'utiliser le format E.164 pour les numéros de téléphone :
- Format : `+[code pays][numéro]`
- Exemple : `+33123456789` (France), `+1234567890` (États-Unis)

## Avantages du Messaging Service

L'utilisation d'un Messaging Service au lieu d'un numéro de téléphone unique offre plusieurs avantages :
- **Meilleure délivrabilité** : Twilio peut automatiquement sélectionner le meilleur numéro disponible
- **Gestion de plusieurs numéros** : Vous pouvez associer plusieurs numéros au même service
- **Fallback automatique** : Si un numéro est bloqué, Twilio utilise automatiquement un autre numéro
- **Configuration centralisée** : Gestion des webhooks, des règles de routage, etc. au niveau du service

## Webhooks Twilio

Le module SMS est intégré avec le module **TwilioWebhook** qui permet de suivre le statut de chaque message envoyé.

### Configuration

Pour activer le suivi des webhooks, configurez `TWILIO_WEBHOOK_URL` dans votre fichier `.env` :

```bash
TWILIO_WEBHOOK_URL=https://your-domain.com/twilio-webhook/receive
```

Cette URL sera utilisée comme webhook par défaut pour tous les SMS envoyés (sauf si un `webUrl` est spécifié dans la requête).

### Événements suivis

Si vous configurez un webhook URL, Twilio enverra des notifications pour les événements suivants :
- `queued` : Le message est en file d'attente
- `sent` : Le message a été envoyé
- `delivered` : Le message a été livré
- `failed` : L'envoi a échoué
- `undelivered` : Le message n'a pas pu être livré
- `receiving` : Le message est en cours de réception (messages entrants)
- `received` : Le message a été reçu (messages entrants)
- `read` : Le message a été lu (messages entrants)

### Consultation des événements

Le module TwilioWebhook stocke tous les événements en base de données et fournit plusieurs endpoints pour les consulter :

- `GET /twilio-webhook/events` - Tous les événements
- `GET /twilio-webhook/events/message/:messageSid` - Événements pour un message spécifique
- `GET /twilio-webhook/events/type/:eventType` - Événements par type
- `GET /twilio-webhook/events/phone/:phoneNumber` - Événements pour un numéro de téléphone

Pour plus de détails, consultez la documentation du module TwilioWebhook : [twilio-webhook/README.md](../twilio-webhook/README.md)

**Note importante** : Contrairement au système Brevo précédent, ce module ne gère **pas** les retries d'envoi de SMS. Les webhooks servent uniquement à suivre le statut des messages.