One-time codes
Send a one-time code (OTP) with the otp template. You send the code and how long it works for. Ponitor writes the message and sends it ahead of your other SMS.
Why codes go through the template
Orange and MTN can block a code in a wording they haven't agreed to, so a customer waiting to log in never gets it. The otp template always writes the agreed wording:
Hello! Your verification code is 482910. Valid for 10 minutes.
The message names no one: the SMS shows as from your Sender ID. You can't change the words, so a code can't go out in a wording the networks block. Send every other message, such as a receipt or a reminder, as text.
Send a code
curl -X POST $PONITOR_BASE_URL/messaging/v1/sms \
-H "apiKey: $PONITOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sender": "ACME",
"recipient": "+231770000000",
"externalId": "login-58213",
"template": {
"id": "otp",
"parameters": { "code": "482910", "duration": "10 minutes" }
}
}'
| Field | What to send |
|---|---|
sender | Your Sender ID or Short Code, exactly as approved. It's who the SMS shows as from. |
recipient | An Orange or MTN number, in international format. |
externalId | Your own reference, unique within your team. Use a new one for each code. |
template.id | otp. It's the only template an SMS can be sent with. |
template.parameters.code | The code: 4 to 10 digits, as a string so leading zeros stay. |
template.parameters.duration | How long the code works, as your customer should read it, such as "10 minutes", "1 hour" or "2 days". Up to 20 characters, on one line. Ponitor puts it in as you send it. |
Send template instead of text, never both. Every field is described in Send an SMS.
The response is the same as for any SMS, with the message Ponitor wrote in text and the code hidden. See Read the response and Ponitor doesn't keep the code.
What's different about a code
| A one-time code | Any other SMS | |
|---|---|---|
| Wording | Ponitor's, agreed with Orange and MTN | Yours |
| Place in the queue | Ahead of your other SMS, including campaigns | In the order sent |
| Price | The same as any SMS. The message is one part. | Per part. See Length and parts. |
Ponitor sends the code but doesn't track when it stops working: your app does. A code that reaches the phone late is one your app turns away, so check the expiry on your side when the customer types it in.
Ponitor doesn't keep the code
Checking the code is your app's job. So once the network has the message, Ponitor keeps no copy of the code. Everywhere you see the message, one dot stands in for each digit:
Hello! Your verification code is ••••••. Valid for 10 minutes.
That's the text in the send response, in Get an SMS, in your webhooks, in Messages in the app and in exports. Anyone who can see your team's messages can't read a customer's code. If you need a record of which code went to whom, keep it in your own system, keyed by your externalId.
When a send is refused
| Status | Why | Fix |
|---|---|---|
400 | template.id must be "otp" | Send otp as the id. |
400 | template.parameters.code must be 4 to 10 digits | Send the code as a string of digits, such as "048213". |
400 | template.parameters.duration is missing, longer than 20 characters, or on more than one line. | Send a short duration, such as "10 minutes". |
400 | Send template or text, not both | Leave out text. |
Nothing is charged for a refused send. The other refusals, such as a sender that isn't approved, are the same as for any SMS. See When a send is refused.
Codes in the app
Every team's SMS › Templates shows the OTP template, marked as Ponitor's. Nobody can change or delete it, and it isn't offered when you write a message in the app: a code typed by hand goes as an ordinary SMS, without its place at the front of the queue. Send codes through the API.