SMS
The SMS channel — Twilio and Netgsm providers, E.164 numbers, segment counting and Turkish characters, short links, STOP/START/HELP automation, MMS and inbound webhooks.
The SMS channel sends through POST /v1/notifications (target.channels: ["sms"]), campaigns and journeys; the body is the contents field (language selection + Liquid). For two-way conversations and keyword automations, see two-way SMS.
Providers
| Provider | Fields (secret in italics) | Validation |
|---|---|---|
twilio | account_sid, auth_token, from_number (E.164 or alphanumeric) or messaging_service_sid | GET /Accounts/{sid}.json |
netgsm | usercode, password, msgheader, iys_filter (0/11/12) | GET /sms/rest/v2/msgheader + header check |
mock | — | simulation |
API: PUT /v1/apps/{app_id}/channels/sms + POST …/validate (admin).
Numbers and subscriptions
- Numbers are stored in E.164 (
+905321234567); on SDK/API registration, spaces, hyphens, parentheses and the00prefix are normalized, and an invalid value returns400. - SDK:
Pushizo.User.addSms('+90 532 …')→POST /sdk/v1/apps/{app_id}/subscriptions(channel: "sms"); for a logged-in user,external_id(+identity_hash) proves ownership; for an anonymous user, the device'ssubscription_iddoes. - Server:
POST /v1/apps/{app_id}/users/by/{label}/{value}/subscriptions{ "channel": "sms", "token": "+90…" }, or send directly withtarget.include_phone_numbers.
Content fields
| Field | Description |
|---|---|
contents | Body (language map, Liquid) |
sms_from | Sender number/header override |
sms_media_urls | MMS media (up to 10, https://); Twilio only — 422 on Netgsm, MMS_NOT_SUPPORTED at send time |
disable_sms_link_shortening | Links are not converted to /t/s/{code} short links |
Segment counting: GSM-7 is 160 characters for a single part / 153 per part for multipart; UCS-2 is 70 / 67. The Turkish letters ş ğ ı İ ç are outside GSM-7 and drop the message to UCS-2; the dashboard warns you. With Netgsm encoding: TR (the Turkish single-shift table), these letters count as 2 septets. The preview POST …/templates/{id}/render (channel: "sms") returns body, encoding, segments, non_gsm_characters, turkish_characters; counts.sms_segments accumulates in the message counters.
Short links: GET /t/s/{code} (8-character base62, 90 days) counts the click and redirects with a 302.
STOP / START / HELP
- STOP → suppression
stop+ subscriptionunsubscribed+subscription.unsubscribedwebhook; START → thestopentry is removed and the subscription becomesactiveagain. - HELP / INFO / YARDIM / BİLGİ (the latter two are the Turkish keywords) →
help; whenapps.settings.sms.autoReplyis on, thehelpReply/stopReplytext is sent as a transactional SMS to that single subscription (preferences). - Sources: Twilio inbound message webhook (Advanced Opt-Out
OptOutTypeor keyword), Netgsm inbox polling (once a minute), generic webhook{ "type": "stop" | "start" | "help", "address": "+90…" }.
Inbound webhooks and reports
URL: Channels → SMS → Webhook URL ({API_URL}/hooks/sms/{twilio|mock}/{token}).
| Provider | Setup | Verification | Events |
|---|---|---|---|
| Twilio | StatusCallback is added automatically on send; set the same URL as the number's A message comes in address | X-Twilio-Signature | delivered, undelivered/failed (+ErrorCode), inbound STOP/START/HELP |
| Netgsm | No push webhook: the worker polls the delivery report (/sms/rest/v2/report, last 72 hours) and the inbox once a minute | — | Report 1 → delivered, 3 → invalid number (subscription invalid) |
Generic (mock) | JSON POST | URL token | delivered, failed, stop, start, help |
Local development
Mock SMS: numbers ending in 0001 are invalid, 0002 permanent failure, 0003 transient, 0004 rate limit, 0005 authentication error; all others succeed. To try STOP: curl -X POST "<webhook URL>" -H 'content-type: application/json' -d '{"type":"stop","address":"+905320000111"}'.
Drag-and-drop email editor
Dashboard → Messages → Email Editor (/{org}/email-designs). Decision record: ADR-0027.
Two-way SMS and keywords
Messages arriving from SMS, WhatsApp and RCS are written to per-contact conversations in the Inbox; keywords defined at org or app level respond to incoming messages with automatic actions (tag, journey trigger, auto-reply,…