Communication

Outbound messaging to parents and guardians. Send trip alert notifications and read communication logs across the SMS, WhatsApp and email channels, honoring each recipient's notification preferences.

3 endpoint(s)

GET List Communication Logs {{url}}/communication/logs ▸

Retrieve a paginated log of messages sent to parents (SMS/WhatsApp), including delivery status.

Query Parameters

per_page (integer, optional, default 10, max 20)
senderuserid (string UUID, optional)
supervisor_id (string UUID, optional): Scope to a school.
status (string, optional): e.g. SENT, DELIVERED, FAILED, PENDING.
channel (string, optional): SMS or WHATSAPP.
category (string, optional): Message category, matching a template category.
date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
search (string, optional): Matches phone number, subject, or content.

Response

Paginated list of communication-log entries (data) with meta; each: channel, recipient, status and timestamp.

Auth

Bearer token

Used On

Communications Center

Request Body

{
    // "date_range": "2025-10-23 14:03:21, 2025-10-23 14:03:21",
    "status": "PENDING", //only use: PENDING, SENT, DELIVERED, FAILED
    "channel": "WHATSAPP", //only use: SMS, WHATSAPP
    "category": "CHECK_IN", //only use: GENERAL, CHECK_IN, CHECK_OUT, TRAFFIC_DELAY, VEHICLE_ISSUE, WEATHER_ISSUE, SAFETY_INCIDENT
    "search": "",
    "supervisor_id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
    "sender_user_id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
    "per_page": 10,
    "page": 1
}

Sample Response (200 OK)

{
    "data": [
        {
            "id": "b449cadf-e469-49d6-b9d5-28db605c2aba",
            "phone": "+254791472893",
            "parent": {
                "id": "d23b811d-368c-44fd-a031-6663bed28fc0",
                "phone": "+254791472893",
                "email": "Parent@gmail.com",
                "first_name": "Pm",
                "last_name": "Parent"
            },
            "dependant": {
                "id": "18435a9c-5822-4f31-9a56-aca28e2a038d",
                "first_name": "Middle",
                "last_name": "PM"
            },
            "sender": {
                "id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
                "first_name": "Collins",
                "last_name": "Muriuki"
            },
            "category": "Check In",
            "subject": "Terra Go Check In",
            "content": "Mzazi Mpendwa Mtoto amepanda basi!",
            "channel": "WhatsApp",
            "status": "Pending",
            "response": null,
            "created_at": "2026-01-14 10:38:15"
        },
        {
            "id": "e493e3dd-ea82-4207-bc06-7e0b325b3099",
            "phone": "+254791472893",
            "parent": {
                "id": "d23b811d-368c-44fd-a031-6663bed28fc0",
                "phone": "+254791472893",
                "email": "Parent@gmail.com",
                "first_name": "Pm",
                "last_name": "Parent"
            },
            "dependant": {
                "id": "18435a9c-5822-4f31-9a56-aca28e2a038d",
                "first_name": "Middle",
                "last_name": "PM"
            },
            "sender": {
                "id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
                "first_name": "Collins",
                "last_name": "Muriuki"
            },
            "category": "Check In",
            "subject": "Terra Go Check In",
            "content": "Mzazi Mpendwa Mtoto amepanda basi!",
            "channel": "WhatsApp",
            "status": "Pending",
            "response": null,
            "created_at": "2026-01-14 10:36:25"
        },
        {
            "id": "fab6ae02-0be7-4ff5-bf03-033e1890d801",
            "phone": "+254791472893",
            "parent": {
                "id": "d23b811d-368c-44fd-a031-6663bed28fc0",
                "phone": "+254791472893",
                "email": "Parent@gmail.com",
                "first_name": "Pm",
                "last_name": "Parent"
            },
            "dependant": {
                "id": "18435a9c-5822-4f31-9a56-aca28e2a038d",
                "first_name": "Middle",
                "last_name": "PM"
            },
            "sender": {
                "id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
                "first_name": "Collins",
                "last_name": "Muriuki"
            },
            "category": "Check In",
            "subject": "Terra Go Check In",
            "content": "Mzazi Mpendwa Mtoto amepanda basi!",
            "channel": "WhatsApp",
            "status": "Pending",
            "response": null,
            "created_at": "2026-01-14 10:34:04"
        },
        {
            "id": "e00614ce-400c-4047-ba72-b00ff3a9d54b",
            "phone": "+254791472893",
            "parent": {
                "id": "d23b811d-368c-44fd-a031-6663bed28fc0",
                "phone": "+254791472893",
                "email": "Parent@gmail.com",
                "first_name": "Pm",
                "last_name": "Parent"
            },
            "dependant": {
                "id": "18435a9c-5822-4f31-9a56-aca28e2a038d",
                "first_name": "Middle",
                "last_name": "PM"
            },
            "sender": {
                "id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
                "first_name": "Collins",
                "last_name": "Muriuki"
            },
            "category": "Check In",
            "subject": "Terra Go Check In",
            "content": "Mzazi Mpendwa Mtoto amepanda basi!",
            "channel": "WhatsApp",
            "status": "Pending",
            "response": null,
            "created_at": "2026-01-13 16:58:16"
        },
        {
            "id": "96539eca-cc0b-4a13-94d1-a88b2b54c10b",
            "phone": "+254791472893",
            "parent": {
                "id": "d23b811d-368c-44fd-a031-6663bed28fc0",
                "phone": "+254791472893",
                "email": "Parent@gmail.com",
                "first_name": "Pm",
                "last_name": "Parent"
            },
            "dependant": {
                "id": "18435a9c-5822-4f31-9a56-aca28e2a038d",
                "first_name": "Middle",
                "last_name": "PM"
            },
            "sender": {
                "id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
                "first_name": "Collins",
                "last_name": "Muriuki"
            },
            "category": "Check In",
            "subject": "Terra Go Check In",
            "content": "Mzazi Mpendwa Mtoto amepanda basi!",
            "channel": "WhatsApp",
            "status": "Pending",
            "response": null,
            "created_at": "2026-01-13 16:56:49"
        }
    ],
    "links": {
        "first": "http://terrago.test/api/communication/logs?page=1",
        "last": "http://terrago.test/api/communication/logs?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://terrago.test/api/communication/logs?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "page": null,
                "active": false
            }
        ],
        "path": "http://terrago.test/api/communication/logs",
        "per_page": 10,
        "to": 5,
        "total": 5
    },
    "status": 200,
    "message": "Communication Logs Retrieved Successfully"
}

POST Send Trip Alert Notifications {{url}}/communication/add ▸

Queue personalized SMS/WhatsApp notifications to the parents of every student tied to a specific trip alert (e.g. notify all affected parents when an incident is logged on a trip).

Request Body

trip_id (string UUID, required)
alert_id (string UUID, required): The alert/event these notifications relate to.
template_id (string UUID, required): Must be an active message template.
subject (string, required)
message (string, required)

Response

{"total_dispatched": N} — the number of notifications actually queued.

Notes

Only parents who have notifications enabled (see Set User Notification Settings) are messaged.
WhatsApp is preferred; SMS is used as the fallback per parent's channel preference.
Sending happens asynchronously via a background job per recipient — a 200 here means the jobs were queued, not that messages have been delivered yet.

Auth

Bearer token

Request Body

{
    "trip_id" : "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",  // Trip UUID
    "alert_id": "b40a2131-4796-429d-977b-962f275a1dd2",  // Alert / event UUID
    "template_id": "909e0d32-1913-4847-94fc-747fd5727513",  // Message template UUID
    "subject": "Terra Go Check In",  // Email subject line
    "message": "Mzazi Mpendwa Mtoto amepanda basi!"  // Message text sent to the recipient
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "total_dispatched": 2
    },
    "message": "Successfully queued 2 personalized notifications"
}

GET Get Communication Stats {{url}}/communication/stats ▸

SMS-channel engagement stats for the admin dashboard cards — sent this month, sent today, and month-to-date failure rate.

Query Parameters

supervisor_id (string UUID, optional): scope stats to a single school; omitted for the org-wide (System Admin) view.

Response

channel — always SMS (this endpoint only covers the SMS channel).
sentmtd / senttoday — messages sent or delivered, month-to-date / today.
failure_rate — percentage of this month's messages that failed.
total_mtd — total messages (any status) this month.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Used On

Communications Center

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "channel": "SMS",
        "sent_mtd": 1204,
        "sent_today": 38,
        "failure_rate": 1.4,
        "total_mtd": 1221
    },
    "message": "Communication stats retrieved successfully"
}