An SMS application is an application that uses its own balance, shared from your main balance: you choose how much of your main balance to share with it. It has its own API key. A call made with that key sends from the balance of that application only, never from your main balance, and when that balance is finished the application stops sending. You can give the key to the person or the system that uses the application without giving them your account key.
A new key replaces the old one at once. Revoke a key to stop the person or the system that uses it.
Send the key of the application in the X-API-Key header, like the account key. The key tells us which application it is.
X-API-Key: tmwapp_YOUR_APPLICATION_KEY
https://telcomw.com/api/v3| Call | Request | What it does |
| Single SMS | POST /api/v3/sms/send |
Send one message to one phone number. |
| Broadcast SMS | POST /api/v3/sms/broadcast |
Send one message to many phone numbers in a single request. The message is written once. |
| Personalised Batch SMS | POST /api/v3/sms/batch |
Send a different message to each phone number in a single request, for example a name or a code in every message. |
| Delivery Reports | GET /api/v3/sms/delivery-reports |
The delivery status of the messages this SMS application sent. |
| Message Status | GET /api/v3/sms/{message_id} |
The delivery status of one message this SMS application sent. |
| Application Balance | GET /api/v3/account/balance |
The balance of the SMS application, to check before a large send. |
| Sender IDs | GET /api/v3/sender-ids |
The sender IDs you can send from. Ask for new ones in the dashboard, under Account. |
Nothing else: any other call, such as campaigns, is refused with 403.
curl -X POST https://telcomw.com/api/v3/sms/send \
-H 'X-API-Key: tmwapp_YOUR_APPLICATION_KEY' \
-H 'Content-Type: application/json' \
-d '{"to":"0999123456","message":"Hello from TelcoMW","sender_id":"WGIT"}'
The call is refused with 402 and INSUFFICIENT_APPLICATION_BALANCE, and nothing is sent or charged. Sending continues after the application is funded. A switched-off application is refused with APPLICATION_INACTIVE.
Everything else is the same as in SMS V3: numbers, sender IDs, prices, scheduling, X-Duplicate-Guard, statuses and errors.
| Code | HTTP | What it means |
INVALID_API_KEY | 401 | The API key is not valid, or the account is not active. |
RATE_LIMITED | 429 | Too many requests. Wait the number of seconds in the Retry-After header. |
APPLICATION_INACTIVE | 403 | The SMS application is inactive. Enable it in the dashboard (SMS Applications), then send again. Nothing was sent or charged. |
INSUFFICIENT_APPLICATION_BALANCE | 402 | The SMS application does not have enough balance. Fund it from your main balance in the dashboard. details.required and details.balance say how much. |
KEY_NOT_ALLOWED | 403 | The API key of an SMS application was used for something other than sending and reading what it sent (campaigns, for example). Use the account API key for that. |
APPLICATION_KEY_MISMATCH | 403 | The key belongs to one SMS application and the x-application-id header names another. Leave the header out when you use an application key. |
Need help? Contact us on WhatsApp.