--- title: "API ile WhatsApp Mesajı Gönderme: cURL, Node, Python, PHP" description: "API ile WhatsApp mesajı nasıl gönderilir: şablon ve oturum mesajları için çalışan cURL, Node.js, Python ve PHP örnekleri, durum takibi ve hata yönetimi." canonical: "https://omnichannels.ai/tr/blog/send-whatsapp-message-api-examples/" language: "tr" updated: "2026-10-16" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "integration" primaryQuery: "whatsapp api ile mesaj gönderme" keywords: ["whatsapp api curl örneği", "node.js ile whatsapp şablon gönderme", "whatsapp api python", "whatsapp api php", "whatsapp business api mesaj gönderme", "whatsapp oturum mesajı api", "whatsapp multipart form-data api"] published: "2026-10-16" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 10 answer: "OmniChannels.ai API'siyle her WhatsApp mesajını tek bir uç noktadan gönderirsiniz: Authorization: Bearer başlığıyla multipart form verisi olarak POST https://api.broadnet.me/whatsapp/message/sendbulk. messageType alanı yükü seçer: sohbeti başlatmak veya 24 saatlik pencerenin dışında yazmak için gereken onaylı şablonlar için TEMPLATE, pencere içindeki yanıtlar için TEXT, IMAGE veya INTERACTIVE." takeaways: ["Tüm WhatsApp mesajları POST /whatsapp/message/sendbulk üzerinden gider; messageType (TEMPLATE, TEXT, IMAGE, INTERACTIVE ve diğerleri) hangi alanların zorunlu olduğunu belirler.", "İstek JSON değil multipart/form-data'dır; bu yüzden Python'da files=, PHP'de url-encode'u önlemek için dizi gövdesi gerekir.", "24 saatlik müşteri hizmetleri penceresinin dışında yalnızca onaylı bir şablon gönderilebilir; pencere içinde serbest metin, medya ve etkileşimli mesajlar gönderebilirsiniz.", "Çağrı mesajları kuyruğa alır ve hemen bir batchId döndürür; alıcı bazlı durumlar webhook'unuza ve bulk-insights uç noktasından gelir.", "API idempotency anahtarı almaz; bu yüzden her gönderimi çağrıdan önce kaydedin ve zaman aşımından sonra yeniden göndermek yerine durumu kontrol edin."] faq: - q: "WhatsApp mesajlarını JSON olarak mı yoksa form verisi olarak mı gönderirim?" a: "Form verisi olarak. WhatsApp gönderim uç noktası POST /whatsapp/message/sendbulk, her alanı bir form parçası olarak multipart/form-data kabul eder. SMS tekli gönderimleri JSON kullanır; bu yaygın bir karışıklık kaynağıdır. Python'da alanları data= yerine files= ile, PHP'de cURL'un multipart oluşturması için gövde olarak bir dizi gönderin." - q: "Şablon olmadan WhatsApp mesajı gönderebilir miyim?" a: "Yalnızca müşteri hizmetleri penceresi içinde. Bir müşteri size mesaj yazdığında 24 saatlik bir pencere açılır ve metin, medya veya etkileşimli mesajlarla yanıt verebilirsiniz. Pencerenin dışında veya bir sohbeti başlatmak için onaylı bir şablon göndermeniz gerekir. API Meta'nın kurallarını uygular; kapalı bir pencereye serbest metin gönderimi başarısız olur." - q: "Mesajın iletilip iletilmediğini nasıl anlarım?" a: "Gönderim çağrısı yalnızca mesajların kuyruğa alındığını doğrular ve bir batchId döndürür. Alıcı bazlı durumlar SUBMITTED, SENT, DELIVERED ve READ aşamalarından ilerler ya da FAILED veya REJECTED olarak sonlanır. Webhook'unuza itilirler ve ayrıca bulk-insights uç noktasından batch bazında okuyabilirsiniz." - q: "Tek istekte birçok alıcıya gönderebilir miyim?" a: "Evet. destinationNo virgül, noktalı virgül veya yeni satırla ayrılmış birden fazla numara, destinationFiles ise bir TXT, CSV veya XLSX dosyası kabul eder. Alıcı başına farklı değişkenli bir şablon için alıcı başına bir satır içeren kişiselleştirilmiş bir dosya yükleyin. Mükerrer numaraları kaldırmak için allowDuplicate değerini false yapın." - q: "Mükerrer gönderimleri önleyen bir idempotency anahtarı var mı?" a: "Hayır. API idempotency anahtarı kabul etmez. Bir istek zaman aşımına uğrarsa istemci tarafından kabul edilip edilmediğini anlayamazsınız. Her gönderimi çağırmadan önce kendi veritabanınızda kaydedin, dönen batchId'yi saklayın ve herhangi bir yeniden denemeden önce durumu ya da batch listesini kontrol edin." - q: "Göndermeden önce opt-in gerekir mi?" a: "Evet. Meta'nın politikası, her alıcının işletmenizden mesaj almayı kabul etmiş olmasını gerektirir ve şablonlar kullanımdan önce onaylanmalıdır. API sizin yerinize onayı kontrol etmez. Opt-in'i kaynağında toplayın, kanıtı saklayın ve opt-out yapanları bastırın." sources: - title: "WhatsApp Business Mesajlaşma Politikası" url: "https://business.whatsapp.com/policy" - title: "WhatsApp Business Platform'da fiyatlandırma — Meta for Developers" url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing" - title: "RFC 7578: Formlardan Değer Döndürme: multipart/form-data" url: "https://www.rfc-editor.org/rfc/rfc7578" --- # API ile WhatsApp Mesajı Gönderme: cURL, Node, Python, PHP Canonical: https://omnichannels.ai/tr/blog/send-whatsapp-message-api-examples/ Language: tr Publisher: OmniChannels.ai by BroadNet Technologies Bu rehber, bir uygulamaya WhatsApp gönderimi entegre eden geliştiriciler için hazırlandı. cURL, Node.js, Python ve PHP'de çalışan istekleri gösterir, şablon ile oturum mesajları arasındaki farkı açıklar ve takip ile hataları kapsar. Her uç nokta ve alan [WhatsApp API referansımızdan](/developers/whatsapp/) ve OpenAPI belirtimimizden gelir. ## API üzerinden WhatsApp mesajı nasıl gönderirim? Form alanlarıyla `https://api.broadnet.me/whatsapp/message/sendbulk` adresine kimliği doğrulanmış tek bir `POST` yaparsınız. `messageType` alanı mesaj türünü seçer ve yanıt mesajların kuyruğa alındığını doğrular. | Öğe | Değer | |---|---| | Temel URL | `https://api.broadnet.me` (`/v1` öneki yok) | | Uç nokta | `POST /whatsapp/message/sendbulk` | | Kimlik doğrulama | `Authorization: Bearer $BROADNET_TOKEN` | | İçerik türü | `multipart/form-data` (HTTP istemciniz tarafından otomatik ayarlanır) | | Yanıt | `batchId` içeren JSON batch özeti | Test kimlik bilgileri kısa bir erişim talebinden sonra verilir ve test gönderimleri doğrulanmış kendi numaralarınıza gider. [Hızlı başlangıç](/developers/quickstart/) ve kimlik doğrulama sayfalarına bakın. Token'ı yalnızca sunucunuzda tutun. ## Şablon mu oturum mesajı mı: hangisini göndermeliyim? Sohbeti başlatmak veya pencerenin dışında yazmak için şablon, müşteri son 24 saat içinde size yazdıysa oturum mesajı gönderin. Bu kuralı biz değil Meta koyar. | | Şablon mesajı | Oturum mesajı | |---|---|---| | `messageType` | `TEMPLATE` | `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`, `INTERACTIVE` ve diğerleri | | Ne zaman izinli | Şablon onaylandıktan sonra her zaman | Yalnızca müşteri hizmetleri penceresi açıkken | | Onay gerekir mi | Evet, Meta tarafından | Hayır | | Tipik kullanım | Sipariş güncellemeleri, OTP, hatırlatmalar, kampanyalar | Destek yanıtları, sorulara cevaplar | Meta teslim edilen mesaj başına kategoriye göre ücret alır ve hizmet mesajları ile bilgilendirme (Utility) şablonlarına ilişkin kuralları 1 Ekim 2026'da değişti. [Pencere rehberimiz](/tr/blog/whatsapp-24-hour-customer-service-window/) mekaniği, [fiyat sayfamız](/tr/whatsapp-pricing/) ve [hesaplayıcımız](/tr/tools/whatsapp-pricing-calculator/) maliyeti kapsar. ## Onaylı bir şablonu nasıl gönderirim? `messageType=TEMPLATE` yapın, şablonun adını ve dil kodunu belirtin ve değişken değerlerini geçirin. Yeni bir batch başlatmak için `batchId=0` kullanın. ```bash curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -F batchId=0 \ -F campaignName=order-updates \ -F destinationNo=971500000000 \ -F messageType=TEMPLATE \ -F templateName=order_update \ -F templateLanguage=en_US \ -F bodyTemplateVariables=INV-400 ``` ```js // Node.js 18+ (yerleşik fetch ve FormData) const form = new FormData(); form.append("batchId", "0"); form.append("campaignName", "order-updates"); form.append("destinationNo", "971500000000"); form.append("messageType", "TEMPLATE"); form.append("templateName", "order_update"); form.append("templateLanguage", "en_US"); form.append("bodyTemplateVariables", "INV-400"); const res = await fetch("https://api.broadnet.me/whatsapp/message/sendbulk", { method: "POST", headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` }, // fetch multipart sınırını kendisi ayarlar body: form, }); console.log(await res.json()); ``` ```python import os import requests fields = { "batchId": "0", "campaignName": "order-updates", "destinationNo": "971500000000", "messageType": "TEMPLATE", "templateName": "order_update", "templateLanguage": "en_US", "bodyTemplateVariables": "INV-400", } # Her alanı url-encode (data=) yerine multipart parçası (files=) olarak gönderin. r = requests.post( "https://api.broadnet.me/whatsapp/message/sendbulk", headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"}, files={k: (None, v) for k, v in fields.items()}, timeout=30, ) print(r.json()) ``` ```php true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BROADNET_TOKEN")], // Dize değil dizi, cURL'un multipart/form-data göndermesini sağlar. CURLOPT_POSTFIELDS => [ "batchId" => "0", "campaignName" => "order-updates", "destinationNo" => "971500000000", "messageType" => "TEMPLATE", "templateName" => "order_update", "templateLanguage" => "en_US", "bodyTemplateVariables" => "INV-400", ], ]); echo curl_exec($ch); curl_close($ch); ``` Hedef, ülke kodu artı numara, yalnızca rakamlardır. Çağrı hemen bir batch özetiyle döner: ```json { "totalFiles": 1, "totalSuccess": 1, "totalFailed": 0, "totalDuplicates": 0, "batchId": "2609091405000000001", "fileResults": [ { "fileName": "direct", "totalRecords": 1, "successCount": 1, "failedRecipients": [], "duplicateRecipients": [] } ], "message": "Messages queued for delivery" } ``` `batchId` değerini kendi kaydınızın yanında saklayın. "Kuyruğa alındı", "iletildi" değildir. ## Hangi istek alanları en önemlidir? Hangi alanların zorunlu olduğu `messageType` değerine bağlıdır. Yaygın olanlar şunlardır. | Alan | Zorunlu | Açıklama | |---|---|---| | `messageType` | Evet | `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`, `STICKER`, `LOCATION`, `CONTACTS`, `TEMPLATE`, `INTERACTIVE`, `REACTION` veya `FLOW` | | `destinationNo` veya `destinationFiles` | İkisinden biri | Virgül, noktalı virgül veya yeni satırla ayrılmış numaralar; ya da bir TXT, CSV veya XLSX dosyası | | `batchId` | Hayır | `0` yeni bir batch başlatır | | `campaignName` | Hayır | Raporlama için kendi etiketiniz | | `allowDuplicate` | Hayır | `false` mükerrer alıcıları kaldırır | | `templateName`, `templateLanguage` | `TEMPLATE` için | Onaylı şablon adı ve `en_US` veya `ar` gibi dil kodu | | `bodyTemplateVariables` | Şablona göre | Gövde değişken değeri; adlandırılmış parametreler JSON olarak geçirilir | | `buttonsTemplateVariable` | Şablona göre | Dinamik düğme değeri: URL soneki, kupon kodu veya OTP kodu | | `content` | `TEXT` için | En çok 4.096 karakterlik metin gövdesi veya medya için bir başlık | | `mediaUrl` | Türe göre | Medyanın herkese açık HTTPS URL'si | | `interactivePayload` | `INTERACTIVE` için | Meta'nın etkileşimli nesnesi, JSON dizesi olarak | Zamanlama `scheduled`, `scheduleTime` ve `gmt` kullanır; `delay` iletimi yavaşlatır. Tam liste [WhatsApp API referansında](/developers/whatsapp/). ## Düğmeli bir şablonu veya OTP'yi nasıl gönderirim? Düğme değerini `buttonsTemplateVariable` içine ekleyin. Kod kopyalama düğmeli bir kimlik doğrulama şablonu için kodu hem gövde hem düğme alanlarında geçirin. ```bash curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -F batchId=0 \ -F destinationNo=971500000000 \ -F messageType=TEMPLATE \ -F templateName=login_code \ -F templateLanguage=en_US \ -F bodyTemplateVariables=482913 \ -F buttonsTemplateVariable=482913 ``` Burada `login_code`, kendi onaylı kimlik doğrulama şablonunuz için bir yer tutucudur. Birden fazla düğme için `buttonsTemplateVariable` bir JSON dizisi alır. Kodu sunucunuzda üretin, geçerlilik süresiyle hash'lenmiş saklayın ve asla günlüğe yazmayın. [OTP rehberimiz](/tr/blog/otp-authentication-messages-guide/) tek dokunuşlu, sıfır dokunuşlu ve kod kopyalama iletimini kapsar. ## Müşteri hizmetleri penceresi içinde nasıl yanıt veririm? Bir oturum mesajı türü kullanın. Düz metin yanıtı için `messageType=TEXT` ve `content` gerekir. ```bash curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -F batchId=0 \ -F destinationNo=971500000000 \ -F messageType=TEXT \ -F campaignName=support \ -F "content=Your order has shipped. Reply here if you need anything." ``` Yanıt düğmeleri için `messageType=INTERACTIVE` ve Meta'nın etkileşimli mesaj biçimini izleyen bir `interactivePayload` gönderin. ```bash curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -F batchId=0 \ -F destinationNo=971500000000 \ -F messageType=INTERACTIVE \ -F campaignName=support \ -F 'interactivePayload={"type":"button","body":{"text":"Confirm your delivery slot?"},"action":{"buttons":[{"type":"reply","reply":{"id":"slot_ok","title":"Confirm"}},{"type":"reply","reply":{"id":"slot_change","title":"Change"}}]}}' ``` Gelen bir mesajı okundu olarak işaretlemek ve isteğe bağlı olarak yazıyor göstergesi göstermek için JSON ile `POST /whatsapp/message/read` çağırın: ```bash curl -X POST https://api.broadnet.me/whatsapp/message/read \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "messageId": "wamid.HBgMOTcxNTAwMDAwMDAwFQIAEhgg", "typing": true }' ``` Tasarım rehberliği için etkileşimli mesajlar rehberimize bakın. ## İletimi nasıl takip ederim? Durumlar hesabınızda yapılandırılan webhook'a itilir ve batch bazında da okunabilir. Her alıcı `SUBMITTED`, `SENT`, `DELIVERED` ve `READ` aşamalarından ilerler ya da bir nedenle `FAILED` veya `REJECTED` olarak sonlanır. ```bash curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&status=FAILED&page=0&size=50" \ -H "Authorization: Bearer $BROADNET_TOKEN" ``` `batch_Id` zorunludur; `status`, `destination`, `search`, `page` ve `size` isteğe bağlıdır ve `page` sıfırdan başlar. Kaçırılan olaylar için polling'i yedek olarak kullanın ve alıcınızı [webhook rehberimizde](/tr/blog/whatsapp-webhooks-guide/) anlatıldığı gibi oluşturun. Batch'ler ayrıca referanstaki batch uç noktalarıyla duraklatılabilir, sürdürülebilir ve iptal edilebilir. ## Hangi hataları yönetmeliyim? Önce HTTP durumunu, sonra hata gövdesini okuyun. API hataları beş alanlı bir JSON gövdesiyle bildirir ve WhatsApp'a özgü başarısızlıklar Meta'dan gelebilir. | Durum | Anlamı | Eylem | |---|---|---| | `400` | Türe özgü eksik alan veya geçersiz hedef gibi doğrulama hatası | İsteği düzeltin; değiştirmeden yeniden denemeyin | | `401` / `403` | Eksik veya geçersiz token ya da izin verilmeyen işlem | Token'ı düzeltin veya işlemi etkinleştirmemizi isteyin | | `404` | Şablon veya gönderici bulunamadı | Şablon adını ve dilini kontrol edin | | `413` | Yüklenen dosya çok büyük | Dosyayı küçültün | | `429` | Hız sınırı | `Retry-After` süresini bekleyin | | `502` | Meta çağrıyı reddetti; `message` Meta'nın hata kodunu ve metnini taşır | Okuyun; yalnızca geçiciyse yeniden deneyin | | `500`, `503`, `504` | Sunucu veya yukarı akış sorunu | Üstel backoff ve jitter ile yeniden deneyin | Hata kodları rehberimiz yaygın Meta kodlarını açıklar. İdempotency anahtarı olmadığı için [Hatalar ve limitler](/developers/errors-and-limits/) sayfasındaki mükerrer koruma adımlarını izleyin: önce bekleyen bir kayıt yazın, dönen `batchId`'yi saklayın ve zaman aşımından sonra yeniden göndermeden önce durumu kontrol edin. ## Örnek senaryo: Bir sipariş bildirim servisi BAE'li bir perakendeci olan "Souq Rafiq" (kurgusal), bir sipariş kargoya verildiğinde `order_update` şablonunu gönderir. 1. Sipariş servisi, `order-8842-shipped` anahtarlı ve `pending` durumlu bir satır yazar. 2. Şablon ve sipariş numarasını `bodyTemplateVariables` olarak vererek `sendbulk` çağırır. 3. `200` alınca `batchId`'yi saklar ve satırı `accepted` olarak işaretler. 4. Webhook işleyicisi satırı `DELIVERED` veya `READ` ya da nedenle `FAILED` olarak günceller. 5. Müşteri yanıt verirse destek aracı pencere içinde `TEXT` oturum mesajı kullanır. 6. Gece çalışan bir iş dünkü batch'ler için `bulk-insights`'ı okur ve eksik durumları mutabık hale getirir. ## Yaygın hatalar nelerdir? - **JSON göndermek.** WhatsApp gönderim uç noktası multipart'tır; `Content-Type: application/json` çalışmaz. - **`files=` yerine Python `data=`;** bu, formu url-encode eder. - **Pencere dışında serbest metin;** başarısız olur. Şablon kullanın. - **Yanlış dil kodu;** şablonun `en_US` değeri yerine `en` gibi. - **`200`'ü iletildi saymak.** Kuyruğa alındı demektir. - **Zaman aşımından sonra kör yeniden denemeler;** bir müşteriye iki kez mesaj gidebilir. - **İstemci kodunda token.** API'yi yalnızca arka ucunuzdan çağırın. - **Limitler:** yük ayrıntıları şablona göre değişir. İlk kişiselleştirilmiş kampanyanız için değişken düzenini ekibimizle teyit edin. ## OmniChannels.ai nasıl yardımcı olur? BroadNet resmi bir Meta Business Solution Provider'dır ve WhatsApp Business API'ye devreye alma Meta Embedded Signup kullanır; ekibimiz kaydı sizinle birlikte hazırlar, onaylar Meta'da kalır. REST API bir OpenAPI 3.1 belirtimi ve bir TypeScript SDK'sı olan `@broadnet/cpaas-sdk` ile belgelenmiştir; iletim durumları kanallar arasında normalleştirilir. [WhatsApp API belgeleriyle](/developers/whatsapp/) veya [hızlı başlangıçla](/developers/quickstart/) başlayın.