שליחת SMS
http
POST https://smsprovider-web.vercel.app/api/v1/messagesשליחת אותה הודעה ליעד אחד או עד 1,000 יעדים. הקרדיטים נשמרים מיד (סגמנט = קרדיט) וההודעות נכנסות לתור. קישורים מוטמעים ([link-id] בטקסט + links) מקוצרים עם מעקב קליקים.
אימות: Authorization: Bearer bm_live_… · Scope נדרש: sms:send
חובה לשלוח Idempotency-Key (מחרוזת ייחודית, למשל UUID). חזרה על אותו מפתח בתוך 24 שעות מחזירה את אותה תשובה בלי חיוב כפול.גוף הבקשה
| שדה | סוג | חובה | הערות |
|---|---|---|---|
to | string | string[] | כן | len 5–20, items 1–1000 |
from | string | לא | len 2–20 |
body | string | כן | len 1–1005 |
schedule_at | string (date-time) | לא | |
campaign_name | string | לא | len 1–50 |
unsubscribe_link | boolean | לא | |
unsubscribe_reply | boolean | לא | |
links | map<string, string (uri)> | לא | |
skip_recent_days | integer | לא | 1–14 |
allow_international | boolean | לא | |
android_hash | string | לא | pattern ^[A-Za-z0-9+/]{11}$ |
ref | string | לא | len 1–100 |
תשובה
200 — SendResult
json
{
"batch_id": "7d1c3c5e-2b1f-4c55-9a51-1f0b8f1b2a10",
"accepted": 1,
"rejected": [],
"credits_reserved": 1,
"messages": [
{
"id": "0e9b2f0a-6c1d-4f43-8c33-6f3b3f0d9a11",
"status": "queued",
"to": "+972501234567",
"segments": 1,
"credits": 1,
"ref": "order-123",
"scheduled_at": null,
"created_at": "2026-11-02T18:00:00Z"
}
]
}שגיאות
| סטטוס | קוד |
|---|---|
| 400 | validation_error |
| 400 | idempotency_key_required |
| 409 | idempotency_conflict |
| 402 | insufficient_credits |
| 403 | sender_not_verified |
| 422 | invalid_destination |
| 429 | daily_limit_exceeded |
| 403 | org_suspended |
| 401 | unauthorized |
| 403 | insufficient_scope |
| 429 | rate_limited |
| 500 | internal_error |
דוגמאות
curl
bash
curl -X POST "https://smsprovider-web.vercel.app/api/v1/messages" \
-H "Authorization: Bearer $BATLER_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"to":["0501234567"],"from":"MyBrand","body":"שלום! ההזמנה שלך יצאה למשלוח: [track]","links":{"track":"https://example.com/orders/123"},"ref":"order-123"}'Node.js
ts
import { BatlerSMS } from "@batler/sms";
const sms = new BatlerSMS({ apiKey: process.env.BATLER_API_KEY! });
const body = {
"to": [
"0501234567"
],
"from": "MyBrand",
"body": "שלום! ההזמנה שלך יצאה למשלוח: [track]",
"links": {
"track": "https://example.com/orders/123"
},
"ref": "order-123"
};
const result = await sms.messages.send(body);PHP
php
<?php
$ch = curl_init("https://smsprovider-web.vercel.app/api/v1/messages");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BATLER_API_KEY"),
"Content-Type: application/json",
"Idempotency-Key: " . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode(["to" => ["0501234567"], "from" => "MyBrand", "body" => "שלום! ההזמנה שלך יצאה למשלוח: [track]", "links" => ["track" => "https://example.com/orders/123"], "ref" => "order-123"], JSON_UNESCAPED_UNICODE),
]);
$result = json_decode(curl_exec($ch), true);Python
python
import os, uuid, requests
resp = requests.request(
"POST", "https://smsprovider-web.vercel.app/api/v1/messages",
headers={"Authorization": f"Bearer {os.environ['BATLER_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={"to": ["0501234567"], "from": "MyBrand", "body": "שלום! ההזמנה שלך יצאה למשלוח: [track]", "links": {"track": "https://example.com/orders/123"}, "ref": "order-123"},
timeout=30,
)
resp.raise_for_status()
result = resp.json()C#
csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BATLER_API_KEY"));
var req = new HttpRequestMessage(HttpMethod.Post, "https://smsprovider-web.vercel.app/api/v1/messages");
req.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
req.Content = new StringContent("{\"to\":[\"0501234567\"],\"from\":\"MyBrand\",\"body\":\"שלום! ההזמנה שלך יצאה למשלוח: [track]\",\"links\":{\"track\":\"https://example.com/orders/123\"},\"ref\":\"order-123\"}", System.Text.Encoding.UTF8, "application/json");
var res = await http.SendAsync(req);
var result = await res.Content.ReadAsStringAsync();