Quickstart
Overview
TACNow is a multi-channel TAC / OTP delivery API supporting WhatsApp and SMS. You generate the code and verify it on your side; TACNow delivers it on the channel you choose.
Base URL
https://api.tacnow.co/v1
All requests require Content-Type: application/json and an Authorization header.
Authentication
Authenticate every request with a Bearer token using an API key from your project dashboard.
Authorization: Bearer sk_live_your_api_key_here
TACNow issues two key types per project:
| Key prefix | Behaviour |
|---|---|
sk_live_ | Sends real WhatsApp and SMS messages, and charges each one to your organisation wallet |
sk_test_ | Nothing is sent on either channel, and nothing is charged |
Keep your live keys secret. Rotate them from the console at any time.
Send a TAC
POST /v1/otp/send
One endpoint for both channels. Set channel on every request — the body differs by channel. A request without channel is sent on WhatsApp.
WhatsApp — send the code itself; the message wording is fixed.
| Field | Type | Required | Description |
|---|---|---|---|
channel | string | ✓ | "whatsapp" |
phone | string | ✓ | E.164 format, with the + and country code — e.g. +60123456789 |
code | string | ✓ | Your code: 4–15 letters or digits, no spaces or symbols |
WhatsApp TAC uses Meta's approved authentication template, so the recipient sees "<code> is your verification code." from the TACNow sender. You cannot supply your own wording: sending message on a WhatsApp request is rejected with MESSAGE_NOT_ALLOWED_FOR_CHANNEL. The code's expiry is fixed by the template, so expiry_minutes is rejected with EXPIRY_NOT_ALLOWED_FOR_CHANNEL.
SMS — send the full message text, including your code.
| Field | Type | Required | Description |
|---|---|---|---|
channel | string | ✓ | "sms" |
phone | string | ✓ | E.164 format, with the + and country code — e.g. +60123456789 |
message | string | ✓ | Your message, including the code. It must fit one SMS: 160 characters, or 70 if it contains any character outside the basic SMS alphabet — an emoji, a curly quote ’, Chinese — and ^ { } \ [ ~ ] | € count as two. Line breaks are fine; tabs, zero-width and text-direction characters are refused. |
WhatsApp, falling back to SMS — send the code; if WhatsApp says the number can't receive it, the same code goes by SMS.
| Field | Type | Required | Description |
|---|---|---|---|
channel | string | ✓ | "auto" |
phone | string | ✓ | E.164 format, with the + and country code — e.g. +60123456789 |
code | string | ✓ | Your code: 4–15 letters or digits, no spaces or symbols |
sms_message | string | The SMS wording if it falls back, with {code} exactly once where the code goes, e.g. "Your code is {code}. Do not share it." With the code filled in it must fit one SMS, by the same rule as message. Defaults to "Your verification code is {code}." |
The message is sent and charged as WhatsApp. If Meta reports that the number isn't on WhatsApp (error 131026), TACNow sends the code by SMS instead: the WhatsApp charge is returned and the SMS price is charged, so you pay once, for the channel that delivered. A WhatsApp message that is only slow — the phone is off, say — is not switched to SMS, because it would arrive later and the person would get two codes.
auto needs SMS for the destination. A number in a country with no SMS price is rejected with 422 DESTINATION_NOT_SUPPORTED, on live and test keys alike. Until SMS to Malaysian numbers opens, a live auto send returns 503 CHANNEL_UNAVAILABLE and nothing is charged; a test key accepts it now (see Test Mode).
Requests that omit channel are sent on WhatsApp, so a body with message and no channel is rejected with MESSAGE_NOT_ALLOWED_FOR_CHANNEL. Always send channel explicitly.
Destinations and price. Each send is charged its price for its channel and destination — see the pricing page. Malaysian (+60) numbers are supported today:
- A number in a country we do not carry is rejected with
422 DESTINATION_NOT_SUPPORTEDbefore anything is charged, on live and test keys alike. Other destinations are available on request. - SMS to Malaysian numbers is opening soon. Until then a live SMS send returns
503 CHANNEL_UNAVAILABLEand nothing is charged; a test key accepts it, so you can build and test your SMS integration now.
phone must include the + and country code. TACNow does not guess your country: local
formats such as 0123456789 are rejected with INVALID_PHONE. Send +60123456789.
Spaces and dashes are not stripped either — +6012-345 6789 is rejected.
Response
{
"ok": true,
"message_id": "018f1a2b-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
"status": "queued",
"mode": "live"
}
status is "queued" for live keys — the message is dispatched asynchronously — and "sent" for test keys. Keep message_id to check delivery later.
WhatsApp example
SMS example
Delivery status and resending over SMS
GET /v1/otp/:message_id/status
{
"ok": true,
"message_id": "018f1a2b-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
"status": "sent",
"mode": "live",
"channel": "whatsapp",
"queued_at": "2026-09-14T10:00:00Z",
"sent_at": "2026-09-14T10:00:02Z",
"failed_at": null,
"delivery_status": "delivered",
"delivered_at": "2026-09-14T10:00:04Z",
"error_code": null,
"fallback": null
}
statusis submission:pending,enqueued,sentorfailed.sentmeans the provider accepted the message, not that it arrived.delivery_statusis delivery, and only WhatsApp has it:accepted,sent,delivered,readorfailed. It is alwaysnullfor SMS, because SMS carrier receipts in Malaysia are not reliable enough to report.
On "channel": "whatsapp", TACNow does not switch channels for you. If a WhatsApp message comes back with delivery_status: "failed" — for example, the number is not on WhatsApp — send a new request with "channel": "sms". The charge for the failed WhatsApp message is returned to your wallet automatically.
On "channel": "auto", it does that for you when the number isn't on WhatsApp. Poll the same message_id: once an SMS has gone in its place, the response describes the SMS (channel: "sms", its own status and sent_at) and carries a fallback object — { "from": "whatsapp", "to": "sms", "reason": "131026", "at": "…", "skipped_reason": null }. The WhatsApp charge is returned and the SMS price is charged instead. fallback is null for every other request.
If no SMS went, to is null and skipped_reason says why:
skipped_reason | Meaning |
|---|---|
sms_unavailable | SMS to that number is not open right now |
insufficient_balance | Your wallet could not cover the SMS once the WhatsApp charge was returned |
otp_expired | WhatsApp reported the failure after the code's validity had passed, so an SMS would carry a dead code |
data_unavailable | The number or code was no longer held, so there was nothing to send |
In each case the WhatsApp charge is still returned. An auto request is not final at status: "sent": WhatsApp can report that the number is not on WhatsApp after accepting the message, and the request then moves to an SMS that starts again at pending. Keep polling until delivery_status is delivered or read, status is failed, or fallback is set and its SMS is sent or failed.
Test Mode
Use a sk_test_ API key to develop and test without sending real messages or spending from your wallet.
Authorization: Bearer sk_test_your_test_key
In test mode:
- Nothing is delivered on WhatsApp or SMS
- Nothing is charged to your organisation wallet
- The response shape is identical to live mode — your code doesn't need to change
- Validation is identical too, so channel rules such as
MESSAGE_NOT_ALLOWED_FOR_CHANNELare caught before you go live - Delivery logs show
mode: "test"so you can distinguish them in the dashboard - The test number
+60100000000behaves as if it isn't on WhatsApp: awhatsapprequest to it fails with131026, and anautorequest falls back to SMS — so you can watch the fallback end to end before SMS opens. It is for test keys only: a live key sending to it gets422 TEST_NUMBER_NOT_ALLOWED
Switch to a sk_live_ key when you're ready to go live. No other code changes needed.
Wallet balance
GET /v1/balance
{
"ok": true,
"balance": "485.12",
"currency": "MYR",
"project_id": "018f1a2b-...",
"org_id": "a52899ab-...",
"scope": "organisation"
}
balance is your organisation wallet in ringgit, as a decimal string, shared by every project. GET /v1/usage reports amount_consumed in ringgit the same way.
Error Codes
All error responses follow this shape:
{
"ok": false,
"error": "ERROR_CODE",
"message": "Human-readable description",
"field": "phone"
}
field is present when a specific request field caused the error. Every response carries X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day headers, and a 429 also includes the wait in seconds: retryAfter for RATE_LIMIT_EXCEEDED, retry_after_seconds and a Retry-After header for RECIPIENT_RATE_LIMITED.
| Code | HTTP | Description |
|---|---|---|
INVALID_API_KEY | 401 | The API key is missing, malformed, or revoked |
IP_NOT_ALLOWED | 403 | Request IP is not in the API key's allowlist |
PROJECT_SUSPENDED | 403 | The project for this API key is archived or not found |
INSUFFICIENT_BALANCE | 402 | Your organisation wallet balance is too low for this message — nothing was sent or charged |
RATE_LIMIT_EXCEEDED | 429 | Request rate exceeds the project's per-minute or per-day limit |
RECIPIENT_RATE_LIMITED | 429 | Too many codes sent to this phone recently: your organisation can send one number at most 1 code every 30 seconds, 5 an hour and 10 a day, across all your projects, and a number receiving codes from several senders may be limited sooner. Nothing was sent or charged. Test mode is not limited |
MISSING_PHONE | 422 | phone is missing |
INVALID_PHONE | 422 | phone is not in E.164 format |
INVALID_CHANNEL | 422 | channel is not whatsapp, sms or auto |
MISSING_CODE | 422 | code is missing on a WhatsApp or auto request |
INVALID_CODE | 422 | code is not 4–15 letters or digits |
MESSAGE_NOT_ALLOWED_FOR_CHANNEL | 422 | message was sent on a WhatsApp or auto request — send code instead (on auto, sms_message words the SMS) |
EXPIRY_NOT_ALLOWED_FOR_CHANNEL | 422 | expiry_minutes was sent on a WhatsApp or auto request — the expiry is fixed by the template |
INVALID_SMS_MESSAGE | 422 | sms_message does not contain {code} exactly once |
SMS_MESSAGE_NOT_ALLOWED_FOR_CHANNEL | 422 | sms_message was sent on a whatsapp or sms request — it only words the fallback of auto |
MISSING_MESSAGE | 422 | message is missing on an SMS request |
MESSAGE_TOO_LONG | 422 | message, or sms_message with the code filled in, does not fit one SMS — 160 characters, or 70 with any character outside the basic SMS alphabet |
MESSAGE_INVALID_CHARACTERS | 422 | message or sms_message contains a control, zero-width or text-direction character. Line breaks are fine |
TEST_NUMBER_NOT_ALLOWED | 422 | A live key sent to the test number +60100000000, which only test keys can use |
VALIDATION_ERROR | 422 | The request body is not a JSON object |
DESTINATION_NOT_SUPPORTED | 422 | We do not carry this number's country on this channel — on auto, on WhatsApp or on SMS — nothing was charged. Malaysian (+60) numbers are supported |
CHANNEL_UNAVAILABLE | 503 | The channel is not available for live sends to this destination yet (SMS to Malaysia until it opens — and so auto, which needs SMS) or temporarily — use another channel, or test mode |
INTERNAL_ERROR | 500 | An unexpected server error occurred — retry with exponential backoff |