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,…
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, subscription)
(docs/adr/0029-whatsapp-rcs-iki-yonlu-sms-eposta-isindirma.md §4–5).
1. Receiving inbound messages
| Provider | Setup |
|---|---|
| Twilio | Enter the webhook URL from the channel card (/hooks/sms/twilio/{token}) in the "A message comes in" field of the Twilio number or Messaging Service; requests are verified with X-Twilio-Signature. |
| Netgsm | No webhook needed; the worker polls the inbox periodically and never processes the same message twice. |
| Mock | POST /hooks/sms/mock/{token} with body { "type": "inbound", "address": "+90…", "body": "…" } (non-production only). |
The inbound number is normalized (E.164). If there is no subscription, a pending subscription without consent is created: the contact appears in the inbox
and can be replied to, but campaigns are not sent to them.
2. Compliance keywords
STOP/STOPALL/UNSUBSCRIBE/CANCEL/END/QUIT/İPTAL/RET/DUR end the subscription; START/YES/UNSTOP/BAŞLA resubscribe (and record consent on WhatsApp); HELP/INFO/YARDIM/BİLGİ are for the help reply (the bold words are the Turkish keywords). These words cannot be defined as custom keywords and are always evaluated before custom keywords.
3. Defining custom keywords
From the Keywords screen in the dashboard, or via the API:
POST /v1/apps/{appId}/sms-keywords
{
"keyword": "indirim",
"channels": ["sms", "whatsapp"],
"actions": {
"add_tags": { "kampanya": "yaz" },
"remove_tags": ["eski"],
"event": { "name": "keyword_indirim", "properties": { "kaynak": "sms" } },
"reply": { "text": "Your code: YAZ20" },
"opt_in": true
}
}- Scope:
scope: "org"applies to all of the org's apps; an app-specific definition takes precedence over an org-wide one. The same keyword in the same scope returns409. - Matching: The first word of the incoming text (trailing punctuation is stripped). Matching is insensitive to Turkish case, dotted/dotless i and
accents:
indirim,İNDİRİM,Indirim!are the same word. A keyword is a single token of letters/digits, up to 30 characters. - Actions:
add_tags/remove_tags(an anonymous user is attached to a subscription without a user),event(records an event → a journey can be started with an event trigger),reply.text(auto-reply; at most once per minute for the same contact + keyword),opt_in(sets the subscription tosubscribedwith consent, sourcekeyword). - A disabled keyword (
enabled: false) runs no actions.
4. Auto-reply and WhatsApp consent
An auto-reply, like an inbox reply, is a transactional message to a single subscription (exempt from quiet hours and frequency caps) and follows the channel's rules:
- On WhatsApp, no auto-reply is sent to a contact without a consent record (
pending); the delivery is suppressed with reasonno_opt_inand appears as suppressed in the conversation. If the keyword has anopt_in: trueaction, consent is recorded first and the reply goes out — use this action in consent collection flows (e.g. "KATIL", Turkish for "JOIN"). - Because the WhatsApp reply falls within the session window (the contact has just written), it is sent as free-form text.
- On SMS, no reply is sent to a number that has opted out with STOP.
5. Replying from the inbox
Open the conversation and type your text (on WhatsApp you can also choose a template or an interactive message; see the
WhatsApp guide). API: POST /v1/apps/{appId}/conversations/{id}/messages { "text": "…" }.
Replying to an unsubscribed or invalid number returns 422. Conversations can be marked as read, closed and reopened.
6. Retention period
Conversation messages are personal data and are subject to the delivery retention period (90 days by default; if the organization setting or plan limit is shorter, that applies). Messages older than the period, and conversations whose last message is older than the period, are deleted by the daily maintenance job.
7. SMS verification code
POST /v1/apps/{appId}/verify/sms { "phone": "+905321112233", "locale": "tr" } starts a code. The response contains only id and expires_at; the code is never returned. POST …/verify/sms/check { "id", "code" } verifies it. Codes are valid for 10 minutes, with 5 starts per number per hour and a lockout after 5 failed attempts. If the Twilio channel has a Verify Service SID (VA…) set, the code is handled by Twilio Verify. Otherwise the active SMS channel sends the code. In the dashboard, it is on the SMS channel card.
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.
WhatsApp (Meta Cloud API): setup, templates, session window and inbox
Pushizo sends WhatsApp messages directly through Meta's Cloud API; no BSP or extra hosting is needed (ADR-0029). The channel requires SMS as a plan feature. For development and testing without an external account, the mock…