API v2 (בטא)
הודעות
שלחו הודעה עכשיו או במועד שתקבעו, למספר טלפון, לקבוצת WhatsApp, לאיש קשר שמור או לשם משתמש ב-Telegram. שלחו את אותה הודעה לעד 1,000 נמענים בבקשה אחת, קראו את ההיסטוריה, עקבו אחרי הסטטוס של הודעה ובטלו אותה כל עוד היא ממתינה.
| פעולה | Endpoint | הרשאה |
|---|---|---|
| שליחת הודעה | POST /api/v2/messages | messages:send |
| שליחה לנמענים רבים | POST /api/v2/messages/batch | messages:send |
| רשימת הודעות | GET /api/v2/messages | messages:read |
| קבלת הודעה | GET /api/v2/messages/{id} | messages:read |
| ביטול הודעה | DELETE /api/v2/messages/{id} | messages:send |
מפתחות, שגיאות, Idempotency-Key ומגבלות עובדים כמו שמתואר בסקירה של API v2. כדי לדעת מתי הודעה נשלחת או נכשלת בלי polling, הוסיפו endpoint של Webhook.
שליחת הודעה#
https://wbiztool.com/api/v2/messagesגוף הבקשה: JSON (application/json)
ההודעה נכנסת לתור והתגובה מגיעה לפני שהיא יוצאת, עם HTTP 202 וה-Message בסטטוס queued (או scheduled עם send_at עתידי). עקבו אחריה עם קבלת הודעה או עם Webhook.
curl -X POST https://wbiztool.com/api/v2/messages \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-ready" \
-d '{
"from": 101,
"to": { "phone": "+919876543210" },
"text": "Hi Asha, your order #1042 is ready."
}'import os
import requests
response = requests.post(
"https://wbiztool.com/api/v2/messages",
headers={
"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}",
"Idempotency-Key": "order-1042-ready",
},
json={
"from": 101,
"to": {"phone": "+919876543210"},
"text": "Hi Asha, your order #1042 is ready.",
},
timeout=30,
)
body = response.json()
if response.status_code == 202:
print("Queued:", body["id"], body["status"])
else:
print("Refused:", body["error"]["code"], body["error"]["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "order-1042-ready",
},
body: JSON.stringify({
from: 101,
to: { phone: "+919876543210" },
text: "Hi Asha, your order #1042 is ready.",
}),
});
const body = await response.json();
if (response.status === 202) {
console.log("Queued:", body.id, body.status);
} else {
console.error("Refused:", body.error.code, body.error.message);
}<?php
$ch = curl_init('https://wbiztool.com/api/v2/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order-1042-ready',
],
CURLOPT_POSTFIELDS => json_encode([
'from' => 101,
'to' => ['phone' => '+919876543210'],
'text' => 'Hi Asha, your order #1042 is ready.',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status === 202) {
echo 'Queued: ' . $body['id'] . ' ' . $body['status'];
} else {
echo 'Refused: ' . $body['error']['code'] . ' ' . $body['error']['message'];
}תגובה (202):
{
"id": 9817263,
"status": "queued",
"from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
"to": { "phone": "+919876543210", "contact_id": 991 },
"text": "Hi Asha, your order #1042 is ready.",
"media": null,
"send_at": null,
"expires_at": null,
"created_at": "2026-10-18T10:15:02.311Z",
"sent_at": null,
"error": null
}
גוף הבקשה
toobjectחובהמי מקבל אותה: בדיוק אחד מהשדות
phone, group, contact_idאוusername. ראו נמענים.frominteger or nullחובה, אלא אם בסביבת העבודה יש מספר מחובר אחדה-
idשל המספר ששולח אותה, מרשימת מספרים. אם לא תשלחו אותו, המספר המחובר היחיד ישלח אותה: מספר WhatsApp מחובר אחד ישמש גם אם מחובר גם חשבון Telegram, וחשבון Telegram ישמש רק כשאין מספר WhatsApp מחובר. מספר שהתנתק מתקבל: ההודעות שלו ממתינות עד שהוא מתחבר מחדש.textstringחובה, אלא אם נשלחת מדיהההודעה, עד 3,000 תווים. עם
media, זה הכיתוב, ואפשר להשמיט אותו. עיצוב של WhatsApp עובד:*bold*,_italic_,~strikethrough~. ב-JSON, כתבו שורות חדשות כ-\n.mediaobject or nullאופציונליתמונה או קובץ לשליחה. ראו מדיה.
send_atstring or nullאופציונלישליחה במועד הזה במקום עכשיו: ISO 8601 עם ההיסט שלו, למשל
2026-10-20T09:30:00+05:30. המועד חייב להיות בעתיד. ראו תזמון ותפוגה.expires_atstring or nullאופציונלילא לשלוח אחרי המועד הזה: במקום זאת ההודעה הופכת ל-
expired. ISO 8601 עם ההיסט שלו, בעתיד ואחריsend_at.
כותרות
Authorizationheaderחובה
Bearer wbz_live_…, מפתח עם ההרשאהmessages:send.Idempotency-Keyheaderאופציונלימחרוזת ייחודית כלשהי, כדי שניסיון חוזר לעולם לא ישלח הודעה שנייה. ראו Idempotency-Key.
שגיאות בשליחה#
| HTTP | קוד | מתי |
|---|---|---|
400 | validation_failed | שדה חסר, מסוג שגוי או לא מוכר; ב-to אין אף אחד מהשדות שלו או שיש כמה; ב-media יש גם url וגם media_id, או אף אחד מהם; expires_at אינו אחרי send_at |
400 | text_required | אין text ואין media |
400 | text_too_long | text ארוך מ-3,000 תווים |
400 | invalid_datetime | send_at או expires_at אינו ISO 8601 עם היסט |
402 | no_credits | לא נותרו לסביבת העבודה הודעות בתוכנית |
403 | number_not_allowed | המפתח מוגבל למספרים אחרים |
403 | account_disabled | החשבון של בעלי סביבת העבודה מושבת |
422 | invalid_phone | to.phone אינו מספר טלפון בפורמט בינלאומי עם + |
422 | invalid_username | to.username אינו שם משתמש, קישור או מזהה tg: של Telegram |
422 | username_needs_telegram | to.username עם מספר WhatsApp כ-from |
422 | contact_not_found | אין איש קשר עם ה-to.contact_id הזה |
422 | media_not_found | אין קובץ עם ה-media.media_id הזה |
422 | invalid_media_url | media.url אינו קישור http(s) ציבורי |
422 | time_in_past | המועד של send_at או של expires_at כבר עבר |
422 | number_not_found | from אינו מספר של סביבת העבודה הזו |
422 | from_required | אין from, ובסביבת העבודה אין מספר מחובר, או שיש כמה |
422 | message_rejected | לא הצלחנו להכניס את ההודעה לתור; message מסביר למה |
429 | number_daily_cap_reached | המספר שלח 1,000 הודעות ב-24 השעות האחרונות |
שליחה שנדחתה לא משאירה כלום: שום הודעה לא נשמרת, כך שאין מה לבטל. שגיאות שיכולות לקרות בכל בקשה (מפתחות, הרשאות, מגבלות קצב, Idempotency-Key) מופיעות בדף השגיאות.
שליחה לנמענים רבים#
https://wbiztool.com/api/v2/messages/batchגוף הבקשה: JSON (application/json)
שולח את אותה הודעה לעד 1,000 נמענים. הגוף זהה לזה של שליחת הודעה, חוץ מזה ש-to הוא רשימה של נמענים.
- הכול או כלום. כל נמען נבדק לפני ששום דבר נכנס לתור, וכל הרשימה חייבת להיכנס בהודעות שנותרו בתוכנית ובמקום שנותר למספר השולח ב-24 השעות הקרובות. אם נמען אחד שגוי, שום דבר לא נכנס לתור, ו-
fieldמציין אותו, למשלto[3].phone. - אותו נמען פעמיים מקבל הודעה אחת.
- התגובה היא
202עםdata: Message אחד לכל נמען, לפי הסדר שלto.
curl -X POST https://wbiztool.com/api/v2/messages/batch \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: opening-hours-2026-10-20" \
-d '{
"from": 101,
"to": [
{ "phone": "+919876543210" },
{ "phone": "+447700900123" },
{ "group": "Bakery staff" }
],
"text": "We open at 10 tomorrow."
}'import os
import requests
recipients = ["+919876543210", "+447700900123"]
response = requests.post(
"https://wbiztool.com/api/v2/messages/batch",
headers={
"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}",
"Idempotency-Key": "opening-hours-2026-10-20",
},
json={
"from": 101,
"to": [{"phone": p} for p in recipients] + [{"group": "Bakery staff"}],
"text": "We open at 10 tomorrow.",
},
timeout=60,
)
body = response.json()
if response.status_code == 202:
for message in body["data"]:
print(message["id"], message["to"], message["status"])
else:
print("Refused:", body["error"]["code"], body["error"]["field"], body["error"]["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const recipients = ["+919876543210", "+447700900123"];
const response = await fetch("https://wbiztool.com/api/v2/messages/batch", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "opening-hours-2026-10-20",
},
body: JSON.stringify({
from: 101,
to: [...recipients.map((phone) => ({ phone })), { group: "Bakery staff" }],
text: "We open at 10 tomorrow.",
}),
});
const body = await response.json();
if (response.status === 202) {
for (const message of body.data) console.log(message.id, message.to, message.status);
} else {
console.error("Refused:", body.error.code, body.error.field, body.error.message);
}<?php
$recipients = ['+919876543210', '+447700900123'];
$to = array_map(fn ($phone) => ['phone' => $phone], $recipients);
$to[] = ['group' => 'Bakery staff'];
$ch = curl_init('https://wbiztool.com/api/v2/messages/batch');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: opening-hours-2026-10-20',
],
CURLOPT_POSTFIELDS => json_encode(['from' => 101, 'to' => $to, 'text' => 'We open at 10 tomorrow.']),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status === 202) {
foreach ($body['data'] as $message) {
echo $message['id'] . ' ' . $message['status'] . "\n";
}
} else {
echo 'Refused: ' . $body['error']['code'] . ' ' . $body['error']['field'];
}תגובה (202), Message אחד לכל נמען; השני והשלישי נראים כמו הראשון, עם to שמוגדר ל-{"phone": "+447700900123", …} ול-{"group": "Bakery staff", …}:
{
"data": [
{
"id": 9817264,
"status": "queued",
"from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
"to": { "phone": "+919876543210", "contact_id": 991 },
"text": "We open at 10 tomorrow.",
"media": null,
"send_at": null,
"expires_at": null,
"created_at": "2026-10-19T16:02:40.118Z",
"sent_at": null,
"error": null
}
]
}
שגיאות בשליחה מרובה#
אותן שגיאות כמו בשליחת הודעה אחת, עם המיקום של הנמען ב-field (to[0].phone), ובנוסף:
| HTTP | קוד | מתי |
|---|---|---|
400 | too_many_recipients | ב-to יש יותר מ-1,000 רשומות |
400 | validation_failed | to ריק או שאינו רשימה |
402 | no_credits | הרשימה לא נכנסת בהודעות שנותרו: requested ו-remaining מציינים בכמה |
429 | number_daily_cap_reached | הרשימה לא נכנסת במקום שנותר למספר ב-24 השעות הקרובות: requested ו-room מציינים כמה |
רשימת הודעות#
https://wbiztool.com/api/v2/messagesההודעות של סביבת העבודה מ-90 הימים האחרונים, מהחדשה לישנה, בדפים. הרשימה כוללת הודעות שנשלחו מלוח הבקרה, מקמפיינים, מתזכורות, מאינטגרציות ומ-API v1, ולא רק את אלה של API v2. מפתח שמוגבל לחלק מהמספרים רואה רק את ההודעות שלהם.
פרמטרים של השאילתה
numberintegerאופציונלירק הודעות מה-
idשל המספר הזה.statusstringאופציונלירק הודעות עם הסטטוס הזה:
queued, scheduled, sent, delivered, read, failed, cancelledאוexpired.sincestringאופציונלירק הודעות שנוצרו במועד הזה או אחריו (ISO 8601 עם היסט).
untilstringאופציונלירק הודעות שנוצרו לפני המועד הזה (ISO 8601 עם היסט).
limitintegerאופציונליהודעות בכל דף, 1 עד 100 (ברירת המחדל 25).
cursorstringאופציונליה-
next_cursorשל הדף הקודם, עם אותם מסננים.
אפשר לשלב מסננים. במחרוזת שאילתה, כתבו את ה-+ של ההיסט כ-%2B (+ רגיל מגיע כרווח, שגם הוא נקרא כ-+), או השתמשו ב-Z.
curl -G https://wbiztool.com/api/v2/messages \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
--data-urlencode "status=failed" \
--data-urlencode "since=2026-10-01T00:00:00+05:30" \
--data-urlencode "limit=100"import os
import requests
headers = {"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"}
params = {"status": "failed", "since": "2026-10-01T00:00:00+05:30", "limit": 100}
failed = []
while True:
page = requests.get("https://wbiztool.com/api/v2/messages",
headers=headers, params=params, timeout=30).json()
failed += page["data"]
if not page["next_cursor"]:
break
params["cursor"] = page["next_cursor"] # same filters, next page
for message in failed:
print(message["id"], message["to"], message["error"]["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const params = new URLSearchParams({ status: "failed", since: "2026-10-01T00:00:00+05:30", limit: "100" });
const failed = [];
while (true) {
const response = await fetch(`https://wbiztool.com/api/v2/messages?${params}`, {
headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
const page = await response.json();
failed.push(...page.data);
if (!page.next_cursor) break;
params.set("cursor", page.next_cursor); // same filters, next page
}
for (const message of failed) console.log(message.id, message.to, message.error.message);<?php
$params = ['status' => 'failed', 'since' => '2026-10-01T00:00:00+05:30', 'limit' => 100];
$failed = [];
do {
$ch = curl_init('https://wbiztool.com/api/v2/messages?' . http_build_query($params));
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$page = json_decode(curl_exec($ch), true);
curl_close($ch);
$failed = array_merge($failed, $page['data']);
$params['cursor'] = $page['next_cursor']; // same filters, next page
} while ($page['next_cursor']);
foreach ($failed as $message) {
echo $message['id'] . ' ' . $message['error']['message'] . "\n";
}התגובה היא {"data": [Message, …], "next_cursor": "…" or null}.
שגיאות ברשימה#
| HTTP | קוד | מתי |
|---|---|---|
400 | validation_failed | number אינו מזהה של מספר, status אינו אחד מהסטטוסים, או ש-limit אינו בין 1 ל-100 |
400 | invalid_datetime | since או until אינו ISO 8601 עם היסט |
400 | invalid_cursor | ה-cursor פגום או שנוצר עם מסננים אחרים |
קבלת הודעה#
https://wbiztool.com/api/v2/messages/{id}הודעה אחת והסטטוס שלה עכשיו.
curl https://wbiztool.com/api/v2/messages/9817263 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"import os
import requests
response = requests.get(
"https://wbiztool.com/api/v2/messages/9817263",
headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
timeout=30,
)
message = response.json()
print(message["status"], message["sent_at"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/messages/9817263", {
headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
const message = await response.json();
console.log(message.status, message.sent_at);<?php
$ch = curl_init('https://wbiztool.com/api/v2/messages/9817263');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
]);
$message = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $message['status'];תגובה (200), הודעה שנמסרה:
{
"id": 9817263,
"status": "delivered",
"from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
"to": { "phone": "+919876543210", "contact_id": 991 },
"text": "Hi Asha, your order #1042 is ready.",
"media": null,
"send_at": null,
"expires_at": null,
"created_at": "2026-10-18T10:15:02.311Z",
"sent_at": "2026-10-18T10:15:09.870Z",
"error": null
}
הודעה שלא קיימת, ששייכת לסביבת עבודה אחרת, או (במפתח שמוגבל לחלק מהמספרים) שנשלחה ממספר אחר מחזירה 404 message_not_found.
ביטול הודעה#
https://wbiztool.com/api/v2/messages/{id}מבטל הודעה שעדיין ממתינה (queued או scheduled), לא משנה מי יצר אותה. התגובה היא 200 עם ה-Message, עכשיו בסטטוס cancelled. endpoint של Webhook מקבל message.cancelled.
אי אפשר להחזיר הודעה שכבר יצאה. הודעה שהמספר השולח אוסף בדיוק באותו רגע עדיין עשויה לצאת, לכן בדקו את הסטטוס שלה אחר כך אם זה חשוב.
curl -X DELETE https://wbiztool.com/api/v2/messages/9817263 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"import os
import requests
response = requests.delete(
"https://wbiztool.com/api/v2/messages/9817263",
headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
timeout=30,
)
body = response.json()
if response.status_code == 200:
print("Cancelled")
elif body["error"]["code"] == "not_cancellable":
print("Too late, it is", body["error"]["status"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/messages/9817263", {
method: "DELETE",
headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
const body = await response.json();
if (response.ok) console.log("Cancelled");
else if (body.error.code === "not_cancellable") console.log("Too late, it is", body.error.status);<?php
$ch = curl_init('https://wbiztool.com/api/v2/messages/9817263');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status === 200 ? 'Cancelled' : $body['error']['code'];שגיאות בביטול#
| HTTP | קוד | מתי |
|---|---|---|
404 | message_not_found | אין הודעה כזו עבור המפתח הזה |
409 | not_cancellable | היא כבר לא ממתינה; status בשגיאה מציין מה היא עכשיו, למשל sent |
האובייקט Message#
כל הפעולות בדף הזה מחזירות אובייקטי Message, ואירועי Webhook נושאים אחד כזה ב-data.message.
| שדה | סוג | תיאור |
|---|---|---|
id | integer | המזהה של ההודעה. השתמשו בו כדי לקבל או לבטל את ההודעה. |
status | string | איפה היא עכשיו. ראו סטטוסים. |
from | object | המספר השולח: id, phone (הספרות שלו עם קידומת המדינה, בלי +) ו-platform (whatsapp או telegram). |
to | object | הנמען: phone (עם +), group או username, ו-contact_id, איש הקשר השמור שאליו היא נשלחה. מספר טלפון או קבוצה שנשלחים אליהם בפעם הראשונה נשמרים כאיש קשר. (contact_id הוא null רק בהודעת בדיקה למספר שלא שמור.) |
text | string | הטקסט או הכיתוב; "" כשאין. |
media | object or null | type (image או file), url ו-file_name (null בתמונות). ה-url עשוי להיות קישור שעובד לזמן מוגבל; אל תשמרו אותו. |
send_at | string or null | המועד שאליו היא מתוזמנת, או null ל"עכשיו". |
expires_at | string or null | המועד שאחריו היא לא נשלחת, או null. |
created_at | string | מתי היא נוצרה. |
sent_at | string or null | מתי היא יצאה, אחרי שיצאה (sent, delivered או read). |
error | object or null | בהודעה במצב failed או expired, message מסביר למה, למשל File exceeds WhatsApp size limit (16MB max). אחרת null. |
סטטוסים#
| סטטוס | משמעות |
|---|---|
queued | ממתינה ליציאה. |
scheduled | ממתינה ל-send_at שלה. |
sent | נשלחה מהמספר שלכם (וי אחד ב-WhatsApp). |
delivered | נמסרה לטלפון של הנמען (שני וי). |
read | הנמען קרא אותה (וי כחולים). |
failed | לא הצלחנו לשלוח אותה; error.message מסביר למה. |
cancelled | בוטלה לפני שיצאה: עם ביטול הודעה, מלוח הבקרה, או כי המספר או הקמפיין שלה הוסרו. |
expired | לא נשלחה לפני ה-expires_at שלה. |
אפשר לבטל הודעות במצב queued ו-scheduled. הודעה במצב sent עדיין יכולה להפוך ל-delivered ואז ל-read. failed, cancelled, expired ו-read הם סופיים. Webhooks מדווחים על sent, failed, cancelled ו-expired; כדי לראות delivered ו-read, קבלו את ההודעה.
נמענים#
to מקבל בדיוק אחד מהשדות האלה:
| שדה | דוגמה | מי מקבל אותה |
|---|---|---|
phone | {"phone": "+919876543210"} | מספר טלפון בפורמט בינלאומי עם + (E.164). מותר להשתמש ברווחים ובמקפים. |
group | {"group": "Bakery staff"} | קבוצת WhatsApp שהמספר השולח חבר בה, לפי השם המדויק שלה (עד 200 תווים). |
contact_id | {"contact_id": 991} | איש קשר ששמור בסביבת העבודה, לפי המזהה שלו (למשל ה-contact_id של הודעה קודמת). היא נשלחת למספר או לקבוצה של איש הקשר הזה. |
username | {"username": "@asha_bakes"} | משתמש Telegram: @name, קישור t.me/name, או tg: ומזהה משתמש. רק מחשבון Telegram, לכן ציינו חשבון כזה כ-from (או שיהיה מחובר בדיוק חשבון אחד). |
שליחות לקבוצות ול-Telegram דורשות שהמספר השולח יהיה חבר באותה קבוצה או יוכל להגיע לאותו משתמש; בעיות כאלה מופיעות כהודעה במצב failed, ולא כשגיאה כשאתם שולחים.
מדיה#
media שולח תמונה או קובץ, עם text ככיתוב שלהם. ציינו בדיוק אחד מהשדות url או media_id:
media.urlstringurl או media_idקישור
httpאוhttpsציבורי לקובץ, עד 1,000 תווים. קישורים לכתובות פרטיות או מקומיות נדחים עםinvalid_media_url.media.media_idintegerurl או media_idקובץ בספריית המדיה של סביבת העבודה, מהעלאת קובץ. העלו קובץ פעם אחת ושלחו אותו כמה פעמים שתרצו.
media.typestringאופציונלי
imageאוfile. אם לא תשלחו אותו, קישור שמסתיים ב-.jpg, .jpeg, .png, .gifאו .webpנשלח כתמונה וכל השאר כקובץ; media_idמשתמש בסוג שאיתו הקובץ הועלה.media.file_namestringאופציונליל-
file: השם שהנמען רואה, למשלinvoice-1042.pdf(עד 100 תווים). אם לא תשלחו אותו, השם יילקח מהקישור או מהקובץ שהועלה. הסיומת שלו קובעת איך הקובץ נשלח, לכן הקפידו לכלול סיומת. בתמונות המערכת מתעלמת ממנו.
{
"to": { "phone": "+919876543210" },
"text": "Your invoice for order #1042",
"media": { "url": "https://example.com/invoices/1042.pdf", "type": "file", "file_name": "invoice-1042.pdf" }
}
הקובץ מורד כשההודעה נשלחת, ולא כשאתם קוראים ל-API, כך שקישור שבור או קובץ גדול מדי מופיעים כהודעה במצב failed עם הסיבה ב-error.message. כללי הגודל והסוג הם אלה של v1: ראו שליחת תמונות וקבצים.
תזמון ותפוגה#
send_atמתזמן את ההודעה. היא נשארתscheduledעד אז, ואפשר לבטל אותה עד שהיא יוצאת. כתבו את הזמן עם ההיסט שלו, כך ש-2026-10-20T09:30:00+05:30פירושו 09:30 בהודו. להודעות שחוזרות על עצמן, השתמשו בתזכורות.expires_atהוא מועד אחרון: אם ההודעה לא יצאה עד אז (למשל כי המספר התנתק), היא הופכת ל-expiredבמקום לצאת באיחור. השתמשו בו לקודים חד-פעמיים, לזמני משלוח ולמבצעים. תהליך רקע מסמן אותה כפגת תוקף לפחות 30 שניות אחרי המועד האחרון, לכן אל תסתמכו על מועדים קצרים מדקה.- שניהם חייבים להיות בעתיד, ו-
expires_atחייב להיות אחריsend_at.
