API v2 (beta)
Mesajlar
Bir telefon numarasına, bir WhatsApp grubuna, kayıtlı bir kişiye veya bir Telegram kullanıcı adına hemen ya da belirlediğiniz bir saatte mesaj gönderin. Aynı mesajı tek bir istekte en fazla 1.000 alıcıya gönderin, geçmişi okuyun, bir mesajın durumunu takip edin ve beklerken iptal edin.
| İşlem | Endpoint | Kapsam |
|---|---|---|
| Mesaj gönderin | POST /api/v2/messages | messages:send |
| Birçok alıcıya gönderin | POST /api/v2/messages/batch | messages:send |
| Mesajları listeleyin | GET /api/v2/messages | messages:read |
| Bir mesajı alın | GET /api/v2/messages/{id} | messages:read |
| Bir mesajı iptal edin | DELETE /api/v2/messages/{id} | messages:send |
Anahtarlar, hatalar, Idempotency-Key ve sınırlar API v2'ye genel bakış sayfasında anlatıldığı gibi çalışır. Bir mesajın gönderildiğini veya başarısız olduğunu sürekli sorgulamadan öğrenmek için bir webhook uç noktası ekleyin.
Mesaj gönderin#
https://wbiztool.com/api/v2/messagesGövde: JSON (application/json)
Mesaj kuyruğa alınır ve yanıt, mesaj gönderilmeden önce gelir: HTTP 202 ve queued durumundaki (gelecekte bir send_at varsa scheduled durumundaki) Message. Mesajı Bir mesajı alın veya bir webhook ile takip edin.
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'];
}Yanıt (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
}
Gövde
toobjectzorunluMesajı kimin alacağı:
phone,group,contact_idveyausernamealanlarından tam olarak biri. Bkz. Alıcılar.frominteger or nullÇalışma alanında tek bir bağlı numara yoksa zorunluMesajı gönderen numaranın
iddeğeri; Numaraları listeleyin ile alınır. Gönderilmezse bağlı tek numara gönderir: bir Telegram hesabı da bağlı olsa bile bağlı tek WhatsApp numarası kullanılır; bir Telegram hesabı ise yalnızca hiçbir WhatsApp numarası bağlı değilken kullanılır. Oturumu kapanmış bir numara da kabul edilir: mesajları numara yeniden bağlanana kadar bekler.textstringMedya gönderilmiyorsa zorunluMesaj, en fazla 3.000 karakter.
mediaile birlikte açıklama (caption) olur ve gönderilmeyebilir. WhatsApp biçimlendirmesi çalışır:*bold*,_italic_,~strikethrough~. JSON'da yeni satırları\nolarak yazın.mediaobject or nullisteğe bağlıGönderilecek bir görsel veya dosya. Bkz. Medya.
send_atstring or nullisteğe bağlıHemen değil, bu saatte gönderin: ofsetiyle birlikte ISO 8601, örneğin
2026-10-20T09:30:00+05:30. Gelecekte olmalıdır. Bkz. Zamanlama ve geçerlilik süresi.expires_atstring or nullisteğe bağlıBu saatten sonra göndermeyin: mesaj bunun yerine
expiredolur. Ofsetiyle birlikte ISO 8601; gelecekte vesend_atdeğerinden sonra olmalıdır.
Başlıklar
AuthorizationheaderzorunluBearer wbz_live_…,messages:sendkapsamına sahip bir anahtar.Idempotency-Keyheaderisteğe bağlıBenzersiz herhangi bir metin; böylece yeniden deneme asla ikinci bir mesaj göndermez. Bkz. Idempotency-Key.
Gönderirken oluşan hatalar#
| HTTP | Kod | Ne zaman |
|---|---|---|
400 | validation_failed | Bir alan eksik, türü yanlış veya bilinmiyor; to alanlarından hiçbirini ya da birden fazlasını içeriyor; media hem url hem media_id içeriyor ya da ikisini de içermiyor; expires_at, send_at değerinden sonra değil |
400 | text_required | Ne text ne de media var |
400 | text_too_long | text 3.000 karakterden uzun |
400 | invalid_datetime | send_at veya expires_at ofsetli ISO 8601 değil |
402 | no_credits | Çalışma alanının planında mesajı kalmadı |
403 | number_not_allowed | Anahtar başka numaralarla sınırlı |
403 | account_disabled | Çalışma alanı sahibinin hesabı devre dışı |
422 | invalid_phone | to.phone, + ile uluslararası biçimde bir telefon numarası değil |
422 | invalid_username | to.username bir Telegram kullanıcı adı, bağlantısı veya tg: kimliği değil |
422 | username_needs_telegram | from olarak bir WhatsApp numarasıyla to.username gönderildi |
422 | contact_not_found | Bu to.contact_id ile bir kişi yok |
422 | media_not_found | Bu media.media_id ile bir dosya yok |
422 | invalid_media_url | media.url herkese açık bir http(s) bağlantısı değil |
422 | time_in_past | send_at veya expires_at zaten geçmiş |
422 | number_not_found | from bu çalışma alanının bir numarası değil |
422 | from_required | from yok ve çalışma alanında hiç bağlı numara yok ya da birden fazla var |
422 | message_rejected | Mesaj kuyruğa alınamadı; nedenini message söyler |
429 | number_daily_cap_reached | Numara son 24 saatte 1.000 mesaj gönderdi |
Reddedilen bir gönderim geride hiçbir şey bırakmaz: hiçbir mesaj kaydedilmez, bu yüzden iptal edilecek bir şey de yoktur. Her istekte oluşabilecek hatalar (anahtarlar, kapsamlar, hız sınırları, Idempotency-Key) hatalar sayfasındadır.
Birçok alıcıya gönderin#
https://wbiztool.com/api/v2/messages/batchGövde: JSON (application/json)
Aynı mesajı en fazla 1.000 alıcıya gönderir. Gövde Mesaj gönderin ile aynıdır; tek fark, to alanının bir alıcı listesi olmasıdır.
- Ya hepsi ya hiçbiri. Herhangi bir şey kuyruğa alınmadan önce her alıcı kontrol edilir ve listenin tamamı hem planda kalan mesajlara hem de gönderen numaranın önümüzdeki 24 saatteki kalan kapasitesine sığmalıdır. Bir alıcı hatalıysa hiçbir şey kuyruğa alınmaz ve
fieldo alıcıyı belirtir, örneğinto[3].phone. - Aynı alıcı iki kez yazılırsa tek bir mesaj alır.
- Yanıt,
dataile birlikte202olur:tosırasına göre her alıcı için bir Message.
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'];
}Yanıt (202), her alıcı için bir Message; ikinci ve üçüncüsü birincisine benzer, yalnızca to değerleri {"phone": "+447700900123", …} ve {"group": "Bakery staff", …} olur:
{
"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
}
]
}
Toplu gönderimde oluşan hatalar#
Tek bir mesaj gönderirken oluşanlarla aynıdır; alıcının sırası field içinde yer alır (to[0].phone). Bunlara ek olarak:
| HTTP | Kod | Ne zaman |
|---|---|---|
400 | too_many_recipients | to 1.000'den fazla öğe içeriyor |
400 | validation_failed | to boş veya bir liste değil |
402 | no_credits | Liste kalan mesajlara sığmıyor: ne kadar aştığını requested ve remaining söyler |
429 | number_daily_cap_reached | Liste numaranın önümüzdeki 24 saatteki kalan kapasitesine sığmıyor: kaç mesaj olduğunu requested ve room söyler |
Mesajları listeleyin#
https://wbiztool.com/api/v2/messagesÇalışma alanının son 90 güne ait mesajları, en yeniler önce, sayfalar hâlinde. Buna yalnızca API v2 mesajları değil, panelden, kampanyalardan, hatırlatıcılardan, entegrasyonlardan ve API v1'den gönderilen mesajlar da dahildir. Bazı numaralarla sınırlı bir anahtar yalnızca o numaraların mesajlarını görür.
Sorgu parametreleri
numberintegeristeğe bağlıYalnızca bu numara
iddeğerinden gönderilen mesajlar.statusstringisteğe bağlıYalnızca bu durumdaki mesajlar:
queued,scheduled,sent,delivered,read,failed,cancelledveyaexpired.sincestringisteğe bağlıYalnızca bu saatte veya sonrasında oluşturulan mesajlar (ofsetli ISO 8601).
untilstringisteğe bağlıYalnızca bu saatten önce oluşturulan mesajlar (ofsetli ISO 8601).
limitintegeristeğe bağlıSayfa başına mesaj sayısı, 1 ile 100 arası (varsayılan 25).
cursorstringisteğe bağlıÖnceki sayfanın
next_cursordeğeri, aynı filtrelerle.
Filtreler birlikte kullanılabilir. Sorgu metninde bir ofsetin + işaretini %2B olarak yazın (düz bir + boşluk olarak gelir ve o da + olarak okunur) veya Z kullanın.
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";
}Yanıt {"data": [Message, …], "next_cursor": "…" or null} biçimindedir.
Listelerken oluşan hatalar#
| HTTP | Kod | Ne zaman |
|---|---|---|
400 | validation_failed | number bir numara kimliği değil, status durumlardan biri değil veya limit 1 ile 100 arasında değil |
400 | invalid_datetime | since veya until ofsetli ISO 8601 değil |
400 | invalid_cursor | Cursor bozuk veya başka filtrelerle oluşturulmuş |
Bir mesajı alın#
https://wbiztool.com/api/v2/messages/{id}Tek bir mesaj ve şu anki durumu.
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'];Yanıt (200), teslim edilmiş bir mesaj:
{
"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
}
Var olmayan, başka bir çalışma alanına ait olan veya (bazı numaralarla sınırlı bir anahtar için) başka bir numaradan gönderilmiş bir mesaj 404 message_not_found döndürür.
Bir mesajı iptal edin#
https://wbiztool.com/api/v2/messages/{id}Hâlâ bekleyen (queued veya scheduled) bir mesajı, kimin oluşturduğundan bağımsız olarak iptal eder. Yanıt, artık cancelled durumundaki Message ile birlikte 200 olur. Bir webhook uç noktası message.cancelled alır.
Gönderilmiş bir mesaj geri alınamaz. Gönderen numaranın tam o anda işleme aldığı bir mesaj yine de gönderilebilir; bu önemliyse ardından durumunu kontrol edin.
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'];Mesaj iptalinde oluşan hatalar#
| HTTP | Kod | Ne zaman |
|---|---|---|
404 | message_not_found | Bu anahtar için böyle bir mesaj yok |
409 | not_cancellable | Mesaj artık beklemiyor; hatadaki status şu anki durumunu söyler, örneğin sent |
Message nesnesi#
Bu sayfadaki her işlem Message nesneleriyle yanıt verir ve webhook olayları data.message içinde bir tane taşır.
| Alan | Tür | Açıklama |
|---|---|---|
id | integer | Mesajın kimliği. Mesajı almak veya iptal etmek için kullanın. |
status | string | Mesajın şu an nerede olduğu. Bkz. Durumlar. |
from | object | Gönderen numara: id, phone (ülke koduyla birlikte rakamları, + olmadan) ve platform (whatsapp veya telegram). |
to | object | Alıcı: phone (+ ile), group veya username ve mesajın gittiği kayıtlı kişi olan contact_id. İlk kez mesaj gönderilen bir telefon numarası veya grup kişi olarak kaydedilir. (contact_id yalnızca kayıtlı olmayan bir numaraya gönderilen bir test mesajında null olur.) |
text | string | Metin veya açıklama; yoksa "". |
media | object or null | type (image veya file), url ve file_name (görsellerde null). url sınırlı bir süre çalışan bir bağlantı olabilir; saklamayın. |
send_at | string or null | Mesajın zamanlandığı saat veya "hemen" için null. |
expires_at | string or null | Bu saatten sonra mesaj gönderilmez; ya da null. |
created_at | string | Mesajın oluşturulduğu zaman. |
sent_at | string or null | Mesajın gönderildiği zaman, gönderildikten sonra (sent, delivered veya read). |
error | object or null | failed veya expired bir mesajda message nedenini söyler, örneğin File exceeds WhatsApp size limit (16MB max). Diğer durumlarda null. |
Durumlar#
| Durum | Anlamı |
|---|---|
queued | Gönderilmeyi bekliyor. |
scheduled | send_at saatini bekliyor. |
sent | Numaranızdan gönderildi (WhatsApp'ta tek tik). |
delivered | Alıcının telefonuna teslim edildi (iki tik). |
read | Alıcı tarafından okundu (mavi tikler). |
failed | Gönderilemedi; nedenini error.message söyler. |
cancelled | Gönderilmeden önce iptal edildi: Bir mesajı iptal edin ile, panelden veya numarası ya da kampanyası kaldırıldığı için. |
expired | expires_at saatinden önce gönderilemedi. |
queued ve scheduled iptal edilebilir. sent daha sonra delivered ve ardından read olabilir. failed, cancelled, expired ve read son durumlardır. Webhook'lar sent, failed, cancelled ve expired durumlarını bildirir; delivered ve read durumlarını görmek için mesajı alın.
Alıcılar#
to bu alanlardan tam olarak birini alır:
| Alan | Örnek | Kim alır |
|---|---|---|
phone | {"phone": "+919876543210"} | + ile uluslararası biçimde (E.164) bir telefon numarası. Boşluk ve tireye izin verilir. |
group | {"group": "Bakery staff"} | Gönderen numaranın üyesi olduğu bir WhatsApp grubu, tam adıyla (en fazla 200 karakter). |
contact_id | {"contact_id": 991} | Çalışma alanında kayıtlı bir kişi, kimliğiyle (örneğin önceki bir mesajın contact_id değeri). Mesaj o kişinin numarasına veya grubuna gider. |
username | {"username": "@asha_bakes"} | Bir Telegram kullanıcısı: @name, bir t.me/name bağlantısı veya tg: ve bir kullanıcı kimliği. Yalnızca bir Telegram hesabından gönderilebilir; bu yüzden from olarak bir Telegram hesabı verin (veya yalnızca bir tane bağlı olsun). |
Grup ve Telegram gönderimlerinde gönderen numaranın o grupta olması veya o kullanıcıya ulaşabilmesi gerekir; buradaki sorunlar gönderirken hata olarak değil, failed bir mesaj olarak görünür.
Medya#
media, açıklaması text olan bir görsel veya dosya gönderir. url veya media_id alanlarından tam olarak birini verin:
media.urlstringurl veya media_id'den biriDosyaya giden herkese açık bir
httpveyahttpsbağlantısı, en fazla 1.000 karakter. Özel veya yerel adreslere giden bağlantılarinvalid_media_urlile reddedilir.media.media_idintegerurl veya media_id'den biriÇalışma alanının Medya klasöründeki bir dosya; Dosya yükleyin ile alınır. Bir dosyayı bir kez yükleyin ve istediğiniz kadar gönderin.
media.typestringisteğe bağlıimageveyafile. Gönderilmezse.jpg,.jpeg,.png,.gifveya.webpile biten bir bağlantı görsel olarak, diğer her şey dosya olarak gönderilir; birmedia_idise dosyanın yüklendiği türü kullanır.media.file_namestringisteğe bağlıBir
fileiçin: alıcının gördüğü ad, örneğininvoice-1042.pdf(en fazla 100 karakter). Gönderilmezse ad bağlantıdan veya yüklenen dosyadan alınır. Dosyanın nasıl gönderileceğini uzantısı belirler, bu yüzden bir uzantı ekleyin. Görsellerde yok sayılır.
{
"to": { "phone": "+919876543210" },
"text": "Your invoice for order #1042",
"media": { "url": "https://example.com/invoices/1042.pdf", "type": "file", "file_name": "invoice-1042.pdf" }
}
Dosya API'yi çağırdığınızda değil, mesaj gönderilirken alınır; bu yüzden bozuk bir bağlantı veya çok büyük bir dosya, nedeni error.message içinde yazan failed bir mesaj olarak görünür. Boyut ve tür kuralları v1'dekilerle aynıdır: bkz. Görsel ve dosya gönderme.
Zamanlama ve geçerlilik süresi#
send_atmesajı zamanlar. Mesaj o saate kadarscheduledkalır ve gönderilene kadar iptal edilebilir. Saati ofsetiyle birlikte yazın; örneğin2026-10-20T09:30:00+05:30, Hindistan saatiyle 09:30 demektir. Tekrarlanan mesajlar için hatırlatıcıları kullanın.expires_atbir son tarihtir: mesaj o saate kadar gönderilmemişse (örneğin numaranın oturumu kapalıysa) geç gönderilmek yerineexpiredolur. Tek kullanımlık kodlar, teslimat saatleri ve kampanyalı teklifler için kullanın. Bir arka plan işi mesajı son tarihten en az 30 saniye sonra süresi dolmuş olarak işaretler; bu yüzden bir dakikadan kısa son tarihlere güvenmeyin.- İkisi de gelecekte olmalıdır ve
expires_at,send_atdeğerinden sonra olmalıdır.
İlgili sayfalar#
- Webhook'lar: sürekli sorgulamak yerine
message.sentvemessage.failedalın. - Medya:
media_idile göndermek için dosya yükleyin. - Numaralar:
fromolarak kullanılacakid. - Hatalar
