WhatsApp Alerts and Chatwoot Messaging Integration

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Elian-D/ORVIAN/llms.txt

Use this file to discover all available pages before exploring further.

​

WhatsApp via Evolution API

• Sender-only — ORVIAN dispatches WhatsApp messages but does not process or listen for incoming messages. There are no webhooks or inbound message handlers.
• Asynchronous delivery — all message sending happens through SendAttendanceAlertJob, a queued job with 3 retries and a 60-second backoff. This ensures a failed Evolution API call never blocks the web request or delays attendance recording.
• Anti-spam cache — AttendanceAlertEvaluator protects against alert flooding with a weekly cache key per student per alert type (e.g., alert_absence_{student_id}_{weekOfYear} and alert_tardiness_{student_id}_{weekOfYear}, TTL 7 days). A tutor receives at most one absence alert and one tardiness alert per calendar week, regardless of how many times the evaluator runs.
• Phone normalization — Evolution API expects the phone number without the leading +. WhatsAppService::sendTextMessage() strips it automatically: $normalizedPhone = ltrim($phone, '+').

​

Setting Up Evolution API

EVOLUTION_API_URL=https://evolution.orvian.com.do
EVOLUTION_API_KEY=evolution_api_key_12345
EVOLUTION_INSTANCE_NAME=orvian-demo

php artisan orvian:demo-fire-alerts 1

​

WhatsApp Message Format

📋 *ORVIAN — Notificación de Asistencia*

Estimado/a tutor(a) *[Tutor Name]*,

Le informamos que su representado/a *[Student Full Name]* ha acumulado *[N] ausencia(s) injustificada(s)* durante el mes de [Month Year].

Le solicitamos comunicarse con la dirección del centro para coordinar el seguimiento correspondiente.

_Este mensaje es generado automáticamente por el Sistema de Gestión ORVIAN._

⏰ *ORVIAN — Aviso de Puntualidad*

Estimado/a tutor(a) *[Tutor Name]*,

Le notificamos que su representado/a *[Student Full Name]* ha registrado *[N] llegada(s) tarde* durante el mes de [Month Year].

La puntualidad es fundamental para el aprovechamiento académico. Le agradecemos su atención.

_Este mensaje es generado automáticamente por el Sistema de Gestión ORVIAN._

​

Alert Scheduling

• Scheduled at 16:00 daily in routes/console.php, with withoutOverlapping() to prevent concurrent runs if a previous execution is still processing a large school.
• Thresholds are configurable via .env:
  ALERT_ABSENCE_THRESHOLD=3
  ALERT_TARDINESS_THRESHOLD=3
  
• Manual run for a specific school:
  php artisan orvian:evaluate-attendance-alerts --school=1
  
• Manual run for all schools:
  php artisan orvian:evaluate-attendance-alerts
  

​

Setting Up Chatwoot

CHATWOOT_BASE_URL=https://chat.orvian.com.do
CHATWOOT_API_ACCESS_TOKEN=your-superadmin-api-token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_HMAC_TOKEN=your-hmac-token

​

How Chatwoot SSO Works

1. Laravel’s controller calls ChatwootService::generateIdentifierHash($user->email), which computes:
   hash_hmac('sha256', $user->email, config('communications.chatwoot.hmac_token'))
   
   This hash is computed server-side only and never exposed to the browser or JavaScript.
2. The controller builds a redirect URL:
   https://chat.orvian.com.do?email=director@school.do&identifier_hash=<computed-hash>
   
3. The browser is redirected to that URL. Chatwoot verifies the identifier_hash against its own copy of the HMAC token. If the signature matches, Chatwoot logs the user in automatically.
4. The Director lands directly in the Chatwoot inbox — no separate login is required.

​

Agent Sync

// Inside the onboarding action, after DB commit:
DB::afterCommit(function () use ($user, $chatwoot) {
    $chatwoot->syncUserAsAgent($user);
});

1. Calls findAgentByEmail() to check whether the Director already exists as an agent (prevents duplicates on re-runs).
2. If not found, calls createAgent() with the Director’s name, email, and role: 'agent'.
3. On success, stores the Chatwoot agent ID in users.preferences['chatwoot_agent_id'] for future reference.
4. Any exception thrown during the entire sync flow is caught by a try/catch block and written to the Laravel log as a ChatwootService: Error en sincronización error entry — preventing a failed Chatwoot sync from rolling back the onboarding transaction.

​

Troubleshooting