Communication API — Announcements, Messaging & Notifications

The Communication module is the backbone of information exchange across the Gobarau Academy platform. It provides structured channels for administrators and staff to broadcast role-targeted announcements, deliver automated per-user notifications, facilitate private direct messages between users, host a student Q&A board for academic queries, and coordinate alumni career talk sessions. All endpoints sit under the /api/communication/ prefix and require authentication; write operations on announcements, questions, and career talk sessions additionally require staff or admin-level permissions.

Announcements

Announcements are school-wide broadcasts targeted at a specific role group. They can be pinned for prominence and optionally given an expiry date so they disappear from feeds automatically.

The audience field determines which role group sees an announcement. Only users whose account role matches the value will receive it — so a student announcement will not appear in a teacher’s feed. Choose the audience value carefully before publishing.

List & Create Announcements

method

string

GET · POST

Endpoint: GET/POST /api/communication/announcements/ Permissions: IsAuthenticated, IsStaffOrAdmin

Request Fields (POST)

title

string

required

Short descriptive title of the announcement (max 200 characters).

body

string

required

Full announcement body text.

audience

string

required

The role group this announcement targets. Must be one of the RoleChoices values:

Value	Label
`super_admin`	Super Admin
`principal`	Principal
`vice_principal`	Vice Principal
`bursar`	Bursar
`teacher`	Teacher
`student`	Student
`parent`	Parent
`alumni`	Alumni
`nurse`	School Nurse
`counsellor`	Counsellor

published_at

string (datetime)

ISO 8601 datetime when the announcement goes live. If omitted the announcement is saved as a draft.

is_pinned

boolean

When true, the announcement is pinned to the top of the audience’s feed. Defaults to false.

expires_at

string (datetime)

Optional ISO 8601 datetime after which the announcement is no longer surfaced. Leave blank for permanent announcements.

Example — Create a pinned student announcement

curl -X POST https://api.gobarau.edu.ng/api/communication/announcements/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "End-of-Term Examination Timetable Released",
    "body": "The timetable for the First Term examinations has been published on the noticeboard. All students are advised to collect their copies from the admin office.",
    "audience": "student",
    "published_at": "2025-01-15T08:00:00Z",
    "is_pinned": true,
    "expires_at": "2025-02-01T00:00:00Z"
  }'

Example Response

{
  "id": 1,
  "public_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "End-of-Term Examination Timetable Released",
  "body": "The timetable for the First Term examinations has been published on the noticeboard. All students are advised to collect their copies from the admin office.",
  "audience": "student",
  "published_at": "2025-01-15T08:00:00Z",
  "is_pinned": true,
  "expires_at": "2025-02-01T00:00:00Z",
  "created_at": "2025-01-14T18:32:00Z",
  "updated_at": "2025-01-14T18:32:00Z"
}

Response Fields

integer

Auto-incrementing integer primary key for the announcement.

public_id

uuid

Unique public UUID identifier for the announcement (from BaseModel).

title

string

Announcement title.

body

string

Full body text of the announcement.

audience

string

Role group the announcement targets.

published_at

string (datetime)

Datetime the announcement was or will be published.

is_pinned

boolean

Whether the announcement is pinned at the top of the feed.

expires_at

string (datetime) | null

Datetime the announcement expires, or null if it never expires.

created_at

string (datetime)

Record creation timestamp (from BaseModel).

updated_at

string (datetime)

Last modification timestamp (from BaseModel).

Notifications

Notifications are per-user system events delivered automatically by the platform. Each notification carries a type, a title, a message body, and an optional deep-link URL. Users only see their own notifications; admin roles (super_admin, principal, vice_principal) can see all.

Leverage notifications for automated system events — payment confirmations, grade postings, new assignment uploads, attendance alerts, and welfare case updates. Emit a notification with the appropriate notification_type immediately after the relevant action so users receive real-time updates without polling other endpoints.

List & Create Notifications

Endpoint: GET/POST /api/communication/notifications/ Permissions: IsAuthenticated (scoped — users see only their own records unless admin)

Request Fields (POST)

recipient

integer

required

Primary key of the User who should receive this notification.

notification_type

string

required

Classification of the event. One of:

Value	Label
`system`	System
`payment`	Payment
`academic`	Academic
`attendance`	Attendance
`welfare`	Welfare
`message`	Message

title

string

required

Short notification title (max 200 characters).

message

string

required

Full notification message body.

is_read

boolean

Read status of the notification. Defaults to false.

read_at

string (datetime)

Datetime the notification was read. Should be set alongside is_read: true.

link

string (url)

Optional deep-link URL for the user to navigate to the related resource (e.g. a payment invoice or grade report).

Example — Create a payment notification

curl -X POST https://api.gobarau.edu.ng/api/communication/notifications/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": 42,
    "notification_type": "payment",
    "title": "School Fees Payment Received",
    "message": "Your payment of ₦85,000 for the First Term 2024/2025 session has been confirmed.",
    "link": "https://api.gobarau.edu.ng/api/finance/payment-records/101/"
  }'

Mark a Notification as Read (PATCH)

Use a PATCH request to the detail endpoint to update read status without replacing the full object.

curl -X PATCH https://api.gobarau.edu.ng/api/communication/notifications/7d3e9f12-ab34-5678-cdef-901234567890/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "is_read": true,
    "read_at": "2025-01-20T10:15:30Z"
  }'

Response Fields

integer

Auto-incrementing integer primary key for the notification.

public_id

uuid

Unique public UUID identifier for the notification (from BaseModel).

recipient

integer

Primary key of the recipient User.

notification_type

string

Type classification of the notification.

title

string

Short notification title.

message

string

Full notification message.

is_read

boolean

Whether the user has read the notification.

read_at

string (datetime) | null

Datetime it was read, or null if unread.

link

string

Deep-link URL for the related resource. Empty string if not applicable.

created_at

string (datetime)

Record creation timestamp (from BaseModel).

updated_at

string (datetime)

Last modification timestamp (from BaseModel).

Messages

Messages provide a direct 1-to-1 inbox between any two platform users (staff, students, parents, etc.). Each message has a sender, a recipient, an optional subject line, and a body. Users see only conversations they are part of; admin roles can access all messages.

List & Create Messages

Endpoint: GET/POST /api/communication/messages/ Permissions: IsAuthenticated (scoped — users see only sent/received messages unless admin)

Request Fields (POST)

sender

integer

required

Primary key of the sending User.

recipient

integer

required

Primary key of the receiving User.

subject

string

Optional message subject line (max 200 characters). Defaults to an empty string.

body

string

required

Full message body.

is_read

boolean

Whether the recipient has read the message. Defaults to false; the system normally manages this field.

read_at

string (datetime)

Datetime the message was read by the recipient.

Example — Send a direct message

curl -X POST https://api.gobarau.edu.ng/api/communication/messages/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": 15,
    "recipient": 42,
    "subject": "Regarding Your Child'\''s Progress",
    "body": "Dear Mr. Sani, I would like to schedule a meeting to discuss Aisha'\''s academic performance this term. Please let me know your availability."
  }'

Response Fields

integer

Auto-incrementing integer primary key for the message.

public_id

uuid

Unique public UUID identifier for the message (from BaseModel).

sender

integer

Primary key of the sender User.

recipient

integer

Primary key of the recipient User.

subject

string

Message subject. Empty string if not provided.

body

string

Full message body.

sent_at

string (datetime)

Datetime the message was sent (auto_now_add). Read-only.

is_read

boolean

Whether the recipient has read the message.

read_at

string (datetime) | null

Datetime the message was read, or null if unread.

created_at

string (datetime)

Record creation timestamp (from BaseModel).

updated_at

string (datetime)

Last modification timestamp (from BaseModel).

Questions

The Questions endpoint powers the student Q&A board. Students post questions against a specific academic subject, and any authenticated staff member can provide an answer. Questions are ordered by newest first.

List & Create Questions

Endpoint: GET/POST /api/communication/questions/ Permissions: IsAuthenticated, IsStaffOrAdmin

Request Fields (POST)

student

integer

required

Primary key of the StudentProfile asking the question.

subject

integer

required

Primary key of the Subject the question relates to.

question_text

string

required

The full text of the student’s question.

answer_text

string

Text of the answer. Leave blank when first posting; a teacher fills this in via PATCH.

answered_by

integer

Primary key of the User (teacher) who provided the answer. Set alongside answer_text.

answered_at

string (datetime)

Datetime the question was answered.

Example — Post a question

curl -X POST https://api.gobarau.edu.ng/api/communication/questions/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 88,
    "subject": 5,
    "question_text": "Can you explain the difference between mitosis and meiosis with respect to chromosome number?"
  }'

Example — Teacher answers a question (PATCH)

Use a PATCH request to the detail endpoint to add an answer to an existing question.

curl -X PATCH https://api.gobarau.edu.ng/api/communication/questions/f1e2d3c4-b5a6-7890-fedc-ba0987654321/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "answer_text": "Mitosis produces two genetically identical daughter cells with the same chromosome count as the parent cell (diploid), while meiosis produces four genetically unique daughter cells with half the chromosome count (haploid). Meiosis is used for sexual reproduction; mitosis is used for growth and repair.",
    "answered_by": 15,
    "answered_at": "2025-01-20T14:00:00Z"
  }'

Response Fields

integer

Auto-incrementing integer primary key for the question.

public_id

uuid

Unique public UUID identifier for the question (from BaseModel).

student

integer

Primary key of the StudentProfile.

subject

integer

Primary key of the related Subject.

question_text

string

The student’s question.

asked_at

string (datetime)

Datetime the question was submitted (auto_now_add). Read-only.

answer_text

string

The answer provided by staff. Empty string until answered.

answered_by

integer | null

Primary key of the answering User, or null if unanswered.

answered_at

string (datetime) | null

Datetime the answer was given, or null if unanswered.

created_at

string (datetime)

Record creation timestamp (from BaseModel).

updated_at

string (datetime)

Last modification timestamp (from BaseModel).

Career Talk Sessions

Career talk sessions are alumni-led events where graduates return to speak about their professional journeys. Each session is linked to an AlumniProfile, has a date/time/venue, and supports attendee cap and registration deadline settings.

List & Create Career Talk Sessions

Endpoint: GET/POST /api/communication/career-talk-sessions/ Permissions: IsAuthenticated, IsStaffOrAdmin

Request Fields (POST)

title

string

required

Title of the career talk session (max 200 characters).

description

string

Detailed description of the session topic and speaker background. Defaults to empty string.

alumni

integer

required

Primary key of the AlumniProfile who is the featured speaker.

date

string (date)

required

Date of the session in YYYY-MM-DD format.

time

string (time)

required

Start time of the session in HH:MM:SS format.

venue

string

required

Location where the session will be held (max 200 characters).

max_attendees

integer

Maximum number of attendees allowed. Defaults to 100.

registration_deadline

string (date)

required

Last date in YYYY-MM-DD format by which students must register to attend.

Example — Create a career talk session

curl -X POST https://api.gobarau.edu.ng/api/communication/career-talk-sessions/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "From Gobarau to Silicon Valley: A Journey in Software Engineering",
    "description": "Engr. Hafsat Musa, Class of 2015, shares her path from Gobarau Academy to leading a team at a top technology firm. Topics include tertiary education choices, coding bootcamps, and career growth.",
    "alumni": 3,
    "date": "2025-03-12",
    "time": "10:00:00",
    "venue": "School Main Hall",
    "max_attendees": 200,
    "registration_deadline": "2025-03-10"
  }'

Response Fields

integer

Auto-incrementing integer primary key for the session.

public_id

uuid

Unique public UUID identifier for the session (from BaseModel).

title

string

Session title.

description

string

Full description of the session.

alumni

integer

Primary key of the featured AlumniProfile.

date

string (date)

Date of the session.

time

string (time)

Start time of the session.

venue

string

Venue name or location.

max_attendees

integer

Maximum allowed attendees.

registration_deadline

string (date)

Registration cut-off date.

created_at

string (datetime)

Record creation timestamp (from BaseModel).

updated_at

string (datetime)

Last modification timestamp (from BaseModel).

Administration

People & Admissions

Academics

Finance & Services

Communication & Content

Communication API — Announcements, Messaging & Notifications

Announcements

List & Create Announcements

Request Fields (POST)

Example — Create a pinned student announcement

Example Response

Response Fields

Notifications

List & Create Notifications

Request Fields (POST)

Example — Create a payment notification

Mark a Notification as Read (PATCH)

Response Fields

Messages

List & Create Messages

Request Fields (POST)

Example — Send a direct message

Response Fields

Questions

List & Create Questions

Request Fields (POST)

Example — Post a question

Example — Teacher answers a question (PATCH)

Response Fields

Career Talk Sessions

List & Create Career Talk Sessions

Request Fields (POST)

Example — Create a career talk session

Response Fields

Build docs developers (and LLMs) love

Administration

People & Admissions

Academics

Finance & Services

Communication & Content

Documentation Index

​Announcements

​List & Create Announcements

​Request Fields (POST)

​Example — Create a pinned student announcement

​Example Response

​Response Fields

​Notifications

​List & Create Notifications

​Request Fields (POST)

​Example — Create a payment notification

​Mark a Notification as Read (PATCH)

​Response Fields

​Messages

​List & Create Messages

​Request Fields (POST)

​Example — Send a direct message

​Response Fields

​Questions

​List & Create Questions

​Request Fields (POST)

​Example — Post a question

​Example — Teacher answers a question (PATCH)

​Response Fields

​Career Talk Sessions

​List & Create Career Talk Sessions

​Request Fields (POST)

​Example — Create a career talk session

​Response Fields

Build docs developers (and LLMs) love

Announcements

List & Create Announcements

Request Fields (POST)

Example — Create a pinned student announcement

Example Response

Response Fields

Notifications

List & Create Notifications

Request Fields (POST)

Example — Create a payment notification

Mark a Notification as Read (PATCH)

Response Fields

Messages

List & Create Messages

Request Fields (POST)

Example — Send a direct message

Response Fields

Questions

List & Create Questions

Request Fields (POST)

Example — Post a question

Example — Teacher answers a question (PATCH)

Response Fields

Career Talk Sessions

List & Create Career Talk Sessions

Request Fields (POST)

Example — Create a career talk session

Response Fields