# EnvoiSMS - Morocco Developer SMS & WhatsApp Platform

> Premium localized CPaaS platform providing high-availability developer APIs for SMS and WhatsApp messaging in Morocco. Designed for high-volume transactions, dual-channel cascade routing, OTP verification sessions, and localized Moroccan payment gateways.

---

## Navigation & Core Resources

- [Home Page](https://envoisms.ma)
- [B2B Customer Dashboard](https://envoisms.ma/dashboard)
- [API Developer Documentation](https://envoisms.ma/en/docs)
- [MAD / EUR Pricing & SMS Packages](https://envoisms.ma/en/pricing)
- [API OpenAPI / Postman Specs](https://api.envoisms.ma/docs/api/openapi.yaml)
- [OTP SMS Morocco 2FA](https://envoisms.ma/fr/otp-sms-maroc)
- [Bulk SMS Morocco](https://envoisms.ma/fr/envoi-sms-masse-maroc)
- [WhatsApp Business API Morocco](https://envoisms.ma/fr/whatsapp-business-api-maroc)
- [Twilio Alternative Morocco Comparison](https://envoisms.ma/fr/comparatifs/twilio-alternative-maroc)
- [Terms & Conditions](https://envoisms.ma/en/legal/terms)
- [Privacy Policy](https://envoisms.ma/en/legal/privacy)
- [Full Developer Deep Ingestion Guide](https://envoisms.ma/llms-full.txt)

---

## Platform Features

### 1. Unified Messaging API
A single REST endpoint handles both high-speed promotional SMS and secure transactional WhatsApp delivery:
- **Automatic Fallback Cascade**: Keep `ENABLE_MULTI_CHANNEL_CASCADE=false` (gated) until a successful WhatsApp canary passes, then fallback to high-deliverability SMS automatically when a WhatsApp session is unreachable.
- **Moroccan Carrier Support**: Directly interfaces with IAM (Maroc Telecom), Orange Maroc, and Inwi networks with automated prefix normalization (`+2126` and `+2127`).

### 2. High-Fidelity OTP Verification Session Lifecycle
Robust verification API (`/v1/verify`) that handles secure one-time passcode sending, rate limiting, and stateful validation checks:
- Standardized OTP layouts in French, English, and Arabic.
- Stateful verification windows (5-minute TTL).

### 3. Flexible Billing & Top-Up Systems
Built-in support for localized and international payment networks:
- **Stripe**: Instant card processing using secure checkout sessions (requires `STRIPE_SECRET_KEY` Worker secret).
- **CashPlus**: Structured reference-code invoice generation for local counter payouts.
- **Bank Transfer**: Instant invoicing including RIB, IBAN, SWIFT, and manual reconciliation matching.

---

## Quick API Reference

All requests must be sent to the API Gateway at `https://api.envoisms.ma` (or fallback at `https://smsmaroc-api.a-naouri.workers.dev`). Authorize requests by providing an `Authorization: Bearer <API_KEY>` header.

### Send Message
`POST /v1/messages`
```json
{
  "to": "+212612345678",
  "message": "Votre code de validation EnvoiSMS est 849302.",
  "channel": "sms" 
}
```

### Send Bulk Messages
`POST /v1/messages/bulk`
```json
{
  "recipients": ["+212612345678", "+212687654321"],
  "message": "Offre Flash: Recevez 10% de crédit gratuit sur EnvoiSMS !",
  "channel": "sms"
}
```

### Trigger OTP Session
`POST /v1/verify/send`
```json
{
  "to": "+212612345678",
  "brand": "EnvoiSMS",
  "codeLength": 6,
  "locale": "fr"
}
```

### Verify OTP Passcode
`POST /v1/verify/check`
```json
{
  "to": "+212612345678",
  "code": "849302"
}
```

---

## System Integration Guides

- **Developer Onboarding Runbook**: [Docs Guide](https://envoisms.ma/en/blog/morocco-sms-api-integration-guide)
- **Status Monitoring**: Live service status, API telemetry, and queue metrics are accessible on the dashboard at `/dashboard/overview`.