voip announcement

apps/notifications/admin.py

@@ -1,7 +1,17 @@
 from django.contrib import admin
-from .models import NotificationJob,NotificationPolicy,SMSTemplate
+from .models import AnnouncementJob,NotificationJob,NotificationPolicy,SMSTemplate
 @admin.register(NotificationJob)
 class NotificationJobAdmin(admin.ModelAdmin): list_display=("channel","event_type","status","attempts","provider_status_code","delivery_status","delivery_retry_source","provider_message_id","created_at"); list_filter=("channel","status","delivery_status","delivery_is_final"); readonly_fields=("provider_message_id","provider_status_code","delivery_status_code","delivery_description","delivery_checked_at","delivery_is_final","delivery_retry_source","dedupe_key","created_at","sent_at")
+
+@admin.register(AnnouncementJob)
+class AnnouncementJobAdmin(admin.ModelAdmin):
+    list_display = ("message", "status", "attempts", "next_attempt_at", "sent_at")
+    list_filter = ("status",)
+    search_fields = ("message__ticket__ticket_number", "message__ticket__customer__mobile")
+    readonly_fields = ("message", "status", "attempts", "next_attempt_at", "idempotency_key", "last_error", "created_at", "sent_at")
+
+    def has_add_permission(self, request):
+        return False
 @admin.register(SMSTemplate)
 class SMSTemplateAdmin(admin.ModelAdmin):
     list_display=("event_type","unit","title","is_active","updated_at")

apps/notifications/announcement_worker.py

@@ -0,0 +1,94 @@
+"""Process due announcement calls from the notification worker."""
+import logging
+from datetime import timedelta
+
+import requests
+from django.db import transaction
+from django.utils import timezone
+
+from apps.core.models import VoipConfiguration
+from apps.integrations.announcements import AnnouncementRejected, place_announcement_call
+from apps.messaging.models import MessageReadReceipt
+from .models import AnnouncementJob
+
+logger = logging.getLogger(__name__)
+MAX_ATTEMPTS = 3
+
+
+def _failure_code(exc):
+    if isinstance(exc, requests.Timeout):
+        return "service_timeout"
+    if isinstance(exc, requests.ConnectionError):
+        return "service_unreachable"
+    if isinstance(exc, requests.HTTPError):
+        return "service_http_error"
+    if isinstance(exc, AnnouncementRejected):
+        return "service_rejected"
+    if isinstance(exc, ValueError):
+        return "invalid_service_response"
+    return "unexpected_error"
+
+
+def _cancellation_reason(job, configuration):
+    message = job.message
+    customer = message.ticket.customer
+    if message.is_internal or message.deleted_at or message.author.account_type != "STAFF":
+        return "message_unavailable"
+    if MessageReadReceipt.objects.filter(message=message, user=customer).exists():
+        return "customer_read"
+    if message.ticket.ticket_messages.filter(author=customer, created_at__gt=message.created_at, is_internal=False).exists():
+        return "customer_replied"
+    if not customer.is_active or not customer.local_mobile:
+        return "customer_mobile_unavailable"
+    if not configuration.announcement_url or not configuration.announcement_id:
+        return "announcement_not_configured"
+    return ""
+
+
+def _deliver(job):
+    try:
+        configuration = VoipConfiguration.load()
+        reason = _cancellation_reason(job, configuration)
+        if reason:
+            job.status = AnnouncementJob.Status.CANCELLED
+            job.last_error = reason
+            return
+        place_announcement_call(
+            configuration,
+            mobile=job.message.ticket.customer.local_mobile,
+            idempotency_key=job.idempotency_key,
+        )
+    except Exception as exc:
+        job.attempts += 1
+        job.last_error = _failure_code(exc)
+        job.status = AnnouncementJob.Status.FAILED if job.attempts >= MAX_ATTEMPTS else AnnouncementJob.Status.PENDING
+        job.next_attempt_at = timezone.now() + timedelta(minutes=3)
+        logger.exception("Announcement call failed for job %s", job.pk)
+    else:
+        job.attempts += 1
+        job.status = AnnouncementJob.Status.SENT
+        job.sent_at = timezone.now()
+        job.last_error = ""
+
+
+def process_due_announcements():
+    now = timezone.now()
+    # A crashed worker can safely retry with the same provider idempotency key.
+    AnnouncementJob.objects.filter(
+        status=AnnouncementJob.Status.PROCESSING,
+        next_attempt_at__lt=now - timedelta(minutes=10),
+    ).update(status=AnnouncementJob.Status.PENDING, next_attempt_at=now)
+    with transaction.atomic():
+        jobs = list(
+            AnnouncementJob.objects.select_for_update(skip_locked=True)
+            .filter(status=AnnouncementJob.Status.PENDING, next_attempt_at__lte=now)
+            .select_related("message__ticket__customer")
+            .order_by("next_attempt_at", "pk")[:20]
+        )
+        AnnouncementJob.objects.filter(pk__in=[job.pk for job in jobs]).update(
+            status=AnnouncementJob.Status.PROCESSING, next_attempt_at=now,
+        )
+
+    for job in jobs:
+        _deliver(job)
+        job.save(update_fields=["status", "attempts", "next_attempt_at", "sent_at", "last_error"])

apps/notifications/management/commands/process_notifications.py

@@ -14,6 +14,7 @@ from apps.integrations.bale.providers import get_bale_provider
 from apps.integrations.sms.providers import get_sms_provider
 from apps.messaging.models import MessageReadReceipt
 from apps.notifications.models import NotificationJob,NotificationPolicy,SMSTemplate
+from apps.notifications.announcement_worker import process_due_announcements
 from apps.notifications.services import customer_reply_bale_policy,staff_reply_policy
 from apps.tickets.models import Ticket
 
@@ -343,6 +344,8 @@ class Command(BaseCommand):
                 if job.ticket_id and job.ticket.group_dispatch_id:
                     from apps.tickets.services import refresh_group_dispatch_status
                     refresh_group_dispatch_status(job.ticket.group_dispatch_id)
+            if not options.get("job_id") and not options.get("channel") and not options.get("min_id"):
+                process_due_announcements()
             _process_delivery_checks(options)
             if options["once"] or options.get("job_id"): break
             time.sleep(5)

apps/notifications/migrations/0015_announcementjob.py

@@ -0,0 +1,32 @@
+# Generated by Django 5.1.1 on 2026-09-28 15:31
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('messaging', '0003_messagereadreceipt'),
+        ('notifications', '0014_backfill_safe_0098_delivery_retries'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='AnnouncementJob',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('status', models.CharField(choices=[('PENDING', 'در صف'), ('PROCESSING', 'در حال تماس'), ('SENT', 'ارسال\u200cشده'), ('FAILED', 'ناموفق'), ('CANCELLED', 'لغوشده')], db_index=True, default='PENDING', max_length=15)),
+                ('attempts', models.PositiveSmallIntegerField(default=0)),
+                ('next_attempt_at', models.DateTimeField(db_index=True)),
+                ('idempotency_key', models.CharField(max_length=100, unique=True)),
+                ('last_error', models.TextField(blank=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('sent_at', models.DateTimeField(blank=True, null=True)),
+                ('message', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='announcement_job', to='messaging.message')),
+            ],
+            options={
+                'indexes': [models.Index(fields=['status', 'next_attempt_at'], name='announce_due_idx')],
+            },
+        ),
+    ]

apps/notifications/models.py

@@ -70,3 +70,49 @@ class NotificationJob(models.Model):
     )
     class Meta:
         indexes=[models.Index(fields=["status","next_attempt_at"],name="notif_due_idx"),models.Index(fields=["ticket","channel","status"],name="notif_ticket_chan_idx")]
+
+
+class AnnouncementJob(models.Model):
+    """One durable call reminder for each public message written by staff."""
+    class Status(models.TextChoices):
+        PENDING = "PENDING", "در صف"
+        PROCESSING = "PROCESSING", "در حال تماس"
+        SENT = "SENT", "ارسال‌شده"
+        FAILED = "FAILED", "ناموفق"
+        CANCELLED = "CANCELLED", "لغوشده"
+
+    message = models.OneToOneField("messaging.Message", on_delete=models.CASCADE, related_name="announcement_job")
+    status = models.CharField(max_length=15, choices=Status.choices, default=Status.PENDING, db_index=True)
+    attempts = models.PositiveSmallIntegerField(default=0)
+    next_attempt_at = models.DateTimeField(db_index=True)
+    idempotency_key = models.CharField(max_length=100, unique=True)
+    last_error = models.TextField(blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    sent_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        indexes = [models.Index(fields=["status", "next_attempt_at"], name="announce_due_idx")]
+
+    @property
+    def status_label(self):
+        if self.status == self.Status.SENT:
+            return "درخواست تماس پذیرفته شد"
+        if self.status == self.Status.PENDING and self.attempts:
+            return "در انتظار تلاش مجدد"
+        return self.get_status_display()
+
+    @property
+    def detail_label(self):
+        return {
+            "customer_read": "مشتری پیام را مشاهده کرد.",
+            "customer_replied": "مشتری پس از پیام پاسخ داد.",
+            "message_unavailable": "پیام برای اطلاع‌رسانی در دسترس نیست.",
+            "customer_mobile_unavailable": "شماره همراه مشتری در دسترس نیست.",
+            "announcement_not_configured": "تنظیمات تماس اطلاع‌رسانی کامل نیست.",
+            "service_timeout": "سرویس تماس در مهلت مقرر پاسخ نداد.",
+            "service_unreachable": "ارتباط با سرویس تماس برقرار نشد.",
+            "service_http_error": "سرویس تماس درخواست را با خطا پاسخ داد.",
+            "service_rejected": "سرویس تماس درخواست را نپذیرفت.",
+            "invalid_service_response": "پاسخ سرویس تماس معتبر نبود.",
+            "unexpected_error": "خطای غیرمنتظره در پردازش درخواست تماس رخ داد.",
+        }.get(self.last_error, "وضعیت درخواست تماس نیاز به بررسی دارد." if self.last_error else "")

apps/notifications/services.py

@@ -1,10 +1,22 @@
 from datetime import timedelta
 from uuid import uuid4
 from django.utils import timezone
-from .models import NotificationJob,NotificationPolicy
+from apps.core.models import VoipConfiguration
+from .models import AnnouncementJob,NotificationJob,NotificationPolicy
 def enqueue(channel,event_type,ticket,dedupe_key,payload=None,customer=None,staff_user=None):
     return NotificationJob.objects.get_or_create(dedupe_key=dedupe_key,defaults={"channel":channel,"event_type":event_type,"ticket":ticket,"payload":payload or {},"customer":customer,"staff_user":staff_user,"next_attempt_at":timezone.now()})[0]
 
+def schedule_announcement(message):
+    """The ticket transaction also commits this one-message reminder."""
+    delay = VoipConfiguration.load().announcement_delay_minutes
+    return AnnouncementJob.objects.get_or_create(
+        message=message,
+        defaults={
+            "next_attempt_at": message.created_at + timedelta(minutes=delay),
+            "idempotency_key": f"staff-message-{message.public_id.hex}",
+        },
+    )[0]
+
 def enqueue_unit_supervisor_ticket_sms(ticket):
     """Queue one concise new-ticket SMS for each configured unit supervisor."""
     unit = ticket.owning_unit