ارسال پیامک
این endpoint یک پیامک الگویی را برای یک یا چند گیرنده ثبت میکند. در هر درخواست حداکثر ۱۰۰ گیرنده پذیرفته میشود؛ برای تعداد بیشتر از ارسال گروهی استفاده کنید. ارسال با زمانبندی نیز با همین endpoint و پارامتر Schedule انجام میشود.
مشخصات
| مورد | مقدار |
|---|---|
| متد و مسیر | POST /api/Message/SendMessage |
| احراز هویت | کلید API یا Bearer |
| هدر اختیاری | X-Client-App، اگر کلاینت شما آن را الزامی کرده باشد |
| نوع بدنه | application/json |
پارامترهای query
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
Schedule | رشته | خیر | تاریخ و ساعت شمسی ارسال، مانند 1405/08/30 10:30. مقدار باید URL-encode شود |
بدنهی درخواست
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
code | عدد صحیح (long) | بله | کد عددی الگو؛ از الگوها دریافت میشود |
lineNumber | رشته | خیر | شمارهی خط ارسال؛ نوع خط باید با نوع الگو یکی باشد (خطوط ارسال). اگر خالی باشد، سامانه از میان خطوط همنوع الگو، خط مناسب را خودکار انتخاب میکند |
recipients | آرایه | بله | فهرست گیرندگان؛ حداکثر ۱۰۰ مورد |
recipients[].phoneNumber | رشته | بله | شمارهی موبایل ایرانی، مانند 09120000000 |
recipients[].parameters | آرایه | بسته به الگو | مقدار پارامترهای الگو برای همین گیرنده |
recipients[].parameters[].key | رشته | بله | کلید پارامتر مطابق الگو |
recipients[].parameters[].value | رشته | بله | مقدار پارامتر |
پارامترهای ثابت (مانند نام برند) و پارامترهای داینامیک (Dy_) را ارسال نکنید؛ سامانه خودش آنها را پر میکند. قواعد کامل پارامترها در الگوها و پارامترها آمده است.
نمونهی درخواست
- curl
- C#
- Python
- Node.js
- PHP
- Go
curl -X POST "https://api.payavasms.com/api/Message/SendMessage" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}'
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
var json = """
{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
""";
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.payavasms.com/api/Message/SendMessage", content);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
import requests
url = "https://api.payavasms.com/api/Message/SendMessage"
headers = {
"X-Api-Key": "YOUR_API_KEY",
}
payload = {
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.text)
const response = await fetch("https://api.payavasms.com/api/Message/SendMessage", {
method: "POST",
headers: {
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}),
});
console.log(response.status, await response.text());
<?php
$ch = curl_init("https://api.payavasms.com/api/Message/SendMessage");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-Api-Key: YOUR_API_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
JSON,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . " " . $response;
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
body := strings.NewReader(`{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}`)
req, _ := http.NewRequest("POST", "https://api.payavasms.com/api/Message/SendMessage", body)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(data))
}
نمونهی پاسخ
{
"status": 0,
"message": "عملیات با موفقیت انجام شد.",
"data": {
"result": {
"messages": [
{
"registerCode": 10000001,
"phoneNumber": "989120000000",
"parts": 1
}
]
},
"platform": "Sms"
}
}
| فیلد پاسخ | نوع | توضیح |
|---|---|---|
status | عدد | نتیجهی عملیات؛ 0 یعنی موفق. سایر مقادیر در کدهای وضعیت آمده است |
message | رشته | توضیح فارسی نتیجه |
data | object | داده های مربوط به درخواست |
خطاهای منظقی مانند کمبود موجودی یا پارامتر نامعتبر، ممکن است با کد HTTP 200 و status غیر از صفر برگردند. همیشه فیلد status بدنه را بررسی کنید و فقط به کد HTTP تکیه نکنید.
ارسال زمانبندیشده
پارامتر Schedule را با تاریخ و ساعت شمسی بفرستید. محدودیتی برای فاصلهی زمانی وجود ندارد، اما اگر زمان گذشته باشد پیام بلافاصله ارسال میشود. مقدار باید URL-encode شود؛ در نمونهی زیر 1405/08/30 10:30 به 1405%2F08%2F30%2010%3A30 تبدیل شده است.
- curl
- C#
- Python
- Node.js
- PHP
- Go
curl -X POST "https://api.payavasms.com/api/Message/SendMessage?Schedule=1405%2F08%2F30%2010%3A30" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}'
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
var json = """
{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
""";
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.payavasms.com/api/Message/SendMessage?Schedule=1405%2F08%2F30%2010%3A30", content);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
import requests
url = "https://api.payavasms.com/api/Message/SendMessage?Schedule=1405%2F08%2F30%2010%3A30"
headers = {
"X-Api-Key": "YOUR_API_KEY",
}
payload = {
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.text)
const response = await fetch("https://api.payavasms.com/api/Message/SendMessage?Schedule=1405%2F08%2F30%2010%3A30", {
method: "POST",
headers: {
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}),
});
console.log(response.status, await response.text());
<?php
$ch = curl_init("https://api.payavasms.com/api/Message/SendMessage?Schedule=1405%2F08%2F30%2010%3A30");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-Api-Key: YOUR_API_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
JSON,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . " " . $response;
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
body := strings.NewReader(`{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}`)
req, _ := http.NewRequest("POST", "https://api.payavasms.com/api/Message/SendMessage?Schedule=1405%2F08%2F30%2010%3A30", body)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(data))
}
ارسال بدون تعیین خط
اگر lineNumber را حذف کنید، سامانه خطی مناسب را انتخاب میکند:
- curl
- C#
- Python
- Node.js
- PHP
- Go
curl -X POST "https://api.payavasms.com/api/Message/SendMessage" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": 123456789012,
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}'
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
var json = """
{
"code": 123456789012,
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
""";
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.payavasms.com/api/Message/SendMessage", content);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
import requests
url = "https://api.payavasms.com/api/Message/SendMessage"
headers = {
"X-Api-Key": "YOUR_API_KEY",
}
payload = {
"code": 123456789012,
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.text)
const response = await fetch("https://api.payavasms.com/api/Message/SendMessage", {
method: "POST",
headers: {
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"code": 123456789012,
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}),
});
console.log(response.status, await response.text());
<?php
$ch = curl_init("https://api.payavasms.com/api/Message/SendMessage");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-Api-Key: YOUR_API_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"code": 123456789012,
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
JSON,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . " " . $response;
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
body := strings.NewReader(`{
"code": 123456789012,
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}`)
req, _ := http.NewRequest("POST", "https://api.payavasms.com/api/Message/SendMessage", body)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(data))
}
خطاهای رایج
status | معنا | اقدام پیشنهادی |
|---|---|---|
1 | موجودی کافی نیست | حساب را شارژ کنید |
2000 | الگو پیدا نشد | کد الگو را بررسی کنید |
2004 | الگو غیرفعال است | الگوی فعال انتخاب کنید |
3000 | خط در سامانه موجود نیست (یا برای انتخاب خودکار، خط همنوع الگو یافت نشد) | شمارهی خط را بررسی کنید |
3002 | نوع خط با نوع الگو مطابقت ندارد | خطی همنوع الگو انتخاب کنید یا lineNumber را حذف کنید |
3500 | ارسال به برخی شمارهها ممکن نیست | شمارههای نامعتبر یا غیرمجاز را حذف کنید |
4001 | حساب مسدود است | با پشتیبانی تماس بگیرید |
4500 / 4501 | کلید برنامه الزامی یا نامطابق است | هدر X-Client-App را اصلاح کنید |
5001 | کلید پارامتر نامعتبر است | کلیدها را با الگو مطابقت دهید |
5002 | طول پارامتر بیش از حد مجاز است | مقدار را کوتاه کنید |
5003 | پارامتر اجباری مقدار ندارد | مقدار را بفرستید |
فهرست کامل در کدهای وضعیت و خطاها قرار دارد. هنگام خطای پارامتر، data فهرستی از خطاها با اندیس گیرنده (index)، کلید (key)، کد (status) و دلیل (reason) است.