SMS providers

Receive a send-SMS request and report the result.

SMS providers#

Register an sms binding (store-wide). When the store sends an SMS, Tringify POSTs the message to your endpoint. Verify the signature, hand the message to your provider, and respond synchronously with the result.

Request#

Tringify POSTs this JSON body to your endpoint. message_id is an idempotency key — dedupe on it so a retry does not double-send.

request.json json

{
  "message_id": "a3f1c8e0-...",
  "to": "+919876543210",
  "body": "Your order #1024 has shipped.",
  "category": "transactional",
  "store_id": "8c2b...",
  "store_name": "Acme Store"
}

Field	Notes
message_id	Idempotency key (UUID). Dedupe on it.
to	Destination phone, E.164 format.
body	The rendered message text to send.
category	"transactional" or "marketing".
store_id	The store this send belongs to.
store_name	Display name, for your attribution/logging.

Response#

Respond 200 with this JSON. Set success to true once your provider has accepted the message; include provider_message_id so it can be traced. On failure, return success false with an error code and message — Tringify surfaces a failure to the merchant rather than silently dropping it.

response.json json

{
  "success": true,
  "provider_message_id": "SM1a2b3c...",
  "provider_name": "twilio"
}

response-failed.json json

{
  "success": false,
  "error_code": "invalid_phone",
  "error_message": "Destination number is not valid."
}

Example: Cloudflare Worker#

A minimal SMS provider Worker: verify the signature, look up the merchant's provider credentials (stored by your onboarding flow), send via your provider, and report back.

worker.js javascript

export default {
  async fetch(request, env) {
    const body = await request.text();
    const ts = request.headers.get("X-Tringify-Timestamp");
    const storeId = request.headers.get("X-Tringify-Store-ID");

    if (!(await verify(ts, body, request.headers.get("X-Tringify-Signature"), env.SIGNING_KEY)))
      return new Response("bad signature", { status: 401 });

    const { to, body: text } = JSON.parse(body);
    // Merchant's provider credentials, stored at onboarding (encrypted):
    const creds = await env.MERCHANT_CREDS.get(storeId, "json");

    try {
      const id = await sendViaProvider(creds, to, text);
      return Response.json({ success: true, provider_message_id: id, provider_name: "twilio" });
    } catch (e) {
      return Response.json({ success: false, error_code: "send_failed", error_message: e.message });
    }
  }
};