PushizoDocs
Channels

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

ProviderSetup
TwilioEnter 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.
NetgsmNo webhook needed; the worker polls the inbox periodically and never processes the same message twice.
MockPOST /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 returns 409.
  • 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 to subscribed with consent, source keyword).
  • 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 reason no_opt_in and appears as suppressed in the conversation. If the keyword has an opt_in: true action, 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.

On this page