SMS Messaging API: HTTP Documentation Code Samples Best Practices
Updated: Oct 2
By TechTo Networks · Originally published June 12, 2025 · Reviewed and updated periodically
This page documents TechTo's actual SMS messaging API the real request format, authentication, and working code in five languages rather than a generic or hypothetical one. If you're still deciding whether you need an SMS API at all, or want the fuller picture of why India's compliance framework matters, start with the SMS API overview instead; this page assumes you're ready to integrate.
What an SMS Messaging API Does
An SMS messaging API lets your application send text messages programmatically — triggered by a signup, an order, or any event your system already knows about — rather than requiring a person to send each message manually. TechTo's version of this is built around direct connectivity into Jio, Airtel, Vi, and BSNL, with India's DLT compliance framework built into onboarding rather than left for you to navigate alone.
TechTo's Real API: Three HTTP Variants
The most important thing to know before writing any code: TechTo's SMS API is an HTTP GET, query-parameter API — not a JSON REST API with Bearer-token authentication, which is a common and incorrect assumption carried over from other providers' documentation styles. There are three variants, differing in authentication and response format.
1. Tally HTTP API (username/password)
The simplest variant — credentials passed directly as query parameters, no token management required.
2. Token-Based HTTP API (JSON status responses)
Authenticates with an account token instead of shared credentials, adds a templateid parameter for your DLT-approved template, and exposes two additional JSON-returning endpoints:
Delivery Report: ?token=...&messageid=... → per-number delivery status as a JSON array.
Available Credits: ?token=...&route=... → remaining credits by route, as JSON.
This is the variant most application integrations should use — tokens are easier to rotate than shared credentials, and the JSON responses on the status endpoints are simpler to build a dashboard around.
3. XML API
The same parameters wrapped in a URL-encoded XML payload, for systems (older ERPs, some enterprise middleware) that already standardize on XML.
Shared Parameters Across All Three
Parameter | Meaning |
sender | Your DLT-registered sender ID |
number | Recipient number(s); comma-separated for identical-message bulk sends |
route | Promotional (1), Transactional (2), Sender ID (3), Trans OTP (4, token/XML), International (9), Trans2 (10) |
type | Text (1), Flash (2), Unicode (3) |
sms | Message content, URL-encoded |
templateid | DLT-approved template ID (required on token and XML variants) |
A successful call returns a numeric message ID as plain text. A failure returns a documented numeric error code (see the Error Handling section below). There's no documented webhook for push delivery notifications and no documented scheduling parameter — both are things your own backend handles, using the token variant's delivery-report lookup for status and your own queue or scheduler for timing.
One integration detail worth knowing up front: the number field supports identical-message bulk sending via comma-separation, but does not support per-recipient personalization in a single call — a personalized send (different name, amount, or order ID per recipient) requires looping through your list and calling the API once per recipient.
For the complete, authoritative parameter list — including any additions since this page was last reviewed — see the HTTP API reference.
HTTP vs. SMPP: Choosing Your Integration Path
Most businesses should start with the HTTP API above. It's stateless, requires no persistent connection, and is straightforward to call from any language with basic HTTP support.
SMPP (Short Message Peer-to-Peer) is a persistent, binary protocol used where sustained high-throughput matters more than integration simplicity — typically once a business is sending at a scale where per-request HTTP overhead becomes a real bottleneck, or when building a reseller platform on top of TechTo's infrastructure. A persistent SMPP connection generally supports higher sustained throughput per connection than making one HTTP request per message, which is why very high-volume senders move to it.
TechTo documents SMPP as an available option for accounts that need it — see TechTo's SMPP page for connection specifics, since SMPP setup (host, port, system ID, bind credentials) is account-specific and provisioned during onboarding rather than published generically.
Practical guidance: if you're sending OTPs, transactional alerts, or moderate-to-high promotional volume and want to integrate quickly, the HTTP API is the right starting point — most businesses never need to move off it. If you're approaching a volume where connection overhead itself is becoming the limiting factor, that's the point to discuss SMPP with TechTo's team directly, with your actual volume numbers in hand.
Understanding Throughput (TPS): What to Actually Check
TPS — transactions per second — is how many messages your account can push through before additional messages queue rather than send immediately. It's a genuinely important number, and also one worth getting from TechTo directly for your specific account rather than from any published figure, including an earlier version of this page that stated specific numbers without verified backing.
What's true about TPS regardless of provider:
It's typically tiered by account plan and by route — your OTP route may carry a different TPS allocation than your Promotional route, which is a normal and reasonable configuration, not a limitation.
HTTP and SMPP have structurally different throughput characteristics. A persistent SMPP connection avoids the per-request overhead of repeated HTTP calls, which is part of why high-volume senders use it — but the HTTP API is entirely sufficient for the large majority of use cases, including most OTP and transactional traffic.
A provider that won't give you a specific TPS number for your account tier is telling you something worth noting. Ask TechTo directly for your account's current TPS allocation by route, in writing, before committing to a plan where throughput is a hard requirement — a product launch with a traffic spike, for instance — rather than assuming a general figure applies to your specific account.
This is a case where precision means telling you exactly what to verify, rather than supplying a number that sounds authoritative but isn't independently confirmed for your account.
Authentication Details by Variant
Tally variant: username and password passed as plain query parameters on every request. Treat these exactly as you would any other credential — never embed them in a mobile app or browser-side code, and mask them in logs (since they appear in the request URL on a GET-based API).
Token variant: a single token value replaces the username/password pair. Easier to rotate without touching your account's primary login credentials — prefer this variant for any new integration where credential rotation matters.
XML variant: uses the same credential model as whichever base it's layered on (confirm with the HTTP API reference for current specifics), with the message payload itself structured as XML rather than flat parameters.
In all three cases: call from your backend, never from a distributed client, and store credentials in environment variables or a secrets manager rather than hardcoded in source.
Code Samples
All five samples below send a transactional message using the token variant. Replace the placeholder credential and endpoint values with your account's actual details, and confirm the exact endpoint path against the HTTP API reference before relying on these in production.
Python
import requests
API_TOKEN = "YOUR_API_TOKEN"
BASE_URL = "https://godspeed.liveair.co.in/httpapi/tokan/"
def send_sms(sender: str, number: str, message: str, route: str = "2", msg_type: str = "1") -> str:
params = {
"token": API_TOKEN,
"sender": sender,
"number": number,
"route": route, # 2 = Transactional
"type": msg_type, # 1 = Text
"sms": message,
}
response = requests.get(BASE_URL, params=params, timeout=10)
return response.text.strip() # numeric message ID, or a documented error code
print(send_sms("TECHTO", "9198XXXXXXX0", "Your order #4821 has been confirmed."))
Node.js
const axios = require("axios");
const API_TOKEN = "YOUR_API_TOKEN";
const BASE_URL = "https://godspeed.liveair.co.in/httpapi/tokan/";
async function sendSms(sender, number, message, route = "2", type = "1") {
const response = await axios.get(BASE_URL, {
params: { token: API_TOKEN, sender, number, route, type, sms: message },
timeout: 10000,
});
return String(response.data).trim();
}
sendSms("TECHTO", "9198XXXXXXX0", "Your order #4821 has been confirmed.")
.then(console.log);
PHP
<?php
function sendSms(string $sender, string $number, string $message, string $route = "2", string $type = "1"): string {
$params = [
"token" => "YOUR_API_TOKEN", "sender" => $sender, "number" => $number,
"route" => $route, "type" => $type, "sms" => $message,
];
$url = "https://godspeed.liveair.co.in/httpapi/tokan/?" . http_build_query($params);
return trim(file_get_contents($url));
}
echo sendSms("TECHTO", "9198XXXXXXX0", "Your order #4821 has been confirmed.");
Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
public class TechToSms {
static final String BASE_URL = "https://godspeed.liveair.co.in/httpapi/tokan/";
static final String API_TOKEN = "YOUR_API_TOKEN";
public static String sendSms(String sender, String number, String message, String route, String type) throws Exception {
String query = String.format(
"token=%s&sender=%s&number=%s&route=%s&type=%s&sms=%s",
API_TOKEN, sender, number, route, type,
URLEncoder.encode(message, StandardCharsets.UTF_8)
);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "?" + query))
.timeout(java.time.Duration.ofSeconds(10))
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
return response.body().trim();
}
public static void main(String[] args) throws Exception {
System.out.println(sendSms("TECHTO", "9198XXXXXXX0", "Your order #4821 has been confirmed.", "2", "1"));
}
}
cURL
curl -G "https://godspeed.liveair.co.in/httpapi/tokan/" \
--data-urlencode "token=YOUR_API_TOKEN" \
--data-urlencode "sender=TECHTO" \
--data-urlencode "number=9198XXXXXXX0" \
--data-urlencode "route=2" \
--data-urlencode "type=1" \
--data-urlencode "sms=Your order #4821 has been confirmed."
Important for every sample above: the message text must match your DLT-registered template exactly, with only the genuinely variable portions (order number, in this example) coming from application data — a static-text mismatch is blocked at the carrier level, not delivered with a warning.
Error Handling
A successful send returns a numeric message ID. A failure returns one of a documented set of numeric error codes — handle these explicitly rather than treating every non-ID response as a generic failure:
Code | Meaning | Suggested handling |
101 | Invalid user | Don't retry — check credentials |
102 | Invalid sender ID | Don't retry — check DLT header registration |
103 | Invalid contact(s) | Don't retry — validate the number |
104 | Invalid route | Don't retry — fix the route parameter |
106 | Message content missing | Don't retry — check message construction |
107 | Spam blocked | Don't retry — review content/template |
108 | Low route credits | Pause and alert — top up |
110 | Promotional route outside 9 AM–9 PM | Re-queue for the allowed window |
111 | Connection error | Retry with backoff |
Treat a network timeout as ambiguous rather than a clean failure — the request may have been accepted even though you never saw the response. For anything where a duplicate send has a real cost, record the send attempt before calling the API so you can reconcile rather than blindly resend; the developer integration guide covers this pattern in depth.
Delivery Reports
The token variant's delivery-report lookup lets your backend check a message's final status after sending:
Poll with a backoff schedule (for example, a first check after 30 seconds, then 2 minutes, then 10 minutes) rather than checking immediately and repeatedly, and monitor delivery rate by route separately — a dip isolated to one route usually points to a different cause than a broad, account-wide dip.
DLT Compliance for API-Driven Sends
Every message sent through this API — regardless of which variant — has to clear TRAI's DLT framework the same way a dashboard-sent message does: a registered entity, an approved sender ID, and a pre-approved template matching your message content exactly. Since a TRAI direction reported as dated 18 November 2025, template variables must also be explicitly typed (numeric, alphanumeric, URL, and other approved categories) at registration. The SMS API overview and DLT and TRAI regulations resource cover this in full depth; the API-specific implication is that your templateid parameter (on the token and XML variants) has to reference a template that's actually been through this process — an untyped or unapproved template will be rejected regardless of how correctly your code calls the API.
Common Integration Mistakes
Assuming a JSON REST pattern before checking the actual format. The single most common source of wasted integration time with this API is assuming it works like a typical modern REST API. Read the parameter table above before writing a request builder.
Letting message text drift from the registered template. A date format change, an added word, or different punctuation in how your application renders a message creates a template mismatch invisible to a human reviewer but fatal at the carrier level.
Not handling the error-code set explicitly. Treating every non-numeric-ID response identically means a credential problem (101) gets the same response as a temporary connection issue (111) — these need different handling, as shown in the Error Handling table above.
Calling the API directly from a mobile or browser client. Both the Tally and token variants put credentials in the request — always route through your own backend.
Assuming a specific TPS or SLA figure without confirming it for your account. As covered above, ask TechTo directly rather than relying on any published number, including this page's predecessor.
Security Practices for This API
A few practices matter specifically because of how this API is designed:
Mask query strings in logs. Because this is a GET-based API, your username, password, or token appears directly in the request URL on every call. Make sure your HTTP client logging, reverse proxy access logs, and any APM or monitoring tool you use are configured to redact query parameters — otherwise credentials end up sitting in plaintext log files, which is a real exposure even if the API itself is secure.
Prefer the token variant for anything new. A leaked token can be rotated without touching your account's primary login; a leaked username/password pair on the Tally variant means changing your core account credentials, which is more disruptive to coordinate across every system that uses them.
Store credentials outside your codebase. Environment variables or a secrets manager, not a config file committed to version control — this applies regardless of which API or provider you're using, and is worth restating because it's the single most common real-world credential leak.
Validate phone numbers server-side before calling the API. Don't rely on client-side validation alone — a malformed or malicious input reaching the API wastes a call at best and triggers unexpected behavior at worst.
Rate-limit your own endpoints that trigger sends, particularly anything OTP-related that a user can request on demand. Without a limit on your side, a script could trigger repeated sends to someone else's number, both as an abuse vector and as an unnecessary cost.
Measuring Whether Your API Integration Is Actually Working
Beyond the happy path of "did the call return a message ID," a few things are worth monitoring once you're live:
Error-code distribution over time. A sudden rise in one specific code — say, 107 (spam blocked) or 108 (low credits) — points to a specific, diagnosable cause. Treating all failures as one undifferentiated "failed" bucket makes this invisible.
Delivery rate by route, not blended. A dip isolated to your Transactional route while Promotional stays normal usually means something different (and more urgent) than an account-wide dip — the two have different likely causes and different fixes.
Time from send-call to confirmed delivery, especially for OTP traffic, since this is the number that actually reflects what your users experience — carrier effects included — rather than how quickly your own code executed the request.
Credit balance trend against your sending pace, so a campaign or a sustained increase in traffic doesn't stall mid-run because nobody was watching the balance on a specific route.
Establish your own baseline over your first few weeks of real traffic, then alert on meaningful deviation from it — that's a more reliable signal than comparing against any published benchmark, including one from TechTo's own marketing content.
A Note on Migrating From Another Provider's API
If you're moving to TechTo's API from a different provider, a few things are worth knowing specifically because this API's design differs from the REST-with-SDK pattern most other providers use:
Your DLT registration itself doesn't need to be redone. Entity, sender ID, and template registrations live on the shared DLT ledger, not with any individual provider — switching providers means confirming your new provider can route through your existing sender ID and templates, not re-registering from scratch.
Expect to write a request builder rather than install a package. If your previous integration used an official SDK, budget time to replace that abstraction with the kind of direct HTTP wrapper shown in the Code Samples section above — it's a smaller amount of code than it might sound, but it's a different pattern than swapping one SDK for another.
Run both integrations in parallel before cutting over fully. Send a portion of test traffic through the new integration while your existing provider continues handling production traffic, compare delivery rates and error patterns, and only shift fully once you're confident in the new integration's behavior under real conditions — not just in a quick manual test.
Testing Before Going Live
No sandbox that simulates carrier behavior is documented for this API. A practical approach: register one test template and sender ID, and send to a small set of numbers your team controls across Jio, Airtel, Vi, and BSNL on real handsets before relying on the integration for real traffic. Test your error-handling paths deliberately — an invalid sender, a bad template ID, an invalid number — rather than only testing the success path.
Choosing Between the Three Variants: A Quick Decision Guide
If you're still unsure which of the three HTTP variants fits your situation, a few concrete scenarios:
You're building a new integration from scratch, no legacy constraints. Use the token variant. Easier credential rotation, JSON status responses, and it's the variant TechTo's own documentation and this guide treat as the default recommendation.
You need the absolute simplest possible integration, perhaps for a quick internal tool or a proof of concept. The Tally variant's username/password model is one parameter simpler to set up than managing a separate token, at the cost of a less convenient credential-rotation story later.
Your existing systems (an older ERP, specific enterprise middleware) already expect XML payloads for outbound integrations. The XML variant fits that pattern without forcing a mismatched data format into an otherwise XML-based pipeline.
You're not sure, and none of your existing systems have a strong opinion. Default to the token variant — it's the more future-proof choice for a new integration and the one this page's code samples are built around.
Whichever you choose, the underlying DLT compliance requirements, route and type parameters, and error-code set are identical — switching between variants later is a relatively small code change, not a full re-architecture, since the core request shape stays the same across all three.
Frequently Asked Questions
Is TechTo's SMS messaging API a REST API?
No. It's an HTTP GET, query-parameter API, available in Tally (username/password), token, and XML variants. The token variant returns JSON for delivery-report and credit-balance lookups, but the send call itself uses query parameters and returns a plain-text message ID.
Does TechTo provide an official SDK for Python, Node, PHP, or Java?
No official SDK is documented. The code samples above are complete, minimal wrappers you can adapt directly — a small amount of code, not a package to install.
When should I use SMPP instead of the HTTP API?
Once your volume reaches a point where per-request HTTP overhead becomes a genuine bottleneck, or if you're building a reseller platform on TechTo's infrastructure. Most businesses, including high-volume ones, are well served by the HTTP API — see TechTo's SMPP page if your use case genuinely needs it.
What's TechTo's TPS (throughput) limit?
It's tiered by account plan and route rather than a single fixed number — confirm your account's current allocation directly with TechTo, especially before a launch or campaign where throughput is a hard requirement.
Is there a sandbox for testing before going live?
No sandbox simulating carrier behavior is documented. Test with real numbers your team controls across multiple operators before relying on the integration in production.
How is delivery status tracked without a webhook? Through the token variant's delivery-report lookup, polled by your backend on a backoff schedule rather than a push notification.
What's the difference between this page and the HTTP API reference page?
This page is a documentation-and-code-samples companion — the concepts, the code, and the common mistakes. The HTTP API reference is the authoritative, most current parameter-by-parameter source; if the two ever differ, that page is correct.
I came here comparing SMS API providers — where's the comparison?
This page used to be a provider comparison; it's now the technical reference instead. For an honest, non-promotional framework for comparing providers (with no invented competitor numbers), see the provider evaluation guide.
Can I send personalized messages (different name or amount per recipient) in a single API call?
No. The number parameter's comma-separated bulk-send feature sends identical text to every recipient in that call. Personalized content requires looping through your contact list and calling the API once per recipient, with the variable substituted in before each call.
What happens if my message doesn't match my registered DLT template?
It's blocked at the carrier level rather than delivered with a warning — this applies the same way whether the mismatch comes from a dashboard send or an API call, and is one of the most common causes of unexpected failures once an integration is otherwise working correctly.
Can I schedule a message to send at a future time through this API?
No scheduling parameter is documented. Build scheduling in your own application — a queue with a delayed job, a cron-triggered check, or similar — and call the API at the time you want the message sent.
Does this API support sending to international numbers?
An International route (9) is documented among the shared parameters, but international delivery has its own regulatory and routing considerations outside India's DLT framework — confirm current scope, coverage, and pricing for international sends directly with TechTo rather than assuming parity with domestic delivery.
How do I know if I should use the Tally, token, or XML variant?
Token is the best default for most new integrations, given easier credential rotation and JSON status responses. Tally suits a very simple, low-complexity integration where token management feels like unnecessary overhead. XML suits systems that already standardize on XML payloads elsewhere in your stack. None is objectively superior — pick based on what fits your existing systems and security practices.
Comments