Passing incoming messages to your own system
Screens: Received SMS, address /incoming/received — where you check the result;
Settings → API, address /settings?tab=api — the part of all this that has a field in
the cabinet.
Everything else on this page is set up by support, on your keyword. The page is here so that you know what exists and what to ask for by name.
The simple case: an automatic reply
A keyword can carry one fixed text that goes back to every subscriber who writes to it. The same text goes to everyone, whatever they wrote, and it needs no system of yours — it is the answer for "tell them we got it". It is set up together with the keyword, and you see the result in the report, in the Reply line of the row.
The real case: your system is asked what to answer
Instead of a fixed text, SMS-Docs calls your address with the incoming message and sends the subscriber whatever your handler returns.
The rules to design your handler around:
- Answer quickly. The subscriber is waiting with the phone in hand.
- Answer with the message text and nothing else. Plain text, the way it should reach the phone — not a page, not JSON with a text inside.
- Keep it to the length of an ordinary SMS. An answer of that length goes straight to the subscriber, and the Reply column in the report shows what went out.
Support states the exact timeout and the exact length that apply to your keyword.
The address that receives incoming messages, and its format, are set up by support. The field URL for notifications in Settings → API is a different mechanism: it reports the fate of the messages you send, and the API section of this documentation describes its format.
A notification to a person instead
When the arrival should simply reach a person, SMS-Docs reports it by e-mail, or by SMS to a number you name.
It is sent from your account and charged like any SMS you send yourself: a busy keyword means one notification per incoming message, and the incoming report shows those charges in its own column. An e-mail notification carries the same news.
Delivery over SMPP
If you already work over SMPP, incoming messages can be handed to your bound session instead of being sent to an address. The bind itself is switched on in Settings → API, and it needs the IP address you connect from. Support routes the incoming messages into that session.
Two ready-made keywords
Two keywords belong to SMS-Docs itself and work the same way for everyone:
- one tops up an account balance by SMS;
- one starts a prepared campaign by SMS.
They are worth knowing about for one practical reason: they are already taken, so choose a keyword of your own that differs from them. If either of them is useful to you, support switches it on for your account.