TACNow

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 prefixBehaviour
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.

FieldTypeRequiredDescription
channelstring✓"whatsapp"
phonestring✓E.164 format, with the + and country code — e.g. +60123456789
codestring✓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.

FieldTypeRequiredDescription
channelstring✓"sms"
phonestring✓E.164 format, with the + and country code — e.g. +60123456789
messagestring✓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.

FieldTypeRequiredDescription
channelstring✓"auto"
phonestring✓E.164 format, with the + and country code — e.g. +60123456789
codestring✓Your code: 4–15 letters or digits, no spaces or symbols
sms_messagestringThe 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:

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

curl -X POST https://api.tacnow.co/v1/otp/send \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
  "channel": "whatsapp",
  "phone": "+60123456789",
  "code": "482913"
}'

SMS example

curl -X POST https://api.tacnow.co/v1/otp/send \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
  "channel": "sms",
  "phone": "+60123456789",
  "message": "Your verification code is 482913. Valid for 5 minutes."
}'

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
}

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_reasonMeaning
sms_unavailableSMS to that number is not open right now
insufficient_balanceYour wallet could not cover the SMS once the WhatsApp charge was returned
otp_expiredWhatsApp reported the failure after the code's validity had passed, so an SMS would carry a dead code
data_unavailableThe 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:

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.

CodeHTTPDescription
INVALID_API_KEY401The API key is missing, malformed, or revoked
IP_NOT_ALLOWED403Request IP is not in the API key's allowlist
PROJECT_SUSPENDED403The project for this API key is archived or not found
INSUFFICIENT_BALANCE402Your organisation wallet balance is too low for this message — nothing was sent or charged
RATE_LIMIT_EXCEEDED429Request rate exceeds the project's per-minute or per-day limit
RECIPIENT_RATE_LIMITED429Too 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_PHONE422phone is missing
INVALID_PHONE422phone is not in E.164 format
INVALID_CHANNEL422channel is not whatsapp, sms or auto
MISSING_CODE422code is missing on a WhatsApp or auto request
INVALID_CODE422code is not 4–15 letters or digits
MESSAGE_NOT_ALLOWED_FOR_CHANNEL422message was sent on a WhatsApp or auto request — send code instead (on auto, sms_message words the SMS)
EXPIRY_NOT_ALLOWED_FOR_CHANNEL422expiry_minutes was sent on a WhatsApp or auto request — the expiry is fixed by the template
INVALID_SMS_MESSAGE422sms_message does not contain {code} exactly once
SMS_MESSAGE_NOT_ALLOWED_FOR_CHANNEL422sms_message was sent on a whatsapp or sms request — it only words the fallback of auto
MISSING_MESSAGE422message is missing on an SMS request
MESSAGE_TOO_LONG422message, 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_CHARACTERS422message or sms_message contains a control, zero-width or text-direction character. Line breaks are fine
TEST_NUMBER_NOT_ALLOWED422A live key sent to the test number +60100000000, which only test keys can use
VALIDATION_ERROR422The request body is not a JSON object
DESTINATION_NOT_SUPPORTED422We 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_UNAVAILABLE503The 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_ERROR500An unexpected server error occurred — retry with exponential backoff