SMS API Là Gì? Giải Thích Dễ Hiểu Cho Developer 2026

SMS API Là Gì? Giải Thích Từng Bước Cho Developer và Doanh Nghiệp Việt Nam 2026

SMS API là giao diện lập trình (Application Programming Interface) cho phép phần mềm, website hoặc ứng dụng di động gửi và nhận tin nhắn SMS thông qua các HTTP request đơn giản - mà không cần doanh nghiệp phải ký hợp đồng trực tiếp với từng nhà mạng hay quản lý hạ tầng viễn thông. Developer gọi một endpoint, truyền số điện thoại và nội dung, phần còn lại do SMS gateway lo: định tuyến qua nhà mạng, giao tin nhắn đến thiết bị và trả về trạng thái delivery.

Hình dung đơn giản nhất: SMS API giống như dịch vụ bưu điện có cổng API. Thay vì bạn phải tự lái xe đến từng nhà mạng giao tin nhắn, bạn chỉ cần đưa thư cho bưu điện (SMS gateway) kèm địa chỉ người nhận - họ lo toàn bộ việc vận chuyển, xác nhận giao thành công và báo lại cho bạn. Mọi thứ diễn ra trong vài giây, lập trình hoàn toàn tự động.

Bài viết này giải thích SMS API từ khái niệm cơ bản đến kỹ thuật triển khai thực tế - bao gồm cấu trúc request/response, các phương thức authentication, xử lý Delivery Report và code mẫu theo ngôn ngữ lập trình phổ biến. Cả backend developer mới bắt đầu lẫn tech lead đang đánh giá provider đều sẽ tìm được thông tin cần thiết.

SMS API Hoạt Động Như Thế Nào? - Luồng Từ App Đến Điện Thoại

Khi một hệ thống gửi SMS qua API, thực chất có 5 tầng tham gia - mỗi tầng xử lý một nhiệm vụ riêng biệt. Hiểu đúng kiến trúc này giúp developer debug nhanh hơn khi tin nhắn không tới đích.

Tầng 1 - Application (ứng dụng của bạn): Tạo HTTP POST request chứa số điện thoại người nhận, nội dung tin nhắn và thông tin xác thực. Request này gửi đến endpoint của SMS gateway provider.

Tầng 2 - SMS Gateway API Server: Nhận request, xác thực API key, kiểm tra balance tài khoản, validate số điện thoại theo định dạng E.164 (ví dụ: +84901234567). Nếu hợp lệ, trả về response với message ID và status "queued".

Tầng 3 - SMS Gateway Core (SMPP): Kết nối trực tiếp đến SMSC (Short Message Service Center) của từng nhà mạng qua giao thức SMPP. Đây là lớp kết nối telco thực sự - không phải developer nào cũng cần quan tâm, nhưng quan trọng để hiểu tại sao mỗi nhà mạng cần kết nối riêng.

Tầng 4 - SMSC Nhà Mạng: Trung tâm xử lý tin nhắn của Viettel, Vinaphone, Mobifone... SMSC lưu tin vào hàng đợi, định tuyến đến trạm BTS gần nhất với thuê bao và giao tin nhắn xuống thiết bị đầu cuối.

Tầng 5 - Delivery Report (DLR): Khi thiết bị xác nhận đã nhận tin, SMSC gửi DLR ngược lên gateway, gateway gọi webhook URL của ứng dụng bạn để cập nhật trạng thái: DELIVERED, FAILED hoặc EXPIRED.

Ví dụ một request gửi SMS đơn giản qua REST API (dạng JSON):

POST /api/v2/sms/send
Host: api.smsprovider.vn
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "to": "+84901234567",
  "from": "DICHVUSMS",
  "message": "Ma OTP cua ban la: 483921. Het han sau 5 phut.",
  "callback_url": "https://yourapp.vn/webhook/dlr"
}

// Response HTTP 200
{
  "status": "queued",
  "message_id": "MSG-2026-001-abc123",
  "to": "+84901234567",
  "segments": 1,
  "cost": 0.05,
  "timestamp": "2026-05-24T08:30:00Z"
}

Trường segments quan trọng về chi phí: một SMS tiêu chuẩn chứa tối đa 160 ký tự ASCII hoặc 70 ký tự Unicode (tiếng Việt có dấu). Nếu nội dung dài hơn, tin nhắn tự động chia thành nhiều segment - mỗi segment tính phí riêng. Tin nhắn 200 ký tự tiếng Anh sẽ bị tính 2 segment.

3 Loại SMS API: REST, SOAP và SMPP - So Sánh và Khi Nào Dùng Loại Nào

Không phải mọi SMS API đều dùng chung một giao thức. Ba kiến trúc phổ biến nhất có sự khác biệt đáng kể về độ phức tạp, tốc độ và phù hợp với từng loại use case.

REST API là lựa chọn đúng cho 95% doanh nghiệp. Lý do: dễ tích hợp bằng bất kỳ ngôn ngữ nào, tài liệu rõ ràng, debug dễ với Postman, và throughput 100-1.000 tin nhắn mỗi giây đủ cho hầu hết use case từ OTP đến SMS marketing.

SMPP (Short Message Peer-to-Peer) là giao thức binary tầng 7 TCP/IP, thiết kế đặc thù cho viễn thông. Kết nối persistent (không đóng sau mỗi request) nên độ trễ thấp hơn REST đáng kể - phù hợp khi bạn cần gửi 10 triệu tin nhắn mỗi ngày như ngân hàng hoặc sàn thương mại điện tử lớn. Tuy nhiên tích hợp phức tạp hơn nhiều: cần thư viện SMPP riêng, quản lý session binding, keepalive và error code đặc thù của SMPP.

SOAP dùng XML envelope nặng nề hơn JSON nhiều lần. Hiện chỉ gặp ở hệ thống kế thừa (legacy) xây dựng trước 2010. Nếu bạn đang xây dựng hệ thống mới, REST là lựa chọn duy nhất đáng xem xét.

Cấu Trúc API Request và Response - JSON Chi Tiết Gửi SMS và Nhận DLR

Hiểu cấu trúc request/response chuẩn giúp developer tích hợp đúng từ lần đầu, không mất thời gian thử-sai. Dưới đây là hai tình huống thực tế nhất: gửi single SMS và nhận bulk response.

Với backend developer mới tích hợp: Request gửi một tin nhắn

Backend developer bắt đầu tích hợp SMS API cần nắm 4 trường bắt buộc trong body: số điện thoại người nhận theo chuẩn E.164, tên người gửi (brandname), nội dung tin nhắn và - nếu cần theo dõi trạng thái - URL callback để nhận DLR. Thiếu bất kỳ trường nào trong số này sẽ nhận lỗi 400 Bad Request.

// ===== REQUEST: Gửi SMS đơn =====
POST /api/v2/sms/send  HTTP/1.1
Host: api.dichvusms.vn
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

{
  "to": "+84901234567",        // Số E.164: +84 + số không đầu 0
  "from": "DICHVUSMS",         // Brandname đã đăng ký với Bộ TTTT
  "message": "Don hang #12345 cua ban da duoc xac nhan. Giao hang du kien 24/05/2026.",
  "callback_url": "https://yourapp.vn/webhook/sms-dlr",
  "type": "text",              // "text" hoặc "unicode" cho tiếng Việt có dấu
  "priority": "normal"         // "high" cho OTP, "normal" cho marketing
}

// ===== RESPONSE: HTTP 200 OK =====
{
  "success": true,
  "message_id": "MSG-20260524-abc123def456",
  "status": "queued",          // queued → sent → delivered/failed
  "to": "+84901234567",
  "from": "DICHVUSMS",
  "segments": 1,               // Số segment tính phí
  "cost": 0.08,                // Đơn vị: USD hoặc VND tùy provider
  "balance_remaining": 45.20,
  "timestamp": "2026-05-24T08:30:00+07:00"
}

// ===== RESPONSE: HTTP 400 - Lỗi validation =====
{
  "success": false,
  "error_code": "INVALID_PHONE",
  "error_message": "Số điện thoại không đúng định dạng E.164",
  "message_id": null
}

Trường type ảnh hưởng trực tiếp đến số lượng ký tự mỗi segment: với "text" (ASCII) giới hạn là 160 ký tự, với "unicode" (UTF-16 cho tiếng Việt có dấu) chỉ còn 70 ký tự. Một lỗi phổ biến là gửi tiếng Việt có dấu nhưng để type là "text" - kết quả: tin nhắn hiển thị ký tự lạ trên điện thoại người nhận.

Gửi bulk SMS: Request và response cho nhiều số cùng lúc

// ===== REQUEST: Gửi bulk SMS =====
POST /api/v2/sms/bulk-send  HTTP/1.1
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

{
  "from": "DICHVUSMS",
  "messages": [
    {
      "to": "+84901234567",
      "message": "Chao anh An, don hang #001 da giao thanh cong."
    },
    {
      "to": "+84907654321",
      "message": "Chao chi Binh, don hang #002 dang tren duong van chuyen."
    }
  ],
  "callback_url": "https://yourapp.vn/webhook/sms-dlr"
}

// ===== RESPONSE: HTTP 200 =====
{
  "success": true,
  "batch_id": "BATCH-20260524-xyz789",
  "total": 2,
  "queued": 2,
  "failed": 0,
  "messages": [
    { "to": "+84901234567", "message_id": "MSG-001", "status": "queued" },
    { "to": "+84907654321", "message_id": "MSG-002", "status": "queued" }
  ]
}

Authentication: API Key, OAuth 2.0 và IP Whitelist

SMS API authentication là điểm quan trọng thứ hai sau cấu trúc request - sai authentication là lý do phổ biến nhất khiến request bị từ chối ngay lần gọi đầu tiên. Ba phương thức phổ biến nhất có cơ chế và mức độ bảo mật khác nhau rõ rệt.

API Key (Bearer Token) - Phương thức phổ biến nhất

Provider cấp một chuỗi ký tự ngẫu nhiên (thường 32-64 ký tự) gọi là API key. Mỗi request truyền key này qua HTTP header Authorization: Bearer YOUR_KEY. Đơn giản, dễ implement, phù hợp cho server-to-server communication.

Quy tắc bảo mật bắt buộc: Không bao giờ nhúng API key trực tiếp trong source code. Lưu vào biến môi trường (.env file) hoặc secret manager (AWS Secrets Manager, HashiCorp Vault). API key bị lộ trong GitHub repo là sự cố bảo mật nghiêm trọng - kẻ tấn công có thể gửi hàng nghìn SMS dưới tài khoản của bạn.

HMAC Signature - Xác thực hai chiều

Một số provider yêu cầu ký request bằng HMAC-SHA256: lấy secret key, timestamp và nội dung request, tính chữ ký và đính kèm vào header. Server sẽ tính lại chữ ký từ phía mình và so khớp. Phương thức này an toàn hơn vì ngay cả khi API key bị lộ, kẻ tấn công cũng không thể giả mạo request nếu không có secret key.

// HMAC signature - pseudocode
timestamp = current_unix_timestamp()
string_to_sign = method + "\n" + endpoint + "\n" + timestamp + "\n" + body_hash
signature = HMAC_SHA256(secret_key, string_to_sign)

// Headers gửi kèm
X-Api-Key: YOUR_API_KEY
X-Timestamp: 1716537000
X-Signature: sha256=abc123...def456

OAuth 2.0 và IP Whitelist

OAuth 2.0 (client credentials flow) phù hợp cho hệ thống enterprise cần quản lý access token với thời hạn hết hạn (thường 3.600 giây). Token hết hạn, ứng dụng tự động lấy token mới - không cần can thiệp thủ công. Thêm một lớp bảo mật nữa là IP whitelist: provider chỉ chấp nhận request từ danh sách IP cụ thể bạn đăng ký trước. Kết hợp API key + IP whitelist là thiết lập bảo mật đủ mạnh cho 99% use case doanh nghiệp Việt Nam.

Xử Lý Delivery Report (DLR) và Webhook - Biết Tin Nhắn Có Đến Tay Người Nhận Không

DLR (Delivery Report) là cơ chế phản hồi trạng thái giao tin nhắn - tương đương "đã xem" trong chat app nhưng hoạt động ở tầng mạng di động. Hiểu và xử lý đúng DLR giúp hệ thống phân biệt được tin nhắn nào thực sự đến tay khách hàng, tránh gửi lại không cần thiết.

Luồng DLR từ nhà mạng về ứng dụng

Sau khi SMS giao thành công đến điện thoại người nhận, SMSC nhà mạng gửi DLR ngược lên SMS gateway. Gateway sau đó gọi HTTP POST đến webhook URL bạn đã khai báo trong request ban đầu (callback_url). Toàn bộ vòng DLR này thường mất 1-30 giây cho tin nhắn giao thành công, và có thể lên đến 24-48 giờ nếu điện thoại người nhận đang tắt.

// ===== WEBHOOK NHẬN DLR - Payload từ gateway gọi vào server bạn =====
POST https://yourapp.vn/webhook/sms-dlr  HTTP/1.1
Content-Type: application/json
X-Webhook-Secret: YOUR_WEBHOOK_SECRET   // Dùng để verify nguồn gốc

{
  "event": "message.delivered",
  "message_id": "MSG-20260524-abc123def456",
  "to": "+84901234567",
  "status": "DELIVERED",               // DELIVERED | FAILED | EXPIRED | REJECTED
  "error_code": null,                  // Có giá trị khi status là FAILED
  "delivered_at": "2026-05-24T08:30:05+07:00",
  "network": "Viettel",
  "latency_ms": 4820                   // Thời gian từ gửi đến giao tin, milliseconds
}

// ===== SERVER XỬ LÝ WEBHOOK - Pseudocode Python Flask =====
@app.route('/webhook/sms-dlr', methods=['POST'])
def handle_dlr():
    # Bước 1: Verify chữ ký webhook (bắt buộc - tránh giả mạo)
    signature = request.headers.get('X-Webhook-Signature')
    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        return Response(status=401)

    # Bước 2: Parse payload
    data = request.get_json()
    message_id = data['message_id']
    status = data['status']

    # Bước 3: Cập nhật database
    update_sms_status(message_id, status, data.get('delivered_at'))

    # Bước 4: Trigger business logic nếu cần
    if status == 'FAILED':
        schedule_retry_or_notify(message_id)

    # Bước 5: Response 200 OK - BẮT BUỘC trong 5 giây
    # Nếu không response, gateway sẽ retry webhook 3-5 lần
    return Response(status=200)


// ===== Bảng mã lỗi DLR phổ biến =====
// UNDELIVERED   - Giao không thành công (số sai, thuê bao không tồn tại)
// EXPIRED       - Hết thời gian retry (điện thoại tắt > 24h, tin nhắn bị huỷ)
// REJECTED      - Nhà mạng từ chối (spam filter, nội dung vi phạm)
// UNKNOWN       - Không có thông tin trạng thái (một số nhà mạng không hỗ trợ DLR)

Điểm quan trọng thường bị bỏ qua: webhook endpoint phải response HTTP 200 trong vòng 5 giây. Nếu timeout, gateway coi như giao DLR thất bại và retry - bạn sẽ nhận cùng một DLR nhiều lần. Xử lý idempotency (dùng message_id làm unique key trước khi update database) là thiết kế bắt buộc cho hệ thống production.

Rate Limiting và Retry Logic - Tránh Bị Throttle Khi Gửi Hàng Loạt

Rate limiting là cơ chế provider giới hạn số request mỗi đơn vị thời gian để bảo vệ hạ tầng. Vi phạm rate limit không khiến request bị từ chối vĩnh viễn - nhưng nếu xử lý sai, bạn sẽ tạo ra "bão request" làm tình trạng tệ hơn.

Khi nhận HTTP 429 (Too Many Requests), server trả về header Retry-After: 30 cho biết bao nhiêu giây cần chờ. Sai lầm phổ biến của developer mới: bắt lỗi 429 và retry ngay lập tức trong vòng lặp - điều này làm tăng áp lực lên API và kéo dài thời gian throttle.

// ===== EXPONENTIAL BACKOFF WITH JITTER - Pseudocode =====

function send_sms_with_retry(payload, max_attempts=5):
    for attempt in range(1, max_attempts + 1):
        response = call_sms_api(payload)

        if response.status == 200:
            return response.json()            // Thành công - dừng retry

        if response.status == 429:
            // Đọc Retry-After header trước
            retry_after = response.headers.get('Retry-After', 0)

            if retry_after > 0:
                wait_seconds = retry_after    // Tin vào header của server
            else:
                // Tính exponential backoff + random jitter
                // Jitter tránh nhiều thread retry cùng lúc (thundering herd)
                base_delay = 2 ** attempt         // 2, 4, 8, 16, 32 giây
                jitter = random(0, base_delay * 0.3)
                wait_seconds = min(base_delay + jitter, 60)  // Cap tại 60 giây

            sleep(wait_seconds)
            continue                          // Retry

        if response.status in [400, 401, 403]:
            raise PermanentError(response)    // Lỗi client - KHÔNG retry

        if response.status >= 500:
            // Server error - retry với backoff
            sleep(2 ** attempt)
            continue

    raise MaxRetriesExceeded("Đã thử " + max_attempts + " lần, vẫn thất bại")


// ===== RATE LIMIT THÔNG THƯỜNG CỦA SMS API =====
// Free tier:      10 msg/giây,    1.000 msg/ngày
// Standard:      100 msg/giây,   100.000 msg/ngày
// Enterprise:  1.000 msg/giây,   unlimited
// SMPP:        10.000+ msg/giây  (persistent connection)

Với chiến dịch SMS marketing gửi 100.000 tin nhắn, không nên gọi API liên tục trong một thread. Thay vào đó, dùng message queue (RabbitMQ, AWS SQS, Redis Queue) để phân phối tải đều. Mỗi worker consume từ queue với tốc độ kiểm soát được - ví dụ 50 msg/giây - và tự động retry khi gặp lỗi mà không ảnh hưởng worker khác.

Code Mẫu SMS API Theo Ngôn Ngữ - Python, PHP, Node.js

Dưới đây là pseudocode theo cấu trúc thực tế của từng ngôn ngữ phổ biến. Thay YOUR_API_KEY và ENDPOINT_URL bằng thông tin provider bạn chọn - cấu trúc request/response cơ bản đều tương tự nhau.

Python (dùng thư viện requests)

import requests
import os

API_KEY = os.environ.get('SMS_API_KEY')   // Không hardcode - lấy từ env
API_URL = "https://api.dichvusms.vn/api/v2/sms/send"

def send_sms(to_number, message, callback_url=None):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    payload = {
        "to": to_number,       // Ví dụ: "+84901234567"
        "from": "DICHVUSMS",
        "message": message,
        "type": "unicode",     // Dùng unicode cho tiếng Việt có dấu
    }
    if callback_url:
        payload["callback_url"] = callback_url

    response = requests.post(API_URL, json=payload, headers=headers, timeout=10)
    response.raise_for_status()   // Raise exception nếu status >= 400
    return response.json()

// Sử dụng:
result = send_sms("+84901234567", "Mã OTP của bạn là: 483921",
                  "https://myapp.vn/webhook/dlr")
print(result['message_id'])     // MSG-20260524-abc123

PHP (dùng cURL)

<?php
// Lưu API key trong .env hoặc config ngoài, không nhúng trực tiếp
$apiKey = getenv('SMS_API_KEY');
$apiUrl = 'https://api.dichvusms.vn/api/v2/sms/send';

function sendSms($toNumber, $message, $callbackUrl = null) {
    global $apiKey, $apiUrl;

    $payload = [
        'to'      => $toNumber,
        'from'    => 'DICHVUSMS',
        'message' => $message,
        'type'    => 'unicode',   // Bắt buộc cho tiếng Việt có dấu
    ];
    if ($callbackUrl) $payload['callback_url'] = $callbackUrl;

    $ch = curl_init($apiUrl);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode($payload),
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("SMS API error: HTTP $httpCode - $response");
    }
    return json_decode($response, true);
}

// Sử dụng:
$result = sendSms('+84901234567', 'Đơn hàng #12345 đã được xác nhận.');
echo $result['message_id'];   // MSG-20260524-abc123
?>

Node.js (dùng fetch API native)

// Node.js 18+ có fetch built-in, không cần axios/node-fetch
const API_KEY = process.env.SMS_API_KEY;
const API_URL = 'https://api.dichvusms.vn/api/v2/sms/send';

async function sendSms(toNumber, message, callbackUrl = null) {
    const payload = {
        to: toNumber,
        from: 'DICHVUSMS',
        message,
        type: 'unicode',   // Tiếng Việt có dấu
        ...(callbackUrl && { callback_url: callbackUrl })
    };

    const response = await fetch(API_URL, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(10000)   // Timeout 10 giây
    });

    if (!response.ok) {
        const error = await response.json();
        throw new Error(`SMS API error: ${error.error_message}`);
    }
    return response.json();
}

// Sử dụng với async/await:
const result = await sendSms('+84901234567', 'Xác nhận đặt hàng thành công.');
console.log(result.message_id);

Tiêu Chí Chọn SMS API Provider - Checklist Đánh Giá Cho Tech Lead

Chọn sai provider SMS API ảnh hưởng đến toàn bộ trải nghiệm người dùng cuối - OTP đến trễ, tỷ lệ delivery thấp hay downtime đúng giờ cao điểm đều trực tiếp tác động đến conversion rate và niềm tin khách hàng. Đánh giá provider cần dựa trên 6 tiêu chí có thể đo lường được.

Với tech lead đánh giá provider: 6 tiêu chí không thể bỏ qua

Tech lead lựa chọn SMS API provider cần yêu cầu SLA bằng văn bản cho 6 chỉ số sau. Provider không công bố các con số này rõ ràng là dấu hiệu cần thận trọng.

Một điểm thường bị bỏ qua khi đánh giá: test sandbox. Provider tốt cung cấp môi trường test riêng biệt hoàn toàn với production, cho phép gửi SMS test mà không tốn phí và không gửi tin thật đến số điện thoại thật. Thiếu sandbox = không thể test tích hợp an toàn trước khi deploy.

Hỏi thêm về rate limit tier theo mức giá: nhiều provider giới hạn 10 msg/giây ở gói rẻ nhất - đủ cho MVP nhưng sẽ tắc nghẽn ngay khi bạn cần gửi chiến dịch 10.000 tin nhắn. Nếu roadmap của bạn có SMS marketing volume lớn, thương lượng rate limit ngay từ đầu thay vì migrate provider sau.

Câu Hỏi Thường Gặp Về SMS API

SMS API là gì nói đơn giản nhất?

SMS API là "cầu nối" cho phép ứng dụng phần mềm gửi tin nhắn SMS tự động mà không cần con người thao tác thủ công trên điện thoại. Giống như bạn dùng API thanh toán để xử lý giao dịch, SMS API để gửi thông báo, OTP hay tin nhắn marketing - tất cả thông qua một vài dòng code.

REST API và SMPP khác nhau như thế nào?

REST API hoạt động qua HTTP (stateless - mỗi request độc lập), dễ tích hợp bằng mọi ngôn ngữ lập trình, phù hợp cho hầu hết ứng dụng web và mobile. SMPP là giao thức binary TCP/IP duy trì kết nối liên tục (persistent), throughput cao hơn 10-100 lần nhưng phức tạp hơn nhiều. Chọn REST API trừ khi bạn cần gửi trên 1 triệu tin nhắn mỗi ngày.

Tại sao tin nhắn gửi qua API nhưng không đến điện thoại người nhận?

Có 5 nguyên nhân phổ biến: (1) Số điện thoại sai định dạng - phải theo chuẩn E.164 (+84...), không được dùng 0...; (2) Brandname chưa được phê duyệt bởi Bộ TTTT; (3) Nội dung bị spam filter của nhà mạng chặn; (4) Thuê bao đang tắt máy hoặc ngoài vùng phủ sóng - tin nhắn sẽ được giao khi điện thoại bật lại (trong vòng 24 giờ); (5) Số điện thoại trong danh sách blacklist của nhà mạng.

SMS API có thể gửi tiếng Việt có dấu không?

Có. Cần đặt tham số type: "unicode" trong request. Lưu ý: tin nhắn Unicode chứa tối đa 70 ký tự mỗi segment (thay vì 160 ký tự với ASCII). Nội dung tiếng Việt có dấu dài hơn 70 ký tự sẽ tự động tách thành 2 segment trở lên, mỗi segment tính phí riêng. Tin nhắn 140 ký tự tiếng Việt có dấu = 2 segment = 2 lần phí.

Webhook DLR là gì và có bắt buộc phải dùng không?

DLR (Delivery Report) webhook là URL trên server của bạn mà SMS gateway sẽ gọi khi có cập nhật trạng thái tin nhắn (delivered, failed, expired). Không bắt buộc về mặt kỹ thuật - bạn có thể bỏ qua nếu không cần biết trạng thái. Nhưng với OTP, giao dịch tài chính hay thông báo quan trọng, DLR là thiết yếu để hệ thống biết tin nhắn có đến tay người dùng hay cần xử lý phương án dự phòng (gửi lại qua kênh khác).

Tích hợp SMS API mất bao lâu?

Tích hợp cơ bản (gửi SMS đơn giản) mất 2-4 giờ với developer có kinh nghiệm REST API. Tích hợp đầy đủ bao gồm xử lý DLR webhook, retry logic, logging và test sandbox mất 1-3 ngày làm việc. Thêm brandname đã đăng ký, kiểm thử trên 3 nhà mạng và deploy production thêm 1-2 ngày. Tổng cộng: 1 tuần cho tích hợp production-ready hoàn chỉnh.

SMS API có cần đăng ký brandname không?

Tại Việt Nam, gửi SMS brandname (tên doanh nghiệp thay vì số điện thoại) bắt buộc phải đăng ký với Bộ TTTT và nhà mạng thông qua đơn vị trung gian được cấp phép. Thời gian phê duyệt thường 3-7 ngày làm việc. Nếu chưa có brandname, bạn vẫn có thể gửi SMS qua API nhưng tin nhắn sẽ hiển thị từ một đầu số ngẫu nhiên - ảnh hưởng đáng kể đến tỷ lệ mở và lòng tin của người nhận.

Sự khác biệt giữa SMS API và SMS gateway là gì?

SMS gateway là hạ tầng trung gian kết nối giữa internet và mạng viễn thông di động - nơi tin nhắn được định tuyến và chuyển đổi giao thức. SMS API là lớp phần mềm (interface) nằm phía trên gateway, cung cấp cho developer các endpoint HTTP để tương tác với gateway đó mà không cần hiểu giao thức viễn thông phức tạp bên dưới. Nói ngắn gọn: gateway là "đường cao tốc", API là "ứng dụng đặt vé" mà bạn dùng.

HTTP status 429 khi gọi SMS API nghĩa là gì?

HTTP 429 (Too Many Requests) có nghĩa bạn đã vượt quá rate limit của API. Đọc header Retry-After trong response để biết phải chờ bao nhiêu giây trước khi thử lại. Không được retry ngay lập tức - điều đó làm tình trạng tệ hơn. Implement exponential backoff: lần retry 1 chờ 2 giây, lần 2 chờ 4 giây, lần 3 chờ 8 giây - tối đa 60 giây.

SMS API khác gì với SMS marketing?

SMS API là công nghệ kỹ thuật - giao diện lập trình để gửi tin nhắn theo cách tự động hóa. SMS marketing là chiến lược kinh doanh - dùng tin nhắn để tiếp cận, chăm sóc và chuyển đổi khách hàng. SMS API là công cụ; SMS marketing là cách dùng công cụ đó để đạt mục tiêu kinh doanh. Doanh nghiệp dùng SMS API để triển khai chiến dịch SMS marketing tự động, thay vì gửi từng tin nhắn thủ công.

Có thể tự build SMS gateway thay vì dùng API bên thứ 3 không?

Về lý thuyết có - bạn có thể ký trực tiếp với Viettel, Vinaphone, Mobifone và tự quản lý kết nối SMPP. Trên thực tế, chi phí đầu tư hạ tầng, đội kỹ thuật 24/7 và điều kiện ký kết hợp đồng với nhà mạng (thường yêu cầu volume tối thiểu hàng triệu tin/tháng) khiến phương án này chỉ khả thi với doanh nghiệp viễn thông hoặc fintech quy mô lớn. Với 99% doanh nghiệp, dùng SMS API của provider được cấp phép là lựa chọn tối ưu về chi phí và tốc độ triển khai.

Checklist Tích Hợp SMS API - Từ Development Đến Production

Dùng checklist này để đảm bảo không bỏ sót bước quan trọng nào trước khi deploy SMS API lên môi trường production.

Giai đoạn 1: Chuẩn bị và cấu hình

• Đăng ký tài khoản provider, nhận API key và lưu vào biến môi trường (không hardcode)
• Xác nhận brandname đã được phê duyệt bởi Bộ TTTT (nếu dùng SMS brandname)
• Đọc tài liệu API: xác định endpoint, format số điện thoại (E.164), error code list
• Setup sandbox/test environment riêng biệt với production credentials
• Xác định rate limit tier của gói đang dùng (msg/giây và msg/ngày)

Giai đoạn 2: Development

• Implement hàm gửi SMS với proper error handling (phân biệt 4xx và 5xx)
• Validate số điện thoại E.164 trước khi gọi API (tránh tốn phí request lỗi)
• Set timeout 10 giây cho mọi API call (tránh thread bị treo vô hạn)
• Implement exponential backoff cho HTTP 429 và 5xx errors
• Dùng type "unicode" khi nội dung có tiếng Việt có dấu
• Lưu message_id vào database ngay sau khi gửi thành công

Giai đoạn 3: Xử lý DLR Webhook

• Tạo webhook endpoint nhận POST request từ gateway
• Verify webhook signature để chống giả mạo DLR
• Response HTTP 200 trong vòng 5 giây (xử lý nặng thì queue async)
• Implement idempotency dùng message_id (tránh xử lý trùng lặp)
• Log đầy đủ: message_id, status, timestamp, error_code (nếu có)

Giai đoạn 4: Test và Go-live

• Test gửi SMS thực đến SIM của 3 nhà mạng: Viettel, Vinaphone, Mobifone
• Test DLR webhook nhận đúng status DELIVERED và FAILED
• Test edge case: số điện thoại tắt máy, số không tồn tại, nội dung vượt 70 ký tự unicode
• Test retry logic: giả lập 429 và 500 response
• Setup alert/monitoring khi delivery rate dưới 90% hoặc latency vượt 10 giây
• Chuẩn bị phương án fallback nếu provider chính down (ví dụ: chuyển sang provider phụ)

Kết Luận

SMS API là lớp kỹ thuật nền tảng cho mọi tính năng liên quan đến tin nhắn di động trong phần mềm doanh nghiệp - từ OTP xác thực đến thông báo đơn hàng và chiến dịch SMS marketing tự động. Với developer, REST SMS API có thể tích hợp cơ bản trong vài giờ; production-ready với DLR, retry logic và monitoring đầy đủ cần khoảng 1 tuần. Quan trọng nhất: chọn provider có uptime SLA ≥ 99,9%, kết nối trực tiếp nhà mạng Việt Nam và sandbox môi trường test đầy đủ.

Nếu bạn đang tìm kiếm SMS API với hướng dẫn tích hợp PHP chi tiết hoặc cần tư vấn chọn giải pháp phù hợp với quy mô và ngân sách của doanh nghiệp, đội kỹ thuật Dịch Vụ SMS sẵn sàng hỗ trợ trực tiếp qua Zalo.

Liên hệ tư vấn kỹ thuật miễn phí: Nhắn tin Zalo 0988 769 317