WhatsApp ve Telegram'da toplu gönderim API'si

WhatsApp ve Telegram'da toplu gönderim API'si: hesabı bağlayın, gönderimi oluşturun ve durumları doğrudan CRM'inizden ya da sitenizden takip edin.

Müşteriye giden mesajlar neredeyse hiçbir zaman "bir ara vakit bulunca" gerekmez. Olay anında gerekir: sipariş ödendi, randevu alındı, müşteri randevuya gelmedi, bir aydır ortada yok. Olay sisteminizde zaten gerçekleşti, bundan sonra panele girip gönderimi elle kurmak tuhaf olur.

Herkese açık API tam olarak bunun için var. Gönderimin tamamı ondan geçer: kitle toplama, metin denetimi, güvenli tempo, her alıcının durumu ve yanıtı. Kuyruğu, mesajlar arasındaki araları, yeniden denemeleri ve numaranın engellenmeye karşı korunmasını sizin kurmanıza gerek yok. Bunlarla servis ilgilenir, sizin sisteminizde tek bir çağrı kalır.

Üstelik hepsi için tek bir metot seti var: WhatsApp ve Telegram hesapları ve Telegram botları. Bir mesajlaşma uygulaması daha eklemek için yeni bir entegrasyon yazmanız gerekmez, aynı istekte yalnızca bir değer değişir.

Toplu gönderim API'si WhatsApp ve Telegram'da neler yapabilir

Panelde elle yaptığınız her şey HTTP üzerinden de yapılabilir:

• Mesajlaşma hesaplarını ve botları bağlamak. Tek istekle: mesajlaşma hesabı QR kodla ya da telefon numarasıyla, bot ise token'la bağlanır. Bağlantının sonucunu servis kendisi bildirir. Hesap iki adımlı doğrulama şifresiyle korunuyorsa şifre de API üzerinden iletilir.
• Kitle. Segment oluşturup telefon numaralarını yüklemek: tek istekte 100 numaraya kadar, daha büyük bir liste birkaç istekte yüklenir. Projenin zaten tanıdığı numaralar ikinci kez eklenmez.
• Gönderimler. Oluşturmak, metin ya da medya eklemek (görsel, video, ses, belge; bir gönderimde en fazla on mesaj), alıcıları seçmek: kişi segmenti, hesabın telefon rehberi ya da mevcut sohbetler. Ardından metin denetimi, başlatma, duraklatma, iptal.
• Taslağı düzenlemek. Gönderim başlatılmadığı sürece mesajların metni ve dosyaları aynı şekilde API üzerinden değiştirilebilir, fazla mesajlar silinebilir, gönderimin adı değiştirilebilir. Metni düzenlerseniz tamamlanmış denetim sıfırlanır: gönderim başlatılmadan önce moderasyondan yeniden geçer.
• Her alıcı için sonuç. Gönderildi, teslim edildi, okundu, yanıt geldi, numara mesajlaşma uygulamasında yok.
• Alıcıların yanıtları. Yanıt geldiği bilgisinin yanında yanıtın metni de gelir: kişinin gönderime yanıtında tam olarak ne yazdığı.
• Tek mesaj gönderme. İşlemsel durumlar için ayrı bir metot var: her istekte kendi metniniz ve ekiniz. Tek bir numara için gönderim kurmanıza gerek kalmaz.
• Yazışmanın tamamı. Kişiyle sohbet geçmişi: gelen ve giden mesajlar tek akışta. Yeni gelen mesajı servis bir olayla bildirir. Yanıtı aynı tekil gönderim metoduyla verebilir, hatta belirli bir mesajı alıntılayarak yanıtlayabilirsiniz. Botlarda gelen mesaj hemen ulaşır, mesajlaşma hesaplarında ise yazışma senkronizasyonla, yani gecikmeyle çekilir. İki durumda da yanıt analitiği olan bir tarife gerekir, buna aşağıda değineceğiz.
• Webhook'lar. Hesap bağlandı ya da bağlantısı kesildi, mesajlaşma uygulaması hesabı kısıtladı, gönderim başladı, duraklatıldı, tamamlandı, alıcı yanıt verdi, yeni mesaj geldi. API'yi sürekli sorgulamanıza gerek yok.

Gönderen hakkında önemli bir nokta: mesajlar, kendiniz bağladığınız sizin hesaplarınızdan gider. Servis kendi numarasını vermez ve bu iyi bir şey: numara da itibarı da sizde kalır, müşterilerin yanıtları da her zamanki mesajlaşma uygulamanıza gelir.

API anahtarı nasıl alınır

1. Gönderim paneline girin ve API bölümünü açın.
2. "Anahtar oluştur" düğmesine basın, bir ad verin (anahtarın hangi entegrasyona verildiğini sonra bu addan anlarsınız) ve isterseniz geçerlilik süresi belirleyin.
3. Token'ı kopyalayın. Token yalnızca bir kez gösterilir: servis sadece hash değerini saklar ve token'ı geri getiremez. Kaybettiyseniz yeni bir anahtar oluşturun, eskisini silin.

API bölümü yalnızca proje sahibine açıktır: anahtarları yalnızca o oluşturur ve listesini görür. Yani entegrasyonu bir yazılımcı ya da dış ekip yapıyorsa anahtarı proje sahibi oluşturur ve token'ı ona iletir. Panele erişim vermesine gerek kalmaz.

Anahtar projeye verilir, belirli bir çalışana bağlı olmaz. Onu bir şifre gibi saklayın. Birden fazla anahtar oluşturabilirsiniz, örneğin her entegrasyona bir tane. Böylece her birini diğerlerinden bağımsız olarak iptal edebilirsiniz.

Anahtarın yetkileri vardır ve oluşturulurken işaretlenir: proje verilerini okumak, gönderim ve kitle hazırlamak, gönderim başlatmak ve mesaj göndermek, hesapları yönetmek, webhook ayarlamak. Yeni anahtar varsayılan olarak okuyabilir ve hazırlayabilir, gerisini bilerek siz verirsiniz. Yetkiler sonradan da anahtarın kendisi değişmeden değiştirilebilir: anahtarın verildiği entegrasyonu durdurmanız gerekmez.

Token her isteğin başlığında iletilir. Her şeyin çalıştığını bağlı hesapların listesini isteyerek kontrol edebilirsiniz:

curl https://api.wsender.io/v1/channel \
  -H "Authorization: key TOKENINIZ"

Tüm metotlar API belgelerinde açıklanıyor. İsteği kendi anahtarınızla, tek satır kod yazmadan doğrudan tarayıcıdan çalıştırabilirsiniz. Yanında makine tarafından okunabilen spesifikasyon da var, OpenAPI dosyası: Swagger Codegen veya NSwag gibi araçlar bu dosyadan kullandığınız dilde istemciyi kendileri üretir, istekleri ve modelleri elle tanımlamanıza gerek kalmaz.

Yedi istekte toplu gönderim

En kısa senaryo şöyle: segmenti topladınız → gönderimi oluşturdunuz → metni eklediniz → alıcıları belirttiniz → denetime gönderdiniz → başlattınız.

1. PUT /v1/segment segment oluşturur.
2. PUT /v1/segment/{segmentId}/contact numaraları yükler.
3. PUT /v1/mailing gönderimi oluşturur.
4. PUT /v1/mailing/{mailingId}/message/text mesaj metnini ekler.
5. PUT /v1/mailing/{mailingId}/recipient/source alıcıların segmentten alınacağını belirtir.
6. POST /v1/mailing/{mailingId}/moderate metni denetime gönderir.
7. POST /v1/mailing/{mailingId}/start gönderimi seçilen hesaptan başlatır.

İstekler her hesap ve bot için aynı: WhatsApp'ta gönderim, Telegram'daki ya da bottan yapılan gönderimle aynı şekilde oluşturulur. Değişen yalnızca neyin bağlı olduğu. Sonrasında hiçbir şeyi sorgulamanız gerekmez, durumlar webhook'larla gelir.

Tekrarlanan istek ikinci bir gönderim oluşturmaz

Entegrasyonlarda sık görülen bir durum: istek gitti, yanıt gelmedi. Ağ bir anlığına koptu, zaman aşımı devreye girdi, servisiniz en olmadık anda yeniden başladı. Sonra ne yapacağınız belli değil. Tekrarlarsanız ikinci bir gönderim oluşturabilir ya da gönderimi iki kez başlatabilirsiniz. Tekrarlamazsanız hiçbir şeyin gitmediği ortaya çıkabilir.

Bu yüzden bir şeyi değiştiren her isteğin bir tekrar anahtarı (idempotency key) vardır. Bir dize belirleyip (genellikle UUID) başlıkta iletirsiniz:

Idempotency-Key: 3f0c1b7e-8a2e-4a51-9d2b-6a1e0f2c4d88

Tek kural var: yeni işlem için yeni anahtar, aynı işlemin tekrarı için aynı anahtar. Gerisini servis halleder. İlk istek çalıştırılır ve yanıtı bir gün boyunca saklanır. Aynı anahtarla gelen tekrar istek hiçbir şey çalıştırmaz, ilk seferdeki yanıtın aynısı döner. İlk istek hâlâ işleniyorsa tekrar 409 kodunu alır: biraz bekleyip yeniden deneyin.

Aynı anahtarla farklı bir istek gönderirseniz 422 kodu gelir. Bu, anahtarın yanlışlıkla yeniden kullanılmasına karşı bir koruma: başka bir isteğin sonucunu almazsınız.

Entegrasyon için pratik sonuç şu. Sonuç döndürmeyen durumlarda isteği tekrarlamak mantıklı: bağlantı kopması, sunucu hataları ve 429 yanıtı (istek sıklığı aşımı). Bu yanıtlar saklanmaz ve tekrar, işlemi gerçekten çalıştırır. İçerikle ilgili bir ret ise, örneğin "metinde zorunlu bir alan eksik", zaten bir sonuçtur ve tekrar da aynısını döndürür.

Toplu gönderimde alıcılar nereden alınır

Beşinci adım ayrıca ele alınmayı hak ediyor: hem sonuç hem de hesap için risk kaynağa bağlı. Üç kaynak var.

• Kişi segmenti. Numaraları siz yüklersiniz. Segmente bağlı gönderim, sonradan eklediğiniz kişilere de mesaj göndermeye devam eder. Entegrasyon için ana kaynak bu, aşağıda ona ayrı bir bölüm ayırdık.
• Hesabın kişileri. Bağlı numaranın telefon rehberi. Varsayılan olarak mesajlar yalnızca daha önce yazıştığınız kişilere gider: böyle bir kitle hem daha iyi yanıt verir hem de neredeyse hiç şikâyete yol açmaz. Bu kısıtlamayı kaldırabilirsiniz, ama kaldırmamanızı öneririz.
• Hesabın sohbetleri. Mevcut sohbetler. Burada da yalnızca yazıştığınız kişileri bırakabilir, servis sohbetlerine yazmamak için botlarla olan sohbetleri ayrıca hariç tutabilirsiniz.

Tasarım aşamasında hesaba katmanız gereken bir ayrıntı: ilk başlatmada kaynak, mesajlaşma uygulamasıyla birlikte sabitlenir ve bir daha değişmez. Başka bir kaynak için yeni bir gönderim gerekir.

Telegram botlarında da aynı API

Ayrı bir "bot API'miz" yok ve bu bilinçli bir tercih: hesaptan gönderim için yazılmış bir entegrasyon, botla da değişiklik yapmadan çalışır. Aynı bağlantı metotları, aynı durumlar, aynı webhook'lar, taslaktan alıcı raporuna kadar gönderimin aynı yolu.

Tam olarak iki fark var ve ikisi de hemen göze çarpar.

Token'la bağlantı. Token'ı Telegram'da @BotFather verir. Sonrası hesap için gönderilen istekle aynı, yalnızca giriş yöntemi yerine token gönderilir. Token yeniden oluşturulursa bot kaybolmaz: ayrı bir token güncelleme isteği, zaten bağlı botun token'ını değiştirir. Aboneler, gönderimler ve geçmiş yerinde kalır (panelde aynı işi botun sayfasındaki token güncelleme bağlantısı yapar).

Alıcılar: botun aboneleri. Bot yalnızca kendisine önce yazan kişilere yazabilir, yüklenmiş numara segmenti bot için kullanılamaz. Platform böyle kurulu: Bot API ilk mesajı botun atmasına izin vermez ve bunu kimse aşamaz.

Buradan entegrasyonda basit bir rol paylaşımı çıkıyor. Henüz yazışmadığınız birine ulaşmanın tek yolu mesajlaşma hesabı olarak kalır. Bot ise zaten abone olanlarla çalışmak için var. Bu tür bir gönderimde engellenme riski doğuracak bir şey yok: telefon numarası işin içine hiç girmiyor. Hızın tek sınırı platformun limitleri: hesabı korumak için temkinli bir hesap ısıtmaya gerek kalmaz.

Tetikleyici gönderimler: her olay için tek çağrı

Segmentin en kullanışlı özelliği şu: ona bağlı gönderim, segmentteki herkese mesaj gönderdiğinde sona ermez. Çalışmaya devam eder ve yeni kişileri bekler. Siz onları segmente ekler eklemez gönderim hemen yeniden başlar.

Başlatılmış bir gönderim aslında bir gönderim kuyruğu gibi çalışır. Dolayısıyla şema şöyle olur:

1. Bir kez segment ve ona bağlı gönderimi oluşturur, metni ekler ve başlatırsınız. API ile ya da panelde elle, sonrası için fark etmez.
2. Sonra sisteminizdeki her olay için tek bir istek yaparsınız: numarayı segmente eklemek.

Hepsi bu. Mesaj kendiliğinden gider: güvenli tempoda, denetlenmiş metinle ve limitler gözetilerek. Sipariş ödendi, randevu alındı, müşteri randevuya gelmedi, bir aydır ortada yok: kendi tetikleyici gönderimleriniz oluşur ve her durum için bakımını yapmanız gereken tek bir çağrı kalır.

Abonelikten çıkma da aynı kolaylıkla çalışır ve bunu önceden düşünmekte fayda var. Kişi artık mesaj almak istemediğini söylediyse numarasını tek istekle segmentten silin, kuyruk onu almaz. Kişinin kaydı geçmişiyle birlikte projede kalır, yalnızca bu kitleden çıkar.

Böyle bir gönderimin metni tüm alıcılar için aynıdır, ad yerleştirme ve ifade varyantlarıyla. Bu yüzden her durum için ayrı bir "segment + gönderim" çifti kurulur: karşılama, randevu hatırlatması, müşteriyi geri kazanma. Bir kez oluşturulurlar, sonra yalnızca numara beklerler.

Müşteri yanıtları sisteminize geri döner

Gönderim, mesaj gittiğinde bitmez. İnsanlar yanıt verir ve çoğu zaman bütün işin amacı da bu yanıttır. API üzerinden kişinin yanıt verdiğini de, tam olarak ne yazdığını da görürsünüz.

Sıra şöyle: "alıcı yanıt verdi" webhook'u gelir, ardından bu alıcının yanıtlarını sorgular ve saati, metni, mesaj türünü ve ekli dosyaların adlarını alırsınız.

curl https://api.wsender.io/v1/mailing/{GONDERIM_ID}/recipient/{ALICI_ID}/reply \
  -H "Authorization: key TOKENINIZ"

Yalnızca bu gönderime verilen yanıtlar döner, kişiyle yazışmanın geri kalanı gelmez: servis, ilgili alıcıya gönderimden sonraki mesajları alır. "Yanıt verdi" durumu da aynı kurala göre atanır, böylece durum ile içerik birbirini tutar.

Sonra yanıt CRM'inize gider: satış temsilcisinin görev listesine, satış ekibinin sohbetine, dashboard'a. Gereğinden fazlasını varsaymamanız için iki uyarı. Yazışma hesaptan belirli aralıklarla çekilir, bu yüzden kişinin yanıtı ile API'de görünmesi arasında zaman geçer. Kişi metin yerine mesaja tepki bıraktıysa liste boş olabilir.

Henüz kendi CRM'iniz yoksa aynı yanıtları panelden açılan Dialogs penceresinde görürsünüz: operatör onları okur ve oradan yanıtlar. API ile gönderilen mesajların yanında orada "API" etiketi olur, etiketin üzerine gelince hangi anahtarla gönderildikleri görünür.

Tarifelerle ilgili en önemli nokta da şu. Yanıtlar, onlarla birlikte hesabın sohbetleri ve kişileri, bağlı hesabın senkronizasyonundan gelir. Senkronizasyon ise her tarifede yok, ücretsiz tarifede bulunmaz. Ücretsiz tarifede entegrasyonu kurup deneyebilirsiniz, gönderimler oluşturulur ve gider, ama geri bildirim olmaz: yanıt webhook'u gelmez, yanıt isteği de bu özelliğin tarifede olmadığını açıklayan 403 hatası döndürür. Boş liste yerine hata dönmesi bilinçli bir tercih: boş yanıtı "kişi yanıt vermedi" diye okur ve hatayı kendi tarafınızda arardınız.

Botlarda da durum aynı. Ücretsiz tarifede bot yalnızca giden yönde çalışır: gönderimler gider, abonelerden gelen mesajlar ise alınmaz ve hiçbir yerde saklanmaz, ne API'de ne panelde. Yeni aboneler ise eklenmeye devam eder ve onlara gönderim yapılabilir.

Webhook'lar: neler olduğunu servis kendisi bildirir

API'yi "ne oldu" diye sürekli sorgulamanıza gerek yok. Kendi adresinizi belirtin, olaylar kendiliğinden gelsin:

curl -X PUT https://api.wsender.io/v1/webhook \
  -H "Authorization: key TOKENINIZ" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/wsender","secret":"gizli-deger"}'

Her projenin tek bir webhook'u olur, adres mutlaka HTTPS olmalı. Örnekteki adresi ve gizli değeri (secret) kendinizinkilerle değiştirin. Gizli değerde Latin harfler (Türkçe karakterler olmadan), rakamlar, kısa çizgi ve alt çizgi kullanılabilir. Servis bunu her isteğin X-WSender-Secret-Token başlığında size geri gönderir. Böylece kendi olaylarınızı aynı adrese gelen yabancı isteklerden ayırırsınız.

Olaylar dört grupta toplanır:

• Hesap: bağlandı, bağlantısı kesildi; bağlantı sırasında ise QR kod hazır, eşleştirme kodu hazır, doğrulama kodu ya da iki adımlı doğrulama şifresi bekleniyor, her şey tamam.
• Mesajlaşma uygulamasının kısıtlamaları: hesap kısıtlandı ve kısıtlama kaldırıldı. Belki de en değerlisi bu: engellendiğinde hesap bağlı kalır ve olay gelmezse gönderim sessizce durur.
• Gönderim: denetimden geçti, uyarılarla geçemedi, başlatıldı, nedeniyle birlikte duraklatıldı, tamamlandı, iptal edildi.
• Alıcılar: mesajlar gönderildi, kişi yanıt verdi, gönderim başarısız oldu, numara mesajlaşma uygulamasında yok.

Alıcılara ve tek tek mesajlara ait olaylar yalnızca açık abonelikle gelir. İhtiyacınız olan türleri events içinde listeleyin. Boş liste bunları açmaz, böylece büyük bir gönderim gereksiz bir olay akışı yaratmaz.

Gelen olayı önce güvenli biçimde kaydedin, sonra 2xx koduyla yanıt verin ve işleyin. Sunucunuz 10 saniye içinde yanıt vermezse ya da hata döndürürse servis 30 saniye ile yarım saat arasında değişen aralıklarla yeniden dener. Her olay, oluşturulduğu andan itibaren kuyrukta en fazla bir gün saklanır.

Aynı olay tekrar gelebilir: CRM'deki işlemi iki kez yapmamak için olayın id değerini kontrol edin.

İlk başarısızlıktan bu yana bir gün geçtiyse ve bu sürede tek bir başarılı teslimat olmadıysa webhook otomatik olarak askıya alınır. Proje sahibine, Telegram'da bağlı olan WSENDER bildirim botu üzerinden bildirim gelir. Durumu GET /v1/webhook isteğiyle kontrol edebilirsiniz: health nesnesinde Active ya da Suspended durumu, son hata ve tarihler bulunur.

Olayları alan sunucunuzu düzelttikten sonra, webhook yönetme yetkisi olan bir anahtarla POST /v1/webhook/resume çağırın:

curl -X POST https://api.wsender.io/v1/webhook/resume \
  -H "Authorization: key TOKENINIZ"

Servis adresinize, her zamanki gizli değerle bir webhook.test deneme olayı gönderir. Teslimatı yalnızca 2xx yanıtı yeniden başlatır. Normal POST /v1/webhook/test adresi kontrol etmeye yarar, ama askıyı kaldırmaz.

Askı süresince yeni olaylar birikmez, daha önce oluşturulanların saklama süresi de uzamaz. Süresi dolan olaylar ve askı sırasında oluşan olaylar, teslimat yeniden başladıktan sonra gelmez. Bu yüzden uzun bir kesintiden sonra mesajların ve gönderimlerin güncel durumlarını API üzerinden sorgulayın. Alanların ve hataların ayrıntıları API belgelerinde.

Gönderim hızı: API neden her şeyi bir anda göndermez

Yazılımcıların beklentileri ile mesajlaşma uygulamalarının gerçekliği en çok burada ayrışır. API isteği anında kabul eder, gönderim temposunu ise Otomatik Strateji belirler. Otomatik Strateji sakin başlar ve hesabın gönderim geçmişi biriktikçe hızı artırır. Platform hesabı yavaşlatırsa servis gönderimi duraklatır ve daha yavaş devam eder.

Servis numaranızı böyle korur: tüm listenize bir saatte gönderim yaparsanız mesajlaşma uygulaması büyük olasılıkla hesabı kısıtlar. Bu yüzden serviste böyle bir seçenek yok.

Entegrasyondan önce hesaba katmanız gereken dört nokta daha:

• Metin başlatmadan önce denetlenir. Yapay zekâ mesajı inceler ve uyarılar döndürebilir. Liste API üzerinden okunur, her uyarıda neyin yanlış olduğu ve hangi mesajda olduğu görünür. Öneri niteliğindeki uyarılar tek istekle kabul edilir, yasaklı konular ise yalnızca metni düzelterek giderilir.
• Tarife limitleri paneldekiyle aynı çalışır. Mesajlar günlük kotadan düşer. Kota dolduğunda gönderim duraklar ve kendiliğinden devam etmez, panelden ya da API ile yeniden başlatmanız gerekir.
• İstek limiti proje başına sayılır. Projenin tüm anahtarları için ortaktır, yeni anahtar çıkarmak limiti artırmaz.
• Soğuk numaralar daha yavaş gider. Numara yazışmalarınızda yoksa önce mesajlaşma uygulamasına bu numaranın kayıtlı olup olmadığını sormak gerekir. Telegram bu aramayı çok daha sıkı sınırlar, bu yüzden orada tanınmayan numaralara gönderim, WhatsApp'takinden belirgin şekilde daha yavaş ilerler.

Toplu gönderim API'si nerede işe yarar

• CRM: anlaşma ve sipariş durumu bildirimleri, müşteri yanıtları da karta geri döner.
• Online mağaza: sipariş onayı, ödeme, kargo.
• Site veya landing sayfası: başvuruya, kişinin kullandığı mesajlaşma uygulamasından anında yanıt.
• Online randevu: ziyaretten bir gün önce hatırlatma.
• Müşteriyi geri kazanma: "3 aydır alışveriş yapmadı" segmenti kendi veritabanınızdan beslenir, gönderim de kuyruğu kendisi işler.

Sırada ne var

API için ayrıca ücret yok, normal tarifeler geçerli ve API ücretsiz tarifede bile kullanılabiliyor. Ücretsiz tarifede günde 15 mesaj var, entegrasyonu kurup denemek için bu yeterli.

Küçük başlayın: bir anahtar oluşturun, hesap listesi isteğini çalıştırın, bir hesap bağlayın ve yalnızca kendi numaranızdan oluşan bir segmente gönderim yapın. Tüm akış yarım saatte netleşir. Sonrasında çalışan bir "segment + gönderim" çifti kurmak ve olayın ortaya çıktığı yerden ona numara eklemek kalır.

Metotların tam açıklaması API belgelerinde, istemci üretmek için spesifikasyon ise OpenAPI dosyasında.