A customer texts GOAL to your shortcode — the carrier debits their airtime, your webhook fires, you respond with the content. Perfect for quizzes, scores, lottery numbers, weather, tips and lookups.
The customer's text is what initiates the chain — that's how the carrier knows to charge for the reply.
e.g. GOAL to 84320. The carrier routes it to Sozuri, which fires a linkNotification webhook with a unique linkId.
POST to /v1/premium with type: "ondemand" and the linkId echoed back. That's what tells the carrier to bill this one request.
Subscriber's airtime is debited, your share lands on the monthly reconciliation statement. A premiumDelivery webhook confirms success.
linkId is the whole trick.Without it, the carrier won't charge. With it, billing is automatic and reconciled to the cent. Always echo back the value you received on the inbound webhook.
linkId means the reply is sent for free — no carrier bill, no revenue. Always validate before responding.
# Reply to an inbound keyword request
curl -X POST "https://api.sozuri.net/v1/premium" \
-H "Authorization: Bearer $SOZURI_API_KEY" \
-d '{
"project": "Bunge Quiz",
"from": "84320",
"to": "+254712345678",
"channel": "premium",
"type": "ondemand",
"keyword": "QUIZ",
"linkId": "LNK-9X4K7P",
"message": "Q1. Which county hosts Lake Magadi? A/B/C.",
"campaign": "trivia-thursday"
}'One keyword per round, one fee per answer. Bunge nights, weekend trivia, sports tipping.
FPL, AFCON, KPL, NBA — text the match keyword, get the current scoreline and stats.
Weather by location, drug interaction checks, exam revision answers, fuel prices, market rates.
Yes. A single premium shortcode (e.g. 84320) can host both models. Each keyword is provisioned individually with its own tariff and billing model.
The linkId stays valid for the carrier's session window (typically a few minutes). After that, the customer's request is treated as expired and a fresh keyword text is required to bill again.
Best practice is to respond within a few seconds so the customer experiences the reply as part of the same exchange. Sozuri tracks the gap and reports it on the delivery webhook.
Each carrier sets the per-request tariff at contract time, typically KSh 5, 10, 20 or 50. Higher tariffs require stronger content review. The same shortcode can host multiple keywords at different tariffs.
One shortcode. As many keywords as your content can support. Carrier-billed, opt-in-by-default, friction-free for the customer and for you.