mirror of https://git.meshkee.com/Meshkee/backend.git synced 2026-08-11 22:30:59 +04:30

Files

T

Alireza HassaniandCursor f4295e780c Add partner SMS gateway via Gama SendQuick and document it.

Expose POST /public/sms/send with API key + domain allowlist for external backends like Balout, wire Meshkee OTP/message sends to Gama, and publish Partner SMS docs on /docs/website.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-04 11:09:21 +03:30

2.5 KiB

Raw Permalink Blame History

Partner SMS gateway

Server-to-server SMS via Meshkee → Gama (گاما). Use this when a non-Meshkee (or partner) backend needs to send SMS through the shared Meshkee account.

Not for browser/storefront JavaScript. Never put the API key in frontend code.

Hub: https://api.meshkee.com/docs/website
Endpoint docs also in OpenAPI / Postman under Partner SMS.

Endpoint

POST https://api.meshkee.com/api/v1/public/sms/send
Content-Type: application/json
X-Api-Key: <partner-secret>

Body

Field	Required	Description
`domain`	yes	Allowlisted partner apex, e.g. `baloutpastry.com` (`www.` is stripped)
`to`	yes	Mobile: `09…`, `9…`, `+989…`, or `989…`
`message`	yes	Free text, max 700 characters

Example (Balout)

curl -sS -X POST 'https://api.meshkee.com/api/v1/public/sms/send' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <YOUR_PARTNER_KEY>' \
  -d '{
    "domain": "baloutpastry.com",
    "to": "09127004945",
    "message": "سفارش شما به شماره ی ۱۲۱۱۳۲۲ اماده می باشد."
  }'

Success (200)

{
  "success": true,
  "serverId": "1136923081051406337"
}

serverId is the Gama message id (delivery tracking).

Errors

HTTP	Meaning
400	Invalid phone or empty/too-long message
401	Missing/invalid `X-Api-Key` or domain not allowlisted
429	Rate limit: 30/partner/minute or 5/destination/minute
503	SMS disabled, missing provider config, or Gama unreachable

Auth model

Meshkee configures SMS_PARTNERS=domain:apiKey,... on the API server.
Partner backend sends X-Api-Key + matching domain in the JSON body.
Key must match that domain (timing-safe compare). www.baloutpastry.com normalizes to baloutpastry.com.

First allowlisted partner: baloutpastry.com.

Sender line (v1)

Uses the service shortcode only (SendQuick). Advertising / bulk / OTP pattern APIs are not exposed yet.

Rules for partner backends

Call from your server only (Balout API → Meshkee API).
Keep the API key in server env / secrets — never in the website frontend.
Prefer short transactional messages (order ready, OTP-style text, etc.).
Respect rate limits; backoff on 429.
Meshkee websites that already use customer auth OTP go through Meshkee’s own auth/SMS path — they do not need this partner endpoint.

2.5 KiB Raw Permalink Blame History Unescape Escape