{"name":"message-receiver","title":"Message Receiver","version":"1.0.0","baseUrl":"https://message-receiver.wyzetalk.cloud","canonicalBaseUrl":"https://message-receiver.wyzetalk.cloud","purpose":"Test sink / broker for proving a delivery process ran. Record email (real inbound), SMS, and push, then query by testId. SMS and push are provider stubs: POST records the handoff; this does not send to a telco or APNs/FCM.","notFor":["Sending real SMS through a carrier","Sending real push through APNs or FCM","Long-term message storage"],"ttlSeconds":259200,"auth":{"requiredOn":"All /v1/* routes","headers":["Authorization: Bearer <API_KEY>","X-API-Key: <API_KEY>"],"example":"Authorization: Bearer $MESSAGE_RECEIVER_API_KEY","secretName":"MESSAGE_RECEIVER_API_KEY"},"testId":{"description":"Correlate a send with a later lookup. Unique per test run.","explicitField":"testId","bracketPattern":"[test-id]","rule":"Use an explicit testId on SMS/push JSON, or put the id in the last [square-bracket] group of the email subject, SMS body, or push title/body.","example":"Password reset [e2e-7f3a1c2e]"},"polling":{"description":"Lookups are poll-friendly. Retry on 404 until timeout. Do not retry 401/400.","foundStatus":200,"notFoundStatus":404,"unauthorizedStatus":401,"intervalMs":2000,"timeoutMs":60000,"stopWhen":"HTTP 200 with found=true"},"publicEndpoints":[{"method":"GET","path":"/health","description":"Liveness. Returns { ok: true }."},{"method":"GET","path":"/docs.json","description":"This document. No API key."},{"method":"GET","path":"/","description":"Same as /docs.json. No API key."}],"endpoints":[{"id":"post-sms","method":"POST","path":"/v1/sms","auth":true,"description":"Record an SMS as if this Worker were the SMS provider. Tests process dispatch, not the telco.","body":{"to":"required. Destination MSISDN or address.","body":"required. SMS text. May include [testId].","from":"optional. Sender id or short code.","reason":"optional. Why it was sent, e.g. otp-login.","testId":"optional. Overrides [..] extraction from body.","sentAt":"optional. ISO-8601 timestamp."},"successStatus":201,"success":{"id":"generated-uuid","type":"sms","to":"+27821234567","from":"WyzeTalk","body":"Your login code is 123456 [e2e-sms-9]","reason":"otp-login","testId":"e2e-sms-9","sentAt":"2026-08-17T13:00:00.000Z","receivedAt":"2026-08-17T13:00:00.000Z"}},{"id":"get-sms","method":"GET","path":"/v1/sms","auth":true,"description":"Look up a recorded SMS.","query":{"testId":"preferred correlation key","id":"generated message id from POST"},"successStatus":200,"success":{"found":true,"type":"sms","id":"uuid","testId":"e2e-sms-9"},"notFound":{"found":false,"error":"not_found","message":"No matching SMS."}},{"id":"post-push","method":"POST","path":"/v1/push","auth":true,"description":"Record a push as if this Worker were the push provider. Tests process dispatch, not APNs/FCM.","body":{"deviceId":"required unless deviceToken is set","deviceToken":"required unless deviceId is set","platform":"optional. ios | android | web","title":"optional. May include [testId].","body":"optional. May include [testId].","data":"optional. JSON object, max 8KiB.","reason":"optional. Why it was sent, e.g. chat-message.","testId":"optional. Overrides [..] extraction from title/body.","sentAt":"optional. ISO-8601 timestamp."},"successStatus":201,"success":{"id":"generated-uuid","type":"push","deviceId":"device-42","testId":"e2e-push-1","reason":"chat-message"}},{"id":"get-push","method":"GET","path":"/v1/push","auth":true,"description":"Look up a recorded push. deviceId returns the latest push for that device.","query":{"testId":"preferred correlation key","deviceId":"latest push for this device","id":"generated message id from POST"},"successStatus":200,"success":{"found":true,"type":"push","id":"uuid","testId":"e2e-push-1"},"notFound":{"found":false,"error":"not_found","message":"No matching push."}},{"id":"get-email","method":"GET","path":"/v1/emails","auth":true,"description":"Look up a real inbound email captured by the email() handler. Do not POST email here.","query":{"testId":"from the last [..] in the subject","messageId":"RFC Message-ID","id":"generated id assigned on ingest"},"successStatus":200,"success":{"found":true,"type":"email","from":"noreply@app.example","to":"inbox@your-domain.example","subject":"Password reset [e2e-7f3a1c2e]","testId":"e2e-7f3a1c2e"},"notFound":{"found":false,"error":"not_found","message":"No matching email."}},{"id":"get-message","method":"GET","path":"/v1/messages/{id}","auth":true,"description":"Look up any recorded message by generated id. Also GET /v1/messages?type=sms&testId=...","successStatus":200,"success":{"found":true,"type":"sms","id":"uuid"},"notFound":{"found":false,"error":"not_found","message":"No matching message."}}],"scenarios":[{"id":"sms-provider","title":"Prove an SMS dispatch ran","when":"Your mailer/SMS pipeline should call this Worker instead of a telco during tests.","steps":[{"action":"Generate a unique testId (UUID)."},{"action":"POST the SMS to this broker as the provider.","method":"POST","path":"/v1/sms","body":{"to":"+27821234567","from":"WyzeTalk","body":"Your login code is 123456 [TEST_ID]","reason":"otp-login","testId":"TEST_ID"},"notes":"Expect 201. The JSON includes id. This is the handoff; no SMS is sent to a network."},{"action":"Query until found (optional if you already have the 201 body).","method":"GET","path":"/v1/sms?testId=TEST_ID","notes":"Poll every 2s until 200 or 60s timeout. 404 means not stored yet."},{"action":"Assert to, body, reason, and testId on the stored record."}]},{"id":"push-provider","title":"Prove a push dispatch ran","when":"Your push sender should POST here instead of APNs/FCM during tests. The app can also query that the notification was recorded.","steps":[{"action":"Generate a unique testId (UUID)."},{"action":"POST the push payload.","method":"POST","path":"/v1/push","body":{"deviceId":"device-42","deviceToken":"fcm-or-apns-token","platform":"android","title":"New message","body":"You have a chat [TEST_ID]","reason":"chat-message","testId":"TEST_ID","data":{"conversationId":"c-1"}},"notes":"Expect 201. Requires deviceId or deviceToken."},{"action":"Look up by testId or device.","method":"GET","path":"/v1/push?testId=TEST_ID","notes":"App/device query: GET /v1/push?deviceId=device-42 returns the latest push for that device."}]},{"id":"email-inbound","title":"Prove an email arrived","when":"A real email is sent to the Cloudflare Email Routing address that targets this Worker. There is no POST /v1/emails.","steps":[{"action":"Generate a unique testId (UUID)."},{"action":"Send email to the routed inbox with the id at the end of the subject.","notes":"Subject example: Password reset [TEST_ID]. The Worker cannot return an id to the sender; correlate via testId."},{"action":"Poll for the captured email.","method":"GET","path":"/v1/emails?testId=TEST_ID","notes":"Retry on 404. Success is 200 with found=true, from, to, subject, date, messageId, id."}]}]}