Admin Announcements

Back-office announcements and broadcast notifications for clients, drivers, and admins. Supports immediate delivery, scheduled broadcasting, and recurring recurrence (daily, weekly, monthly). Paths are relative to the /api/v1 prefix; all routes require an admin bearer token (Authorization: Bearer {token}).

Requires an admin bearer token (see Admin auth). Admin only.

See Common errors.

Endpoints

Method URI Access Description
GET /admin/announcements Admin List announcements history with pagination
POST /admin/announcements Admin Create and dispatch or schedule an announcement

GET /admin/announcements

Lists historical, scheduled, and active announcements, ordered by scheduled/created date (newest first).

Query

Field Type Required Rules
limit integer no 1–100; defaults to 15
page integer no Current page number (1-based)

Response 200

{
  "items": [
    {
      "id": 14,
      "admin_id": 1,
      "title": "Mantenimiento programado de plataforma",
      "body": "La plataforma estará en mantenimiento breve este domingo de 02:00 a 03:00 AM.",
      "severity": "info",
      "audience": ["client", "driver"],
      "status": "sent",
      "scheduled_at": null,
      "sent_at": "2026-09-22T10:00:00+00:00",
      "recurrence": "none",
      "recurrence_end_at": null,
      "next_send_at": null,
      "created_at": "2026-09-22T10:00:00+00:00",
      "updated_at": "2026-09-22T10:00:05+00:00",
      "admin": {
        "id": 1,
        "name": "Administrador General"
      }
    }
  ],
  "meta": {
    "total": 45,
    "per_page": 15,
    "current_page": 1,
    "last_page": 3
  }
}

POST /admin/announcements

Creates a new announcement. If scheduled_at is omitted or in the past, the announcement is immediately dispatched (status: "pending" -> "sent") to the target audience via push notifications (FCM) and the notifications inbox. If scheduled_at is in the future, it is stored with status: "scheduled" and processed automatically by the scheduler.

When recurrence is set (daily, weekly, monthly), future instances will be automatically scheduled and dispatched until recurrence_end_at (if specified).

Request Body

Field Type Required Rules
title string yes max: 100 chars
body string yes max: 500 chars
severity string yes one of info, warning, error
audience array yes array of client, driver, admin (min: 1)
scheduled_at string (ISO8601) no future date/time for scheduled broadcasting
recurrence string no one of none, daily, weekly, monthly (defaults to none)
recurrence_end_at string (ISO8601) no deadline after which recurrence terminates

Example payload (immediate delivery):

{
  "title": "Promoción de fin de semana",
  "body": "Obtén recargas con tarifa preferencial durante todo el sábado.",
  "severity": "info",
  "audience": ["client"],
  "recurrence": "none"
}

Example payload (scheduled & recurring weekly):

{
  "title": "Recordatorio de liquidación semanal",
  "body": "Por favor revisa tus comprobantes y saldo en la billetera antes del corte.",
  "severity": "warning",
  "audience": ["driver"],
  "scheduled_at": "2026-09-28T08:00:00-04:00",
  "recurrence": "weekly",
  "recurrence_end_at": "2026-12-31T23:59:59-04:00"
}

Response 201

{
  "announcement": {
    "id": 15,
    "admin_id": 1,
    "title": "Recordatorio de liquidación semanal",
    "body": "Por favor revisa tus comprobantes y saldo en la billetera antes del corte.",
    "severity": "warning",
    "audience": ["driver"],
    "status": "scheduled",
    "scheduled_at": "2026-09-28T12:00:00+00:00",
    "recurrence": "weekly",
    "recurrence_end_at": "2026-12-31T23:59:59+00:00",
    "next_send_at": "2026-09-28T12:00:00+00:00",
    "created_at": "2026-09-22T11:00:00+00:00",
    "updated_at": "2026-09-22T11:00:00+00:00",
    "admin": {
      "id": 1,
      "name": "Administrador General"
    }
  }
}

Errors

Status Body When
401 { "error": "Unauthorized" } Invalid or missing admin token
403 { "error": "Forbidden" } Caller is not an admin
422 { "error": "ValidationError", "details": { … } } Invalid fields or invalid date format