Gửi SMS Bằng PHP, C# Và Python Qua API: Code Mẫu, Xử Lý Lỗi, Webhook Trạng Thái & Lưu Ý Pháp Lý Cho Doanh Nghiệp 2026

Lập trình viên nhận yêu cầu “cho hệ thống gửi SMS cho khách” thường mất thời gian nhất ở hai chỗ: không rõ gọi API thế nào cho đúng, và không biết vì sao tin gửi đi mà khách không nhận. Bài viết đi thẳng vào phần thực thi: gọi API SMS bằng PHP, C# và Python, xác thực, xử lý lỗi, nhận trạng thái qua webhook và những điều kiện pháp lý bắt buộc trước khi tin đầu tiên rời hệ thống của bạn.

Gửi SMS bằng PHP qua API là gì? Gửi SMS bằng PHP qua API là việc hệ thống của bạn gọi một địa chỉ HTTP của nhà cung cấp dịch vụ tin nhắn, truyền vào số điện thoại người nhận, nội dung tin và tên thương hiệu đã đăng ký, rồi nhận về mã kết quả. Phần đưa tin tới nhà mạng do nhà cung cấp lo. Cách làm này giống nhau ở mọi ngôn ngữ vì bản chất chỉ là một yêu cầu HTTP có kèm khóa xác thực, khác biệt duy nhất là thư viện dùng để gửi yêu cầu.

Tóm tắt nhanh

I. Chuẩn bị trước khi viết dòng code đầu tiên

• Tài khoản API và khóa xác thực, lưu trong biến môi trường chứ không viết thẳng vào code.
• Tên thương hiệu đã đăng ký để tin hiện tên công ty thay vì một dãy số lạ.
• Môi trường thử nghiệm để gửi tới số nội bộ trước khi chạy thật.
• Chuẩn hóa số điện thoại về một định dạng thống nhất trước khi gửi.
• Nhật ký gửi tin lưu lại mã tin, thời điểm và kết quả để đối chiếu về sau.

>>> Xem thêm: API SMS Là Gì? Cách Tích Hợp Gửi Tin Nhắn Tự Động Vào Hệ Thống Doanh Nghiệp 2026

II. Gửi SMS bằng PHP

Cách phổ biến nhất là dùng cURL có sẵn trong PHP, không cần cài thêm gói nào. Địa chỉ và tên tham số bạn thay theo tài liệu của nhà cung cấp.

<?php
$payload = [
    'to'      => '84901888484',
    'brand'   => 'VIHAT',
    'content' => 'Ma xac thuc cua ban la 123456',
];

$ch = curl_init('https://api.nha-cung-cap.vn/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('SMS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);

$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code !== 200) {
    error_log("Gui SMS that bai: HTTP $code - $body");
} else {
    $res = json_decode($body, true);
    error_log('Da nhan message_id: ' . ($res['message_id'] ?? 'khong ro'));
}

Ba điểm hay sai: không đặt thời gian chờ nên tiến trình treo, không ghi lại mã tin trả về nên sau này không tra được, và gửi tin trực tiếp trong luồng xử lý đơn hàng khiến khách phải chờ.

III. Gửi SMS bằng C# và Python

Với C#, dùng HttpClient và nên tái sử dụng một thực thể thay vì tạo mới mỗi lần gửi.

var payload = new { to = "84901888484", brand = "VIHAT", content = "Ma xac thuc: 123456" };
using var req = new HttpRequestMessage(HttpMethod.Post, "https://api.nha-cung-cap.vn/v1/sms/send");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
req.Content = JsonContent.Create(payload);

var res = await httpClient.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) logger.LogError("Gui SMS loi {Code}: {Body}", res.StatusCode, body);

Với Python, thư viện requests cho code ngắn nhất:

import os, requests

res = requests.post(
    "https://api.nha-cung-cap.vn/v1/sms/send",
    headers={"Authorization": f"Bearer {os.environ['SMS_API_KEY']}"},
    json={"to": "84901888484", "brand": "VIHAT", "content": "Ma xac thuc: 123456"},
    timeout=15,
)
res.raise_for_status()
print(res.json().get("message_id"))

IV. Xử lý lỗi và nhận trạng thái qua webhook

• Phân biệt hai loại lỗi: lỗi tham số thì sửa dữ liệu, lỗi tạm thời thì thử lại.
• Thử lại có giãn cách: chờ lâu dần giữa các lần, giới hạn số lần để không gửi trùng.
• Đưa vào hàng đợi: tách việc gửi ra khỏi luồng người dùng để hệ thống không chậm.
• Nhận webhook trạng thái: nhà cung cấp gọi lại địa chỉ của bạn khi tin đến hoặc thất bại.

Phản hồi lúc gửi chỉ nói rằng yêu cầu đã được nhận, không có nghĩa khách đã đọc tin. Chỉ webhook mới cho bạn con số thật về tỷ lệ tới đích.

>>> Xem thêm: Cách Gửi Tin Nhắn SMS Hàng Loạt Cho Doanh Nghiệp: 4 Cách, Quy Trình 6 Bước & Chi Phí 2026

V. Lưu ý pháp lý và chống lạm dụng

Tin nhắn quảng cáo tại Việt Nam phải gửi từ tên định danh đã đăng ký và phải cho người nhận cách từ chối nhận tin tiếp. Đây là yêu cầu của quy định về chống tin nhắn rác, cuộc gọi rác, không phải khuyến nghị tùy chọn. Tin xác thực và thông báo giao dịch thuộc nhóm khác nhưng vẫn cần đúng tên thương hiệu.

Về phía kỹ thuật, hãy giới hạn số tin mỗi số nhận trong một khoảng thời gian để tránh bị lạm dụng khi ai đó bấm gửi lại liên tục. Không đưa nội dung nhạy cảm như mật khẩu đầy đủ vào tin nhắn.

>>> Xem thêm: SMS Brandname Là Gì? Vũ Khí Để Người Dùng Khắc Sâu Tên Thương Hiệu

VI. Gửi Zalo ZNS và Voice OTP qua cùng API

1. Cấu trúc request ZNS và Voice OTP khác gì SMS?

Hệ thống eSMS cho phép gửi nhiều định dạng tin nhắn qua cùng một kết nối HTTP. Khi mở rộng luồng gửi sms php sang đa kênh, bạn có thể tích hợp Zalo ZNS hoặc Voice OTP.

SMS truyền thống chỉ cần chuỗi nội dung văn bản thuần. Ngược lại, Zalo ZNS bắt buộc truyền mã định danh OAID và mã mẫu TempID đã kiểm duyệt. Voice OTP sử dụng cùng endpoint gửi tin nhưng khai báo tham số SmsType bằng giá trị 8. Cuộc gọi thoại sẽ đọc chuỗi ký tự mật mã tự động cho khách hàng.

2. Cách truyền tham số template khi gửi tin đa kênh

Khi gửi ZNS, nội dung động được truyền qua mảng Params hoặc cấu trúc TempData. Mỗi giá trị trong mảng phải khớp đúng thứ tự các biến đã đăng ký với Zalo.

• Mỗi tham số đại diện cho một trường thông tin như họ tên, mã đơn hàng hoặc mật mã.
• Nội dung không chứa từ ngữ vi phạm chính sách của ứng dụng.
• Độ dài giá trị truyền vào không được vượt quá giới hạn mẫu đã duyệt.

3. Cơ chế tự động chuyển kênh dự phòng hoạt động thế nào?

API MultiChannelMessage của ViHAT Solutions hỗ trợ định tuyến thông minh giữa các kênh. Request gửi đi sẽ chỉ định danh sách Channels gồm Zalo đứng trước và SMS đứng sau.

Hệ thống luôn ưu tiên phát tin ZNS để tối ưu ngân sách cho doanh nghiệp. Tin ZNS xác thực thường được chuyển tới thiết bị người dùng trong vòng 15 giây. Nếu người dùng chưa có Zalo hoặc nhận tin thất bại, eSMS tự động chuyển sang SMS Brandname. Cơ chế này giúp khách hàng không bao giờ bị gián đoạn giao dịch.

VII. Kiểm thử và giám sát hệ thống gửi SMS

1. Cách dùng môi trường Sandbox để kiểm thử tích hợp

Trước khi đưa hệ thống vào vận hành thực tế, lập trình viên cần kiểm thử luồng truyền dữ liệu. Nền tảng eSMS cung cấp môi trường Sandbox thông qua tham số chuyên dụng.

Bạn chỉ cần thêm trường Sandbox với giá trị 1 vào cấu trúc body của request. Yêu cầu gửi thử sẽ kiểm tra tính hợp lệ của khóa kết nối và cú pháp. Tin nhắn thử nghiệm không phát về máy người dùng và không trừ phí tài khoản.

2. Ghi log request response và thiết lập cảnh báo lỗi ra sao?

Hệ thống gửi tin cần ghi nhật ký chi tiết cho từng giao dịch. Mỗi bản ghi phải chứa mã CodeResult, SMSID, thời gian gọi và mã đối soát RequestId.

• Mã RequestId tối đa 50 ký tự giúp ngăn chặn việc gửi trùng lặp trong 24 giờ.
• Khi tỷ lệ lỗi vượt ngưỡng 5 phần trăm, hệ thống nên phát tín hiệu cảnh báo tức thì.
• Đội ngũ kỹ thuật có thể xử lý sớm các sự cố về định dạng tin nhắn hoặc số dư.

3. Truy vấn trạng thái theo SMSID và xử lý retry thế nào?

Lập trình viên có thể chủ động kiểm tra trạng thái tin bằng hàm GetSendStatus. Bạn truyền tham số RefId tương ứng với SMSID đã nhận từ phản hồi trước đó.

Hệ thống cho phép tra cứu dữ liệu gửi tin trong 7 ngày gần nhất. Để tối ưu hiệu suất, hãy đưa tin nhắn vào hàng đợi bất đồng bộ. eSMS hỗ trợ gửi trạng thái qua webhook và tự động thử lại 5 lần nếu đường truyền gián đoạn.

VIII. Tối ưu chi phí và hiệu năng khi gửi số lượng lớn

1. Vì sao nên gửi theo lô và kiểm soát tốc độ gửi?

Khi gửi hàng loạt, gọi API cho từng số lẻ sẽ gây tiêu tốn tài nguyên máy chủ. Doanh nghiệp nên tận dụng tính năng gửi theo lô để tối ưu hiệu năng.

API eSMS cho phép truyền danh sách từ 30 đến 5000 số điện thoại trong một yêu cầu. Bạn cần điều tiết nhịp gửi ổn định để tránh tình trạng quá tải kết nối. Quy định của eSMS giới hạn một số nhận nội dung trùng lặp trong 5 phút để chống spam.

2. Phân biệt luồng tin chăm sóc khách hàng và quảng cáo

Phân luồng tin nhắn chính xác là giải pháp giảm bớt chi phí viễn thông đáng kể.

• Tin chăm sóc khách hàng dùng tham số SmsType bằng 2 được ưu tiên định tuyến nhanh suốt 24 giờ.
• Tin quảng cáo mang giá trị SmsType bằng 1 có mức cước tiết kiệm hơn nhiều cho doanh nghiệp.
• Tin quảng cáo yêu cầu kiểm duyệt nội dung trước khi hệ thống nhà mạng phát đi.

3. Cách kiểm tra số dư tài khoản tự động trước khi gửi

Một lỗi phổ biến là chiến dịch bị dừng giữa chừng do cạn kiệt ngân sách. Trước khi thực thi tác vụ sms php gửi số lượng lớn, bạn hãy gọi hàm GetBalance_json từ ViHAT Solutions.

Hàm trả về trường Balance chứa số tiền khả dụng thực tế của tài khoản. Lập trình viên thiết lập ngưỡng an toàn tối thiểu trong mã nguồn. Khi số dư dưới hạn mức, hệ thống tạm dừng và gửi cảnh báo tới quản trị viên.

IX. Câu hỏi thường gặp

Gửi SMS bằng PHP có cần cài thêm thư viện không?

Không. cURL có sẵn trong hầu hết bản PHP, còn framework thường đã kèm HTTP client riêng.

Vì sao tin báo gửi thành công mà khách không nhận?

Vì phản hồi chỉ xác nhận yêu cầu được nhận. Hãy bật webhook trạng thái để biết tin có tới đích.

Có nên tự nối trực tiếp với nhà mạng?

Thường không đáng. Qua nhà cung cấp dịch vụ sẽ nhanh hơn về pháp lý, tên thương hiệu và định tuyến nhà mạng.

Nên gửi OTP bằng SMS hay Zalo?

Ưu tiên Zalo cho chi phí thấp, dùng SMS làm kênh dự phòng khi Zalo thất bại.

X. Kết luận

Gửi SMS bằng PHP, C# hay Python đều chỉ là một yêu cầu HTTP có khóa xác thực, nên phần code không phải chỗ khó. Việc quyết định chất lượng nằm ở xung quanh: chuẩn hóa số, đưa vào hàng đợi, thử lại đúng cách, nhận webhook trạng thái và tuân thủ quy định về tin nhắn quảng cáo. Làm đủ những lớp đó, hệ thống của bạn mới đo được tỷ lệ tin tới đích thật thay vì đoán.

ViHAT Solutions cung cấp API gửi SMS Brandname, Zalo ZNS và Voice kèm webhook trạng thái, tài liệu tích hợp và cơ chế tự chuyển kênh khi gửi thất bại. Để lại thông tin tại đây để được tư vấn.

Nguồn tham khảo: PHP cURL – php.net, Nghị định 91/2020/NĐ-CP – Cổng thông tin Chính phủ.

Thông tin chi tiết xin vui lòng liên hệ:

CÔNG TY CỔ PHẦN GIẢI PHÁP DOANH NGHIỆP VIHAT

Website: vihatsolutions.com

Hotline: 0901 888 484

Email: cs@vihatgroup.com

VP trụ sở ViHAT Solutions: 140 -142, Đường số 2 – Khu nhà ở Vạn Phúc 1, Phường Hiệp Bình, Tp. Hồ Chí Minh.

VP chi nhánh Hà Nội: Tầng 6, tòa nhà An Hưng, số 85-87 Đường Hoàng Quốc Việt, Phường Nghĩa Đô, Cầu Giấy, Hà Nội.

VP Chi nhánh Cambodia: Thida Rath #154 St.33MC, Sangkat Steung Meanchey, Khan Mean Chey Phnom Penh.