Skip to main content

Change Log — 2026-11-17

Author: Josh S. Sakweli, Backend Lead Team
Version: v1.0

Short Description: Who is bringing the parcel, and voice calls about a parcel between the buyer, the shop and whoever delivers it. Nothing here is breaking: fields were only added, no field changed shape or was removed.


1. Order details: who is bringing it

ADDED fulfillment.shippers[].assignedTo, on every order response that already carries fulfillment.

"shippers": [
  { "leg": 0, "businessId": "…", "name": "EMS Courier", "phone": "+255…",
    "assignedTo": { "accountId": "…", "name": "Mama Yoyo", "userProfileMedia": { "fileId": "8c2e…", "status": "COMPLETED", "thumbUrl": "https://…/thumb.jpg", "mimeType": "image/jpeg" } } }
]
  • SetThe whenperson the deliveryshipper businessassigned has givento that leg to one of its riders;leg; absent while nobody is on itassigned (the businessshipper itself is delivering). It follows the job: moved to Juma → Juma.
  • Buyer: "Mama Yoyo · EMS Courier is delivering". Shop: "Mama Yoyo · EMS Courier is coming to collect".
  • Never the rider'assigned person's phone number. To reach her,them, use the NexGate call (section 2). phone is still the business's.
  • Pictures follow the standard: userProfileMedia (fileId, status, thumbUrl, mimeType), never a bare URL.

2. Calls about a parcel (new)

Voice calls between the buyer, the shop and whoever delivers one order, open from the moment a shipper accepts until the order is completed or cancelled. Full API: docs/team/api/nexgate_app_team_api.md Part 8.

NexGate app (buyer): on the order page show two buttons:

  • Call shop: unchanged, POST /calls with targetShopId (any time).
  • Call delivery (only while the delivery is going on): POST /work-calls with { "orderId": "…", "to": "DELIVERY" }. It rings the rider who hasshipper: the parcelperson assigned to the job now, or the business.shipper itself. The answer carries the room token and calling (who is being rung) and allLinesBusy ("Everyone is on another call. Please wait, or call back later").

NexGate app (shop owner): the same Call delivery with "shopId" added, to call as the shop.

Who is on the other side (calling, other, caller in every call response):

{ "role": "SHIPPER", "name": "EMS Courier", "businessLogoMedia": { … },
  "assignedTo": { "accountId": "3213…", "name": "Mama Yoyo", "userProfileMedia": { "fileId": "8c2e…", "status": "COMPLETED", "thumbUrl": "https://…/thumb.jpg", "mimeType": "image/jpeg" } },
  "orderNumber": "ORD-2026-23424", "parcelNumber": "NX-SQAW-ZL", "orderId": "0f05…" }

role is BUYER, SHOP or SHIPPER. A shipper is always the business; assignedTo is the person it assigned to the job (absent when the business itself is on the call). Pictures: userProfileMedia, shopLogoMedia, businessLogoMedia.

Calls list: GET /work-calls (my calls as a buyer) or GET /work-calls?shopId= (the shop's). Each row has other (who), missed, and callBack (what to send as to to call back; absent once the order's calls are closed). Work calls do not appear in GET /calls, which stays chat calls only: show both lists, or merge them by time.

Answer / hang up: POST /work-calls/{callId}/join and /end (?shopId= when acting as the shop).

3. Caller identification on rings

ADDED, all optional, to the CALL_INCOMING / CALL_ENDED pushes and the call.incoming live event (docs/notifications/push_contracts_api_doc.md v1.3 §4.2, §4.3, §4.8). Ordinary chat calls look exactly as before.

Key Meaning
work "true" = a call about a parcel (no chat behind it, no conversationId)
answerAs ME (token included, answer at once), SHOP or BUSINESS (no token: answer with the join endpoint, first one wins)
shopId, shopName a call to the shop; now also reach the owner's phone (they were dropped before)
callerRole BUYER, SHOP, RIDERSHIPPER, SHIPPING_BUSINESS(the delivery business)
callerName, callerAvatar the person,buyer, the shop, or the shipper (business whenname itand calls as itselflogo)
businessNameassignedToAccountId, businessLogoassignedToName, assignedToAvatar SHIPPER only: the businessperson athe ridershipper worksassigned forto the job, who is calling
parcelNumber always on a work call
orderNumber, orderId only to the buyer and the shop, never to a shipper

Draw the line yourselves, e.g. "EMS Courier · Mama Yoyo · rider for EMS Courier · order ORD-2026-23424". The server sends fields, never a sentence.

4. New notifications

  • ORDER_MISSED_CALL (bell + push, opens the order): "Missed call about order ORD-…", with caller.name, call.time, orderNumber, parcelNumber.
  • Shipper app only: WORK_CALL_INCOMING, WORK_CALL_ENDED, WORK_CALL_MISSED.

5. Errors you may see on POST /work-calls

All 409 with a code: NO_SHIPPER_YET (no shipper accepted yet), CALLS_CLOSED ("This delivery is finished"), BUSY (they are on another call), USE_SHOP_CALLS (buyer ↔ shop goes through POST /calls), SAME_PERSON / OWN_SHOP / OWN_BUSINESS (nobody else would answer: e.g. buying from your own shop), NOT_ON_THIS_ORDER.