Notifications and Broadcasts for Coaches

Astral keeps coaches and athletes connected through a layered notification system. You receive in-app notifications when athletes join or leave your organization, and you can proactively reach athletes through direct push notifications and broadcast campaigns.

Notification center

The notification center collects all notifications for your account in one place. Categories include:

Category	What it covers
`training`	AI insights, weekly summaries, activity feedback
`team`	Member joined / member left events
`social`	Group posts and leaderboard updates
`achievements`	Personal records and milestones
`reminders`	Scheduled workout reminders

Dashboard
API

Click the bell icon in the top navigation bar to open the notification center. You can filter by category, mark individual notifications as read, or mark all as read at once.

Fetch paginated notifications:

GET /api/v1/notifications/center?limit=20&category=training

Filter to unread only:

GET /api/v1/notifications/center?read=false

Get unread counts per category:

GET /api/v1/notifications/center/counts

Mark a specific notification as read:

PATCH /api/v1/notifications/center/{notification_id}/read

{ "read": true }

Mark all notifications as read (optionally scoped to a category):

POST /api/v1/notifications/center/mark-all-read

{ "category": "training" }

AI-generated summaries

Astral’s AI coach Rex generates summaries for individual activities and weekly training blocks. These appear in each athlete’s profile and in your notification center.

Weekly summaries

Weekly summaries include:

summary_text — Rex’s narrative overview of the athlete’s week
total_distance — total km for the week
total_activities — number of completed runs
average_pace — average pace in min/km (display format: M:SS)
runner_score — overall performance score for the week

Fetch the most recent weekly summaries for the authenticated user (up to 12 weeks):

GET /api/v1/notifications/ai-summary/weekly?limit=4

Filter to a specific week:

GET /api/v1/notifications/ai-summary/weekly?week_start=2026-04-14

Fetch AI summaries for a specific activity:

GET /api/v1/notifications/ai-summary?activity_id={activity_id}

Sending push notifications

Direct push to a single athlete

Send a push notification directly to one athlete by their user ID. The notification delivers to all valid devices registered to that athlete.

POST /api/v1/notifications/direct-push

{
  "user_id": "usr_abc123",
  "title": "Time to run!",
  "message": "Your tempo run is scheduled for today. You've got this.",
  "data": {
    "type": "training_reminder",
    "plan_id": "plan_xyz789"
  }
}

The data object is optional and is passed through to the mobile app for deep-linking or custom handling. The response includes tokens_sent and failed_tokens counts.

A push notification can only be delivered if the athlete has a valid device token registered. You can check whether an athlete has push enabled by looking at the has_push_token field in the coach_athletes_metrics response.

Broadcast push to a topic

Broadcast push sends a notification to all subscribers of a topic channel.

POST /api/v1/notifications/push

{
  "topic": "general",
  "title": "Race day update",
  "message": "Check the app for updated logistics for this weekend's race."
}

The topic defaults to "general" if omitted. Use this for platform-wide announcements.

Broadcast campaigns

Broadcasts are targeted message campaigns sent to a defined audience of athletes. They support push notifications, email, and LINE channels, and can be sent immediately or scheduled for a future time.

Dashboard
API

Navigate to Broadcasts in the left sidebar to create and manage campaigns. The campaign builder lets you:

Choose a channel (push, email, or LINE)
Write your message content
Define your audience — all athletes, a segment, or a manually selected list
Schedule for immediate delivery or set a future date and time

Create a broadcast campaign:

POST /api/v1/broadcasts

{
  "org_id": "{org_id}",
  "channel": "push",
  "content": {
    "title": "Weekly check-in",
    "body": "How are you feeling after this week's long run? Log your effort in the app."
  },
  "audience_type": "all",
  "schedule_type": "immediate"
}

To target a specific list of athletes, use "audience_type": "manual" and provide their user IDs:

{
  "org_id": "{org_id}",
  "channel": "push",
  "content": {
    "title": "Marathon group reminder",
    "body": "Your 20-mile long run is this Sunday. Review the plan in the app."
  },
  "audience_type": "manual",
  "audience_athlete_user_ids": ["usr_001", "usr_002", "usr_003"],
  "schedule_type": "scheduled",
  "scheduled_at": "2026-05-02T07:00:00Z"
}

Supported channel values: push, email, line. Supported audience_type values: all, segment, manual. Supported schedule_type values: immediate, scheduled.

Registering a device for push notifications

Athletes register their device tokens through the mobile app automatically. If you are building an integration or testing push delivery, you can register a token directly.

POST /api/v1/notifications/tokens/device

{
  "user_id": "usr_abc123",
  "token": "fcm_token_string_here",
  "platform": "ios",
  "device_id": "device-uuid-here",
  "app_version": "2.4.1",
  "metadata": {
    "device_model": "iPhone 15",
    "os_version": "17.4",
    "timezone": "Asia/Taipei"
  }
}

Supported platform values: ios, android, web.

Checking token status for an athlete

GET /api/v1/notifications/tokens/info/{user_id}

The response shows the number of registered tokens, their platforms, validity status, and the last activity timestamp.

​Notification center

​AI-generated summaries

​Weekly summaries

​Sending push notifications

​Direct push to a single athlete

​Broadcast push to a topic

​Broadcast campaigns

​Registering a device for push notifications

​Checking token status for an athlete

Notification center

AI-generated summaries

Weekly summaries

Sending push notifications

Direct push to a single athlete

Broadcast push to a topic

Broadcast campaigns

Registering a device for push notifications

Checking token status for an athlete