Roko Lucky Drawer — SMS Platform API (0.1.0)

Topaz calls this endpoint for every SMS received on our SIM (612 990 119 for stage, 612 987 722 for prod). The request must carry the shared token in X-Roko-Webhook-Token; Roko persists the SMS and returns the internal sms_id.

Authentication

HTTP header X-Roko-Webhook-Token: <token>. The token is compared in constant time against the value Roko stores in SSM at /roko/{stage|prod}/webhook-inbound-token and is issued out-of-band. Missing or wrong token → 401 unauthorized.

Idempotency — important, please read before integrating

The pair (gateway_sms_id, port) is our dedup key. You should send a unique gateway_sms_id per distinct SMS. If you retry the same SMS after a network blip, use the same gateway_sms_id — we will update the existing row in place and return the same sms_id. If you send a different SMS, use a new gateway_sms_id and you'll get a new row and a new sms_id.

Worked example:

Both gateway_sms_id and the returned sms_id are opaque strings (UUIDs recommended). sms_id is a Roko-generated UUID — never sequential, never guessable, safe to log.

Call 1 — farmer sends their first code:

POST /webhook/sms
{"gateway_sms_id": "a1b2c3d4-0001", "port": 17,
 "sender": "612345678", "text": "ROKO U12345678",
 "timestamp": "2026-05-15T10:30:00Z", "source": "topaz"}
→ 200  {"status": "accepted",
        "sms_id": "c4f7e2a0-3b1e-4d2a-9e18-1a6e5f8c0c11"}

DB: new row; parsed_code=U12345678, public_id=c4f7....

Call 2 — Topaz retries Call 1 because it missed the ACK:

POST /webhook/sms   (identical body)
→ 200  {"status": "accepted",
        "sms_id": "c4f7e2a0-3b1e-4d2a-9e18-1a6e5f8c0c11"}
        ← same sms_id

DB: still one row; no duplicates.

Call 3 — same farmer sends a second, different SMS. Topaz assigns a new gateway_sms_id:

POST /webhook/sms
{"gateway_sms_id": "a1b2c3d4-0002", "port": 17,
 "sender": "612345678", "text": "ROKO U99999999",
 "timestamp": "2026-05-15T10:35:00Z", "source": "topaz"}
→ 200  {"status": "accepted",
        "sms_id": "8f2c1a90-4d5e-4a88-b1ab-12e2a4d55c77"}
        ← new sms_id

DB: second row; parsed_code=U99999999.

Call 4 — bug in Topaz: different SMS reuses gateway_sms_id="a1b2c3d4-0001":

POST /webhook/sms
{"gateway_sms_id": "a1b2c3d4-0001", "port": 17,
 "sender": "612345678", "text": "ROKO UXXXXXXXX", ...}
→ 200  {"status": "accepted",
        "sms_id": "c4f7e2a0-3b1e-4d2a-9e18-1a6e5f8c0c11"}
        ← original sms_id, row overwritten

DB: row from Call 1 is overwritten with the new text + parsed_code. Reusing a gateway_sms_id across different SMSes is a gateway bug that causes data loss on our side.

Notes:

• sms_id is a UUIDv4 generated by Roko, not a sequential integer. Safe to log, safe to expose in error messages. It's opaque to Topaz — don't try to interpret or correlate it.
• gateway_sms_id is whatever string Topaz uses (UUID, integer, alphanumeric prefix) up to 64 chars. Integers like 101 are accepted but the JSON-body will be coerced to a string on storage; we recommend using UUIDs for the same privacy reasons that apply to sms_id.

Inbound webhook used by the active outbound SMS provider (Nimba today) to report status transitions for messages we previously sent via POST /sms/send.

Authentication

The path segment {secret} is itself the credential — a long random URL-safe string stored in SSM at /roko/{stage|prod}/sms-status-webhook-secret. Constant-time compared in code. 401 on mismatch.

Why path-secret rather than a signed header: Nimba's portal does not currently sign payloads. The URL appears once in their dashboard and never in normal logs.

Single-URL routing across environments

Nimba allows only one webhook URL per account, and the same Nimba account serves both stage and prod. We register only prod's URL in their dashboard. If prod receives a DLR whose message ID doesn't match a row in prod's sms_outgoing, prod re-POSTs the raw body to stage's URL with stage's secret. Stage records it as a normal authenticated call. Each env's data stays in its own DB.

Behaviour

• Every accepted call (path secret matches) is persisted into the sms_status_events audit table verbatim, regardless of whether we can resolve the message ID. Permanent retention.
• When the message ID resolves to a row in sms_outgoing and the mapped status is delivered or failed, the row's delivery_status is updated. Already-DELIVERED rows are never downgraded.
• We always return 200 OK after auth — internal lookup or mapping failures never trigger a provider retry.

Real Nimba payload shape will be confirmed against the first live DLR; until then the request body is treated as opaque JSON.

The Yeastar P560 pushes call lifecycle events here (call start and call end at minimum). Auth is HMAC-SHA256(raw body, shared secret); the verifier is tolerant of several Yeastar firmware variations:

• Header: X-Signature or X-Signature-256.
• Value: the raw digest, optionally with a sha256= prefix.
• Encoding: base64 OR hex — either is accepted.

The signing secret is generated by the PBX (Integrations → API → Webhook Event Push) on a per-webhook-entry basis — each env's Yeastar webhook has its own value, mirrored into the matching SecureString at /roko/{stage,prod}/pbx-webhook-secret. The stage and prod parameters hold different values; each env's Lambda only reads its own.

On success the handler:

1. Persists every event to call_events (full raw payload kept in JSONB for forensics).
2. Matches the event's extension to an agents.pbx_extension and that agent's currently IN_PROGRESS callback.
3. When matched, appends pbx_call_start / pbx_call_end to the callback activity timeline.

Unmatched events are still persisted to call_events (with NULL agent_id / callback_id); they just don't appear on a callback timeline. Auth failures land in webhook_access_failures and the PBX retries per its own retry policy.

The canonical payload shape we operate on internally is { operation: "call_start"|"call_end", extension, call_id, ip_address }, but the handler also normalises several Yeastar aliases (event_type, member_ext, caller_ext, linkedid, etc.) onto that shape.

Internal endpoint called by the Roko ops dashboard / worker jobs to send an SMS to a farmer.

Provider routing

The active outbound provider is selected at runtime by the SMS_PROVIDER env var on the Lambda (default nimba). Callers DO NOT pick — this is operator-controlled. Each successful response echoes which provider handled the send via the provider field.

Provider-specific rules currently enforced:

• Nimba (nimba): the text body MUST contain the literal word Roko (case-insensitive). Nimba pairs every send with a registered sender name (Roko); messages without the keyword are silently dropped on their side, so we reject 400 early.

Authentication

HTTP header x-api-key: <key>. The key is issued per caller by the operator and stored in SSM at /roko/{stage|prod}/sender-api-key. Missing or wrong key → 403 Forbidden from API Gateway.

Strict validations (return 400)

• phone_number must be a Guinea MSISDN. Accepted shapes: +224612345678, 224612345678, or bare local 612345678. The server normalizes to canonical E.164 (+224612345678) before persistence and before handing off to the SMS provider.
• text must fit in exactly one SMS segment:
  • 160 chars if all characters are in the GSM-7 alphabet
  • 70 chars otherwise (Unicode/UCS-2)
• Requests exceeding the single-segment limit return 400 with the detected encoding and the applicable limit.

Idempotency — use the Idempotency-Key header

Always generate a fresh UUID per logical send and put it in the Idempotency-Key header. If the request times out or the network drops, retry with the same header value. We will not send a second SMS to the farmer; you get the original sms_id back with the current status.

Format: 8-64 chars from [A-Za-z0-9_.:-]. UUIDv4 (36 chars) is the recommended default.

Worked example:

Call 1 — frontend sends "Merci" to a farmer, with a fresh UUID:

POST /sms/send
Idempotency-Key: 0b3e8bdd-b0ac-4d1a-97f9-3f6f3a3c3e91
x-api-key: <key>
Content-Type: application/json

{"phone_number": "+224612345678",
 "text": "Merci pour votre participation ROKO.",
 "template_key": "VALID_FIRST"}

→ 200 {"sms_id": "c4f7e2a0-3b1e-4d2a-9e18-1a6e5f8c0c11",
       "status": "SENT",
       "gateway_sms_id": "20260515-topaz-0001"}

DB: new row with client_idempotency_key=0b3e..., public_id=c4f7..., delivery_status=SENT.

Call 2 — frontend hits a read timeout on Call 1 (Topaz was slow) and retries with the same Idempotency-Key:

POST /sms/send
Idempotency-Key: 0b3e8bdd-b0ac-4d1a-97f9-3f6f3a3c3e91
(same body)

→ 200 {"sms_id": "c4f7e2a0-3b1e-4d2a-9e18-1a6e5f8c0c11",
       "status": "SENT",
       "gateway_sms_id": "20260515-topaz-0001",
       "idempotent_replay": true}

DB: unchanged. Topaz not called a second time. The farmer gets one SMS.

Call 3 — frontend sends a separate message to the same farmer with a new Idempotency-Key:

POST /sms/send
Idempotency-Key: 7d2c8a91-4e56-4f88-9bab-12e2a4d55c77
(different body or same — doesn't matter)

→ 200 {"sms_id": "8f2c1a90-4d5e-4a88-b1ab-12e2a4d55c77",
       "status": "SENT",
       "gateway_sms_id": "20260515-topaz-0002"}

DB: second row. Another SMS is sent. This is correct: new key = new logical send.

Call 4 — legacy caller omits the header:

POST /sms/send
(no Idempotency-Key)

→ 200 {"sms_id": "...", "status": "SENT", ...}

DB: new row, no dedup. If this caller retries, a duplicate SMS will go out. This is backwards compatible for now but callers should add the header; in a future release we will require it.

Notes:

• The Idempotency-Key is scoped to the /sms/send endpoint and to this environment. Don't reuse keys across stage and prod.
• Keys are retained indefinitely; we may add a 30-day TTL later.
• Don't derive the key from the request body; Call 3 shows why the body is allowed to repeat — the key is what uniquely identifies a send.

Returns every inbound SMS joined to the reply (if any), the matched campaign rule, the campaign, and the code's status in the master. parsed_code is masked (U1•••••78) — the full code never leaves the Lambda.

Read-only aggregation for the P4-A manager portal. Group requirement: manager or campaign-admin (admins inherit). SMS metrics are scoped to the resolved campaign; callback and fraud metrics are scoped by date only (no campaign FK in the schema). Simulated rows (is_simulated = true) are excluded.

Totals, product split (Urea/DAP), region breakdown, the received→valid→first-time→registered funnel, and a daily timeseries. Same auth + scoping as /admin/analytics/overview.

Callback counts by status, 24h-SLA compliance, average time-to-first-attempt, the disposition table, and a per-agent rollup. Scoped by date only. Same auth as the other analytics endpoints.

Flags raised, flags closed within the 48h SLA, open flags, blocked numbers by reason, and a daily timeseries. Scoped by date only.

Each headline metric for the current ISO week vs the previous ISO week (Monday-aligned, UTC), with absolute + percentage delta. Feeds the weekly management summary view (SOP 10.5).

Returns up to 500 draw rows ordered by most recent first. Optional filters: campaign_id (UUID), region, status, simulated (true/false). campaign-admin only.

Picks 2 * quota farmers via weighted random sampling without replacement; first quota become primaries (rank 1..N), next quota become alternates. UNIQUE (campaign_id, draw_cycle, region, prize_rank, is_simulated) makes re-submission a no-op — the existing rows are returned with idempotent_replay: true.

Audit: seed (sha256 of inputs) + full eligible pool + ordered picks stored in winner_picks JSONB on every row, together with the campaign's participant_scope and the resolved entries_since cutoff active at execution time (Phase 4-F).

The pool honours campaigns.draw_participant_scope — see the Campaign schema for the two modes. Previous non-disqualified primary winners are always excluded.

On stage with simulated: true, only is_simulated=true farmers are drawn from; on prod the same request returns 422.

Same eligibility filter the draw uses, but returns counts + total weight + a sample of up to 20 farmers for UI preview. The response echoes the campaign's active participant_scope (ALL | SINCE_LAST_DRAW) and the resolved entries_since cutoff (previous draw's execution time for this region, or null when the whole campaign history counts) so the operator can verify the pool before running. campaign-admin only.

Allowed transitions: PENDING → VERIFIED|DISPUTED, VERIFIED → ANNOUNCED|DISPUTED, ANNOUNCED → HANDED_OVER|DISPUTED, HANDED_OVER → DISPUTED, DISPUTED → VERIFIED|ANNOUNCED|HANDED_OVER. Invalid transitions return 409. Disqualification is a separate endpoint.

Promotes the current alternate to primary, picks a new alternate from the frozen winner_picks list (next unused farmer ID that isn't a current primary/alternate on any sibling rank), and resets status to PENDING for fresh verification. Audit-logged. One-way per row.

Creates count farmers in EACH region of regions[], all with is_simulated=true, status REGISTERED, random phone, random demographics, and entry_count randomly distributed in [entry_count_min, entry_count_max]. Total rows created = count * regions.length. One outer transaction wraps every region — a failure mid-array rolls all of them back. Returns 403 on prod. campaign-admin only.

Legacy single-region form ({ region: "X" }) is still accepted for backwards compat.

DB-driven authorization grants. authorize() resolves a person's effective roles as the union of these rows (keyed by email) and the legacy cognito:groups claim, so a granted person lands on their dashboard on the very first Google sign-in — no CLI step. campaign-admin only.

Creates (or reactivates) a grant. pbx_extension is only valid for role: agent and must be unique across agents + grants.

Allowed patch fields: name, description, start_date, end_date, sender_phone, status, prize_quotas, draw_participant_scope. Other fields are silently ignored. prize_quotas is validated against the canonical 8-region set; values must be non-negative integers ≤ 1000. draw_participant_scope must be ALL or SINCE_LAST_DRAW.

Returns 409 with error: scenarios_not_passed or tc_not_updated if the 4-step workflow has not been satisfied.

Runs the entire campaign rules pipeline against the supplied message in a transaction that is always rolled back. No DB writes persist; no outbound SMS is sent. Returns the matched rule, the reply that would have been sent, and the full rule trace.