وب سرویس پیامکی و API پیامک
با استفاده از وب سرویس پیامکی پیام رسان، وبسایت و نرم افزار خود را به قابلیت ارسال و دریافت پیامک مجهز کنید. این سرویس کاربردی، توسعه دهندگان و صاحبان سایت را قادر می سازد تا با نصب افزونه و یا چند خط کد، پیامک های کسب و کار خو را ارسال، دریافت و مدیریت کنند.
curl -X POST 'https://api.sms-webservice.com/api/V3/SendTokenSingle' \
-H 'Content-Type: application/json; charset=utf-8' \
-d @- <<JSON
{
"ApiKey": "$PAYAM_RESAN_API_KEY",
"TemplateKey": "verifycode",
"Destination": 9121112222,
"p1": "123456"
}
JSON$payload = [
'ApiKey' => getenv('PAYAM_RESAN_API_KEY'),
'TemplateKey' => 'verifycode',
'Destination' => 9121112222,
'p1' => '123456',
];
$curl = curl_init('https://api.sms-webservice.com/api/V3/SendTokenSingle');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
CURLOPT_HTTPHEADER => ['Content-Type: application/json; charset=utf-8'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$raw = curl_exec($curl);
if ($raw === false) {
exit('خطای شبکه: ' . curl_error($curl) . "\n");
}
curl_close($curl);
$response = json_decode($raw, true);
if (empty($response['Success'])) {
exit("ناموفق. کد {$response['ErrorCode']}: {$response['Error']}\n");
}
foreach ($response['Result'] as $message) {
echo "شناسه {$message['Id']} از خط {$message['Sender']}\n";
echo "متن نهایی: {$message['FinalText']}\n";
}import json
import os
import urllib.request
payload = {
"ApiKey": os.environ["PAYAM_RESAN_API_KEY"],
"TemplateKey": "verifycode",
"Destination": 9121112222,
"p1": "123456",
}
request = urllib.request.Request(
"https://api.sms-webservice.com/api/V3/SendTokenSingle",
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
headers={"Content-Type": "application/json; charset=utf-8"},
)
with urllib.request.urlopen(request, timeout=30) as answer:
response = json.load(answer)
if not response["Success"]:
raise SystemExit(f"ناموفق. کد {response['ErrorCode']}: {response['Error']}")
for message in response["Result"]:
print(f"شناسه {message['Id']} از خط {message['Sender']}")
print(f"متن نهایی: {message['FinalText']}")use std::error::Error;
fn main() -> Result<(), Box<dyn Error>> {
let payload = ureq::json!({
"ApiKey": std::env::var("PAYAM_RESAN_API_KEY")?,
"TemplateKey": "verifycode",
"Destination": 9121112222i64,
"p1": "123456",
});
let response: ureq::serde_json::Value =
ureq::post("https://api.sms-webservice.com/api/V3/SendTokenSingle")
.send_json(payload)?
.into_json()?;
if response["Success"] != true {
eprintln!("ناموفق. کد {}: {}", response["ErrorCode"], response["Error"]);
std::process::exit(1);
}
for message in response["Result"].as_array().unwrap_or(&vec![]) {
println!("شناسه {} از خط {}", message["Id"], message["Sender"]);
println!("متن نهایی: {}", message["FinalText"].as_str().unwrap_or(""));
}
Ok(())
}import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif
let apiKey = ProcessInfo.processInfo.environment["PAYAM_RESAN_API_KEY"] ?? ""
do {
let payload: [String: Any] = [
"ApiKey": apiKey,
"TemplateKey": "verifycode",
"Destination": 9121112222,
"p1": "123456",
]
var request = URLRequest(
url: URL(string: "https://api.sms-webservice.com/api/V3/SendTokenSingle")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: payload)
request.timeoutInterval = 30
let (data, _) = try await URLSession.shared.data(for: request)
let response = try JSONSerialization.jsonObject(with: data) as? [String: Any]
guard let success = response?["Success"] as? Bool, success else {
let code = response?["ErrorCode"] as? Int ?? 0
let message = response?["Error"] as? String ?? ""
FileHandle.standardError.write(Data("ناموفق. کد \(code): \(message)\n".utf8))
exit(1)
}
for message in response?["Result"] as? [[String: Any]] ?? [] {
print("شناسه \(message["Id"] ?? 0) از خط \(message["Sender"] ?? 0)")
print("متن نهایی: \(message["FinalText"] ?? "")")
}
} catch {
FileHandle.standardError.write(Data("درخواست ناتمام ماند: \(error)\n".utf8))
exit(1)
}const payload = {
ApiKey: process.env.PAYAM_RESAN_API_KEY,
TemplateKey: 'verifycode',
Destination: 9121112222,
p1: '123456',
};
const answer = await fetch('https://api.sms-webservice.com/api/V3/SendTokenSingle', {
method: 'POST',
headers: { 'Content-Type': 'application/json; charset=utf-8' },
body: JSON.stringify(payload),
signal: AbortSignal.timeout(30_000),
});
const response = await answer.json();
if (!response.Success) {
console.error(`ناموفق. کد ${response.ErrorCode}: ${response.Error}`);
process.exit(1);
}
for (const message of response.Result) {
console.log(`شناسه ${message.Id} از خط ${message.Sender}`);
console.log(`متن نهایی: ${message.FinalText}`);
}using System.Text;
using System.Text.Json.Nodes;
var payload = new JsonObject
{
["ApiKey"] = Environment.GetEnvironmentVariable("PAYAM_RESAN_API_KEY"),
["TemplateKey"] = "verifycode",
["Destination"] = 9121112222L,
["p1"] = "123456",
};
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
var body = new StringContent(payload.ToJsonString(), Encoding.UTF8, "application/json");
var answer = await http.PostAsync("https://api.sms-webservice.com/api/V3/SendTokenSingle", body);
var response = JsonNode.Parse(await answer.Content.ReadAsStringAsync());
if (response?["Success"]?.GetValue<bool>() != true)
{
Console.Error.WriteLine($"ناموفق. کد {response?["ErrorCode"]}: {response?["Error"]}");
return 1;
}
foreach (var message in response["Result"]!.AsArray())
{
Console.WriteLine($"شناسه {message!["Id"]} از خط {message["Sender"]}");
Console.WriteLine($"متن نهایی: {message["FinalText"]}");
}
return 0;type TokenSentMessage = {
Id: number;
Sender: number;
FinalText: string;
UserTraceId: null;
};
type Envelope<T> =
| { Success: true; ErrorCode: null; Error: null; Result: T }
| { Success: false; ErrorCode: number; Error: string; Result: null };
const apiKey = process.env.PAYAM_RESAN_API_KEY;
if (!apiKey) {
console.error('متغیر PAYAM_RESAN_API_KEY تعریف نشده است.');
process.exit(1);
}
const payload = {
ApiKey: apiKey,
TemplateKey: 'verifycode',
Destination: 9121112222,
p1: '123456',
};
const answer = await fetch('https://api.sms-webservice.com/api/V3/SendTokenSingle', {
method: 'POST',
headers: { 'Content-Type': 'application/json; charset=utf-8' },
body: JSON.stringify(payload),
signal: AbortSignal.timeout(30_000),
});
const response = (await answer.json()) as Envelope<TokenSentMessage[]>;
if (!response.Success) {
console.error(`ناموفق. کد ${response.ErrorCode}: ${response.Error}`);
process.exit(1);
}
for (const message of response.Result) {
console.log(`شناسه ${message.Id} از خط ${message.Sender}`);
console.log(`متن نهایی: ${message.FinalText}`);
}OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"ApiKey\": \"123456\",\"Recipients\": [{\"Sender\": 0,\"Text\": \"test\",\"Destination\": 0,\"UserTraceId\": 0}]}");
Request request = new Request.Builder()
.url("http://api.sms-webservice.com/api/V3/SendTokenSingle?ApiKey=123456&TemplateKey=123654&Destination=9121111111&p1=125&p2=45&p3=name")
.method("GET", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
payload, _ := json.Marshal(map[string]any{
"ApiKey": os.Getenv("PAYAM_RESAN_API_KEY"),
"TemplateKey": "verifycode",
"Destination": 9121112222,
"p1": "123456",
})
client := &http.Client{Timeout: 30 * time.Second}
answer, err := client.Post(
"https://api.sms-webservice.com/api/V3/SendTokenSingle",
"application/json; charset=utf-8",
bytes.NewReader(payload),
)
if err != nil {
fmt.Fprintln(os.Stderr, "خطای شبکه:", err)
os.Exit(1)
}
defer answer.Body.Close()
decoder := json.NewDecoder(answer.Body)
decoder.UseNumber()
var response map[string]any
if err := decoder.Decode(&response); err != nil {
fmt.Fprintln(os.Stderr, "پاسخ خوانده نشد:", err)
os.Exit(1)
}
if response["Success"] != true {
fmt.Fprintf(os.Stderr, "ناموفق. کد %v: %v\n", response["ErrorCode"], response["Error"])
os.Exit(1)
}
result, _ := response["Result"].([]any)
for _, item := range result {
message, _ := item.(map[string]any)
fmt.Printf("شناسه %v از خط %v\n", message["Id"], message["Sender"])
fmt.Println("متن نهایی:", message["FinalText"])
}
}مستندات وب سرویس
هر متد با پارامترهای ورودی، نمونه پاسخ و کد آماده در چهار زبان مستند شده است: ارسال یک متن به یک یا چند شماره، ارسال چند متن به چند گیرنده، ارسال با الگو (پترن)، فهرست الگوهای پنل، و استعلام وضعیت تحویل با شناسه پیام یا شناسه پیگیری خودتان.
اگر میخواهید پیش از نوشتن یک خط کد، متدها را زنده امتحان کنید، رابط Swagger همان سرویس را با کلید شما اجرا میکند و پاسخ خام را نشان میدهد.
امکانات وب سرویس ارسال پیامک
وب سرویس پیامک این امکان را میدهد که از داخل کد سایت یا اپلیکیشن، پیامک بفرستید، دریافت کنید و وضعیت تحویل آن را پیگیری کنید، بدون اینکه نیازی به ورود دستی به پنل داشته باشید.
ارسال پیامک تکی، انبوه و الگویی
با یک درخواست ساده می توانید به یک یا چند شماره پیام بفرستید. در حالت الگویی، متن از پیش تأیید شده را با مقادیر متغیر پر می کنید تا پیام حتی به شماره های مسدود شده هم برسد.
سرویس OTP و اعتبارسنجی
کد یکبارمصرف را با اولویت بالا و تأخیر کم ارسال می کند. در صورت نرسیدن پیامک، امکان fallback به تماس صوتی هم وجود دارد تا فرآیند ورود یا تأیید شماره قطع نشود.
دریافت پیامک و گزارش وضعیت تحویل
پیامک های ورودی را می توانید از طریق webhook به صورت آنی دریافت کنید یا وضعیت پیام های ارسالی را استعلام بگیرید تا بدانید پیام واقعاً به گوشی رسیده یا نه.

ارسال پیامک از طریق پترن
در این روش ابتدا متن پیام را یکبار بهصورت الگو تعریف و تأیید میکنید. بعد در هر درخواست فقط مقادیر متغیر (مثل کد تأیید یا نام کاربر) را ارسال میکنید. پیامهای الگویی اولویت ارسال بالاتری دارند و حتی به شمارههایی که پیامک تبلیغاتی را مسدود کردهاند هم میرسند. برای OTP، اطلاعرسانی سفارش و پیامهای سیستمی این روش معمولاً بهترین انتخاب است.
فعالسازی وب سرویس پیامکی و ارسال اولین پیامک
ثبتنام و فعالسازی سرویس
پس از ساخت حساب در سامانه، از منوی «API» سپس «کلید API» کلیک کنید و «درخواست فعال سازی» رو بزنید تا سرویس وب سرویس برای شما فعال شود. بعد از فعالسازی بر روی دکمه «ساخت کلید» کلیک کنید تا کلید برای شما ساخته شود.
انتخاب خط فرستنده
برای ارسال معمولی به یک خط فعال روی حساب نیاز دارید. اگر قرار است کد تایید یا پیام خدماتی بفرستید که باید به شمارههای موجود در بلکلیست مخابرات هم برسد، باید از مسیر خط خدماتی و الگو استفاده کنید، نه خط تبلیغاتی.
ثبت الگو
در صورت نیاز. اگر متن پیام شما ثابت است و فقط متغیر دارد، از زیرمنوی «وب سرویس ارسال پترن» الگو را ثبت کنید. الگو پس از تایید، یک TemplateKey میگیرد که همان را در درخواستهایتان پاس میدهید.
اولین ارسال آزمایشی
با نمونهکد بخش قبل یک پیام به شمارهی خودتان بفرستید و پاسخ را بررسی کنید. اگر Success برابر true بود، شناسهی برگشتی را بردارید و با StatusById وضعیت تحویلش را استعلام بگیرید. با همین یک چرخه، هم اتصال و هم پیگیری را یکجا تست کردهاید.
تنظیم دریافت پیامک
اگر میخواهید پاسخ کاربران را هم در سیستم خود داشته باشید، از زیرمنوی «دریافت از طریق وب سرویس» یک آدرس به سامانه معرفی کنید. به محض دریافت هر پیامک، سامانه آن آدرس را فراخوانی میکند و اطلاعات پیام را برایتان میفرستد.

افزونهها و نرمافزارهای متصل
برای فروشگاهساز و فرمساز محبوب خودتان، افزونه آماده داریم: نصب میکنید، کلید API را میگذارید و پیامکها از همان نرمافزار میروند، بدون یک خط کد.
افزونه رسمی پیام رسان برای وردپرس
اگر سایت شما وردپرسی است، برای بیشتر کارها لازم نیست خودتان با وب سرویس کد بزنید. افزونه رایگان پیام رسان کار احراز هویت سایت را کامل میکند: ورود و ثبتنام با کد پیامکی، فرم ساز اختصاصی، تأیید شماره خریدار در ووکامرس، کپچا و پروفایل کاربری؛ همه با ظاهری که خودتان تعیین میکنید.
ورود و ثبتنام با شماره موبایل
ارسال با الگو (پترن)
فرمساز اختصاصی
تأیید شماره در ووکامرس
کپچا و ضدربات
گزارش ارسالها
سوالات متداول وب سرویس پیامک
کاربرد وب سرویس ارسال پیامک چیست؟
انواع ارسال پیامک از نرم افزار و یا وبسایت های اختصاصی و آماده . به عنوان مثال:
- نرم افزارهای حسابداری
- نرم افزارهای اموزشی
- وب سایت های اینترنتی
- فروشگاه اینترنتی
- نرم افزار مدیریت مطب
- و …
تفاوت وب سرویس پیامکی با API پیامک چیست؟
در عمل تفاوتی ندارند و هر دو به یک چیز اشاره میکنند: رابطی که نرمافزار شما را به سامانهی پیامکی وصل میکند. «وب سرویس» اصطلاح رایجتر در بازار ایران است و «API» اصطلاح فنیتر و بینالمللی. وب سرویس پیام رسان بر پایهی REST نوشته شده و با درخواست HTTP ساده کار میکند.
تفاوت ارسال با وب سرویس و ارسال با URL چیست؟
ارسال از طریق URL فقط قابلیت ارسال دارد. با وب سرویس علاوه بر ارسال، میتوانید پیامکهای دریافتی را بخوانید و وضعیت تحویل پیامهای ارسالی را استعلام بگیرید. اگر سیستم شما نیاز دارد بداند پیام رسیده یا نه، وب سرویس تنها گزینه است.
برای اتصال به وب سرویس باید چه زبانی بلد باشم؟
هیچ زبان خاصی لازم نیست. چون سرویس بر پایهی REST است، هر زبانی که بتواند درخواست HTTP بفرستد کافی است. نمونهکد آماده برای PHP، سیشارپ، جاوا و پایتون در مستندات موجود است و برای بقیهی زبانها هم همان ساختار درخواست تکرار میشود.
در یک درخواست به چند شماره میتوانم پیامک بفرستم؟
با متد Send تا ۹۹ شماره در قالب یک آرایه. اگر میخواهید به هر گیرنده متن جداگانهای بفرستید، متد SendMultiple این کار را در گروههای ۱۰۰تایی انجام میدهد و اجازه میدهد برای هر شماره، متن و شمارهی فرستندهی مجزا تعیین کنید.
چطور بفهمم پیامک به دست گیرنده رسیده است؟
هنگام ارسال، سرویس یک شناسه در فیلد Result.id برمیگرداند. این شناسه را ذخیره کنید و بعداً با متد StatusById وضعیت تحویل همان پیام را استعلام بگیرید. در یک درخواست میتوانید وضعیت چند پیام را همزمان بپرسید.
چرا با اینکه پاسخ ۲۰۰ گرفتم پیامک ارسال نشد؟
چون این سرویس خطاهای کاربردی را داخل بدنهی پاسخ برمیگرداند، نه با کد وضعیت HTTP. حتی وقتی کلید API اشتباه باشد یا سقف ارسال روزانه پر شده باشد، باز هم ۲۰۰ میگیرید و فقط فیلد Success برابر false است. همیشه Success را بررسی کنید و در صورت خطا، ErrorCode را بخوانید.
خطای ۱۳ یعنی چه؟
یعنی فرمت شمارهی گیرنده پذیرفته نشده است. شماره باید طبق مستندات همان متد نرمال شود؛ شمارهای که کاربر در فرم وارد میکند معمولاً با صفر شروع میشود یا فرمت بینالمللی دارد. پیش از فراخوانی سرویس، شماره را نرمال کنید و شمارههای نامعتبر را همانجا رد کنید.
بعد از تغییر سرور، ارسالهایم قطع شد. چرا؟
به احتمال زیاد خطای ۱۰ میگیرید: آیپی درخواستدهنده در فهرست آیپیهای معتبر نیست. پس از هر مهاجرت سرور یا تغییر آیپی، باید آیپی جدید را در پنل ثبت کنید. این خطا بیصدا اتفاق میافتد چون هیچ چیزی در کد شما عوض نشده است.
چطور بفهمم اعتبار پنلم رو به اتمام است؟
متد AccountInfo فقط ApiKey میگیرد، پیامکی نمیفرستد و مقدار اعتبار و فهرست خطوط فعال را برمیگرداند. میتوانید آن را روی یک کران دورهای بگذارید تا پیش از خالی شدن حساب خبردار شوید بهجای اینکه از تیکت کاربران بفهمید.
برای سایت وردپرسی هم باید کد بنویسم؟
خیر. افزونههای آماده برای وردپرس، ووکامرس، دیجیتس، گرویتی فرم، پرستاشاپ و اپنکارت موجود است و برای سناریوهای کد تایید، نسخهی مخصوص پترن هم ارائه شده. کافی است کلید API را در تنظیمات افزونه وارد کنید.









