API DokümantasyonuAPI v1
v1.1Inohype WP · WhatsApp Mesajlaşma API'si

WhatsApp mesajlarını kendi numaranızdan API ile gönderin

Inohype WP API'si, panelde QR kod ile bağladığınız kendi WhatsApp hesabınız üzerinden kişilere ve gruplara metin, görsel, video, ses ve belge göndermenizi sağlar. Sipariş bildirimleri, randevu hatırlatmaları ve ekip duyuruları gibi akışları birkaç satır kodla sisteminize ekleyin.

Base URL https://wp.inohype.com
HTTPS + JSONİstek ve yanıt gövdeleri JSON; karakter kodlaması UTF-8.
X-API-KeyHer anahtar tek bir WhatsApp hesabına (oturuma) bağlıdır.
60 istek / dakikaAnahtar başına hız limiti; aşıldığında HTTP 429.
Kendi numaranızMesajlar, QR ile bağladığınız WhatsApp hesabından gider.

Endpoint özeti

Tüm uçlar https://wp.inohype.com/api/external/ altındadır ve X-API-Key başlığı ister.

Yanıt yapısı

Tüm yanıtlar JSON'dır ve success (boolean) alanını içerir. Başarısız isteklerde HTTP durum kodu 4xx/5xx olur ve error alanında Türkçe bir açıklama döner.

{
  "success": true,
  "message": "Mesaj gönderildi",
  "remaining": 4821,
  "sent_to": "905551112233"
}
{
  "success": false,
  "error": "Geçersiz API anahtarı"
}

Kararlarınızı HTTP durum koduna göre verin. error metinleri insanlar için yazılmış Türkçe açıklamalardır ve ifadeleri ileride değişebilir. Tüm durum kodları ve anlamları için Hata Kodları bölümüne bakın.

Başlarken

Hızlı Başlangıç

Dört adımda ilk WhatsApp mesajınızı API ile gönderin. Hesabınız hazırsa tüm süreç genellikle birkaç dakika sürer.

  1. Panele giriş yapın

    Inohype WP'de herkese açık kayıt yoktur; hesabınızı yönetici oluşturur ve giriş bilgilerinizi size iletir. wp.inohype.com adresinden giriş yapın. Hesabınızda iki adımlı doğrulama (2FA) açıksa, doğrulayıcı uygulamanızdaki (Google Authenticator, Authy vb.) kodu da girmeniz istenir.

  2. WhatsApp numaranızı bağlayın

    Panel → Hesaplar → Hesap Ekle ile hesaba bir ad verin (ör. magaza-hatti) ve QR kodu oluşturun. Telefonunuzda WhatsApp → Bağlı Cihazlar → Cihaz Bağla menüsünü açıp QR kodu okutun. Bağlantı tamamlandığında hesap panelde bağlı olarak görünür.

  3. API anahtarı oluşturun

    Panel → API Keys bölümünde gönderim yapacak WhatsApp hesabını seçin ve anahtar oluşturun. Anahtar wpr_ ile başlar ve yalnızca seçtiğiniz hesaba bağlıdır. Anahtarı hemen kopyalayın ve sunucunuzda güvenli bir yerde (ör. .env dosyası) saklayın.

  4. İlk mesajınızı gönderin

    Anahtarı ve alıcı numarasını kendi değerlerinizle değiştirip isteği çalıştırın. İlk testi kendi ikinci numaranıza ya da bir ekip arkadaşınıza yapmanızı öneririz.

    curl -X POST "https://wp.inohype.com/api/external/send-message" \
      -H "X-API-Key: wpr_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "to": "905551112233",
        "message": "Merhaba! Bu, Inohype WP API ile gönderilen ilk test mesajıdır."
      }'
    {
      "success": true,
      "message": "Mesaj gönderildi",
      "remaining": 4821,
      "sent_to": "905551112233"
    }

Önce bağlantıyı test edin. GET /api/external/me kota harcamadan anahtarınızın geçerli olduğunu, hangi hesaba bağlı olduğunu ve WhatsApp oturumunun bağlı olup olmadığını gösterir.

Başlarken

Kimlik Doğrulama

Her istek, X-API-Key HTTP başlığında gönderilen API anahtarıyla doğrulanır. Anahtar aynı zamanda mesajın hangi WhatsApp numarasından gideceğini belirler.

POST /api/external/send-message HTTP/1.1
Host: wp.inohype.com
X-API-Key: wpr_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Anahtar özellikleri

ÖzellikAçıklama
Biçimwpr_ öneki + 64 karakter onaltılık (0-9, a-f); toplam 68 karakter. Başlık adı büyük/küçük harfe duyarlı değildir; anahtarın başındaki ve sonundaki boşluklar yok sayılır.
KapsamHer anahtar tam olarak bir WhatsApp hesabına (oturuma) bağlıdır. İstekte numara veya hesap seçilmez; mesaj, anahtarın bağlı olduğu numaradan gider. Birden fazla numaradan gönderim için her hesaba ayrı anahtar oluşturun.
KotaMesaj kotası anahtar başına değil kullanıcı başınadır; tüm hesaplarınız ve anahtarlarınız aynı kotayı paylaşır. Bkz. Kota ve Hız Limitleri.
İptalPanel → API Keys üzerinden iptal edilen anahtar anında geçersiz olur ve sonraki isteklerde 401 Geçersiz API anahtarı döner.
Gönderim yoluAnahtar yalnızca X-API-Key başlığında kabul edilir. Authorization: Bearer, URL parametresi (?api_key=) veya gövdede anahtar gönderimi desteklenmez.
Content-TypePOST isteklerinde Content-Type: application/json gönderin. Bu başlık olmadan JSON gövde okunamaz ve 400 to ve message gerekli hatası alırsınız.

Anahtarı asla tarayıcıya veya mobil uygulamaya koymayın. API, CORS açısından tüm kökenlere açıktır (Access-Control-Allow-Origin: *); bu, tarayıcıdan da istek atılabileceği anlamına gelir. Ancak sayfa kaynağına, JavaScript paketine ya da mobil uygulamaya gömülen anahtar herkes tarafından okunabilir; kotanız tüketilebilir ve numaranızdan istenmeyen mesajlar gönderilebilir. İstekleri her zaman kendi sunucunuzdan yapın.

Kimlik doğrulama yanıtları

HTTPerrorNeden
401API anahtarı gerekliX-API-Key başlığı gönderilmemiş ya da başlık adı yanlış yazılmış.
401Geçersiz API anahtarıAnahtar hatalı/eksik kopyalanmış, iptal edilmiş, bağlı olduğu WhatsApp hesabı silinmiş veya kullanıcı hesabınız pasif.
403Mesaj kotası dolduKullanıcı kotanız bitmiş. send-message, send-to-group ve groups uçlarını engeller; /me çalışmaya devam eder.
429Çok fazla istek. Lütfen biraz bekleyin.Dakikalık istek limiti aşıldı. Hız limiti, kimlik doğrulamadan önce uygulanır.
Endpoint

Mesaj gönder

POST https://wp.inohype.com/api/external/send-message

Bir kişiye metin mesajı ya da açıklamalı (caption) medya gönderir. Başarılı her istek kotanızdan 1 mesaj düşer; başarısız istekler kotadan düşmez.

X-API-Key JSON gövde 1 mesaj kotası 60 istek / dk

Gövde parametreleri

AdTipZorunluAçıklama
to string Evet

Alıcının telefon numarası. Rakam dışındaki karakterler (boşluk, +, -, parantez) temizlenir ve numara normalize edilir. Ör. 905551112233 veya 0555 111 22 33. Ayrıntılar: Telefon Numarası Formatı.

message string Evet

Mesaj metni. media_url gönderildiğinde medyanın açıklaması (caption) olur ve yine zorunludur. < ve > karakterleri silinir, baştaki ve sondaki boşluklar kırpılır; satır sonları (\n) korunur.

media_url string Hayır

Herkese açık, doğrudan indirilebilir bir http(s) adresi. Sunucu dosyayı indirir ve medya olarak gönderir. Bkz. Medya Gönderimi.

media_mimetype string Hayır

Yalnızca mesaj geçmişine kaydedilir, gönderimi etkilemez; MIME türü indirilen dosyadan belirlenir. Ör. application/pdf.

Mesaj biçimlendirme

WhatsApp'ın standart biçimlendirme işaretleri olduğu gibi çalışır:

YazımGörünüm
*kalın*kalın
_italik_italik
~üstü çizili~üstü çizili
```mono```mono

Satır atlamak için JSON metninde \n kullanın; emojiler UTF-8 olarak doğrudan gönderilebilir.

{
  "to": "905551112233",
  "message": "*Sipariş #10482 kargoda* 🚚\n\nMerhaba Ayşe, siparişiniz _bugün_ kargoya verildi.\nTakip no: ```TR123456789```"
}

< ve > karakterleri iletilmez. Örneğin İndirim <bugün> metni İndirim bugün olarak gider. Karşılaştırma veya ok için ≤, ≥, → gibi Unicode karakterleri kullanabilirsiniz.

İstek
curl -X POST "https://wp.inohype.com/api/external/send-message" \
  -H "X-API-Key: wpr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0555 111 22 33",
    "message": "Merhaba Ayşe, *#10482* numaralı siparişiniz kargoya verildi.\nTakip no: TR123456789"
  }'
Yanıt
{
  "success": true,
  "message": "Mesaj gönderildi",
  "remaining": 4821,
  "sent_to": "905551112233"
}

Yanıt alanları 200

AlanTipAçıklama
successbooleanBaşarılı isteklerde true.
messagestringMesaj gönderildi
remainingintegerBu mesaj düşüldükten sonra kalan kullanıcı kotanız.
sent_tostringNormalize edilmiş alıcı numarası (ör. 905551112233). Kayıt ve mükerrer gönderim kontrolü için saklayın.

Hatalar

HTTPerrorNe zaman?
400to ve message gereklito veya message eksik ya da boş; veya Content-Type: application/json gönderilmemiş.
400Geçersiz telefonNormalize edilmiş numara 10–15 hane değil.
401API anahtarı gerekli / Geçersiz API anahtarıBaşlık yok veya anahtar geçersiz. Bkz. Kimlik Doğrulama.
403Mesaj kotası dolduKullanıcı kotanız bitti.
429Çok fazla istek. Lütfen biraz bekleyin.Anahtar başına dakikada 60 istek aşıldı.
503Hesap bağlı değilAnahtarın bağlı olduğu WhatsApp oturumu şu an bağlı değil.
500Mesaj gönderilemedi: <ayrıntı>WhatsApp gönderimi tamamlanamadı; örneğin medya indirilemedi veya alıcıya gönderim reddedildi.

200, "teslim edildi" demek değildir. Başarılı yanıt, mesajın WhatsApp'a iletildiğini gösterir; alıcıya ulaştığını veya okunduğunu garanti etmez. API şu an teslim/okundu bilgisi sağlamaz.

Endpoint

Grup mesajı gönder

POST https://wp.inohype.com/api/external/send-to-group

Bağlı WhatsApp hesabınızın üyesi olduğu bir gruba metin veya açıklamalı medya gönderir. Başarılı her istek kotanızdan 1 mesaj düşer (gruptaki üye sayısından bağımsız).

X-API-Key JSON gövde 1 mesaj kotası 60 istek / dk

Gövde parametreleri

AdTipZorunluAçıklama
group_id string Evet

Grup kimliği, 120363XXXXXXXXXXXX@g.us biçiminde. GET /api/external/groups ile alın ve olduğu gibi gönderin (numara normalizasyonu uygulanmaz).

message string Evet

Mesaj metni veya medya açıklaması. < ve > silinir, kenar boşlukları kırpılır, satır sonları korunur. Biçimlendirme desteklenir.

media_url string Hayır

Herkese açık, doğrudan indirilebilir http(s) dosya adresi. Bkz. Medya Gönderimi.

media_mimetype string Hayır

Yalnızca mesaj geçmişine kaydedilir; gönderimi etkilemez.

Grup üyeliği ve yetki gerekir. Bağlı numara grubun üyesi olmalı ve grupta mesaj gönderme izni bulunmalıdır. Yalnızca yöneticilerin mesaj gönderebildiği gruplarda numaranın yönetici olması gerekir; aksi halde 500 Grup mesajı gönderilemedi: … döner.

İstek
curl -X POST "https://wp.inohype.com/api/external/send-to-group" \
  -H "X-API-Key: wpr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "120363012345678901@g.us",
    "message": "*Duyuru:* Bu akşam 22.00 itibarıyla 30 dakikalık planlı bakım yapılacaktır."
  }'
Yanıt
{
  "success": true,
  "message": "Grup mesajı gönderildi",
  "remaining": 4820,
  "sent_to": "120363012345678901@g.us"
}

Yanıt alanları 200

AlanTipAçıklama
successbooleanBaşarılı isteklerde true.
messagestringGrup mesajı gönderildi
remainingintegerBu mesaj düşüldükten sonra kalan kullanıcı kotanız.
sent_tostringMesajın gönderildiği grup kimliği (istekteki group_id).

Hatalar

HTTPerrorNe zaman?
400group_id ve message gerekliAlanlardan biri eksik/boş veya Content-Type gönderilmemiş.
401API anahtarı gerekli / Geçersiz API anahtarıBaşlık yok veya anahtar geçersiz.
403Mesaj kotası dolduKullanıcı kotanız bitti.
429Çok fazla istek. Lütfen biraz bekleyin.Dakikalık istek limiti aşıldı.
503Hesap bağlı değilWhatsApp oturumu bağlı değil.
500Grup mesajı gönderilemedi: <ayrıntı>Geçersiz grup ID'si, numara grupta değil, yazma yetkisi yok veya medya indirilemedi.
Endpoint

Grupları listele

GET https://wp.inohype.com/api/external/groups

Bağlı WhatsApp hesabının üyesi olduğu grupları ID, ad ve katılımcı sayısıyla listeler. Kotadan düşmez; ancak kotanız dolduysa bu uç da 403 Mesaj kotası doldu döner.

X-API-Key Parametre yok Kotadan düşmez 60 istek / dk

Gruba mesaj göndermenin üç adımı

1 · Grup ID'sini bulun

GET /api/external/groups ile grupları listeleyin ve hedef grubun id değerini alın.

2 · ID'yi saklayın

Grup ID'leri değişmez. Listeyi her gönderimden önce çekmek yerine ID'yi bir kez alıp yapılandırmanızda tutun.

3 · Mesajı gönderin

ID'yi POST /api/external/send-to-group isteğinde group_id olarak kullanın.

Yanıt alanları 200

AlanTipAçıklama
successbooleanBaşarılı isteklerde true.
groupsarrayBağlı numaranın üye olduğu gruplar.
groups[].idstringGrup kimliği (…@g.us); send-to-group isteğindeki group_id.
groups[].namestringGrubun WhatsApp'taki adı. Adlar değişebilir ve benzersiz olmayabilir; eşleştirme için id kullanın.
groups[].participants_countintegerKatılımcı sayısı; katılımcı bilgisi alınamazsa 0.
totalintegerListelenen grup sayısı.
İstek
curl "https://wp.inohype.com/api/external/groups" \
  -H "X-API-Key: wpr_xxxxxxxxxxxxxxxxxxxxxxxx"
Yanıt
{
  "success": true,
  "groups": [
    {
      "id": "120363012345678901@g.us",
      "name": "Müşteri Duyuru",
      "participants_count": 148
    }
  ],
  "total": 1
}

Hatalar

HTTPerrorNe zaman?
401API anahtarı gerekli / Geçersiz API anahtarıBaşlık yok veya anahtar geçersiz.
403Mesaj kotası dolduKota dolduğunda bu uç da engellenir.
429Çok fazla istek. Lütfen biraz bekleyin.Dakikalık istek limiti aşıldı.
503Hesap bağlı değilWhatsApp oturumu bağlı değil.
500Gruplar yüklenemediGrup listesi alınamadı; kısa bir süre sonra tekrar deneyin.

Yanıt süresi. Liste, bağlı hesabın tüm sohbetleri taranarak oluşturulur; çok sayıda sohbeti olan hesaplarda yanıt birkaç saniye sürebilir. İstemci zaman aşımını en az 60 saniye tutun ve sonucu önbelleğe alın.

Endpoint · Yeni

Hesap durumu

GET https://wp.inohype.com/api/external/me

Anahtarın bağlı olduğu WhatsApp hesabını, oturumun bağlı olup olmadığını, kota kullanımını ve anahtar bilgilerini döndürür. Kotadan düşmez ve kotanız dolu olsa bile çalışır; entegrasyonunuz için ideal bir sağlık kontrolüdür (health check).

X-API-Key Parametre yok Kotadan düşmez Hız limitine dahil

Yanıt alanları 200

AlanTipAçıklama
account.namestringPanelde verdiğiniz hesap adı.
account.phonestring | nullHesaba kayıtlı WhatsApp numarası (ülke koduyla); kayıtlı değilse null.
account.connectedbooleanWhatsApp oturumu şu an bağlı mı? false ise gönderim istekleri 503 Hesap bağlı değil döner.
quota.limitintegerToplam mesaj kotanız (kullanıcı başına).
quota.usedintegerKullanılan mesaj sayısı.
quota.remainingintegerKalan mesaj hakkı; en az 0.
key.idintegerAnahtarın kimliği.
key.created_atstringOluşturulma zamanı, YYYY-MM-DD HH:MM:SS (UTC).
key.last_usedstring | nullBu istekten önceki son kullanım zamanı (UTC); hiç kullanılmadıysa null.
İstek
curl "https://wp.inohype.com/api/external/me" \
  -H "X-API-Key: wpr_xxxxxxxxxxxxxxxxxxxxxxxx"
Yanıt
{
  "success": true,
  "account": {
    "name": "magaza-hatti",
    "phone": "905551112233",
    "connected": true
  },
  "quota": {
    "limit": 5000,
    "used": 179,
    "remaining": 4821
  },
  "key": {
    "id": 12,
    "created_at": "2026-11-01 09:12:44",
    "last_used": "2026-11-17 10:03:10"
  }
}

Ne zaman kullanılır?

Gönderimden önce

Toplu bir gönderim kuyruğunu başlatmadan önce account.connected değerini kontrol edin.

Kota alarmı

Periyodik olarak çağırıp quota.remaining belirlediğiniz eşiğin altına düştüğünde ekibinizi uyarın.

Anahtar doğrulama

Anahtarı yeniledikten sonra yeni anahtarın doğru hesaba bağlı olduğunu doğrulayın.

Hatalar

HTTPerrorNe zaman?
401API anahtarı gerekli / Geçersiz API anahtarıBaşlık yok veya anahtar geçersiz.
429Çok fazla istek. Lütfen biraz bekleyin.Dakikalık istek limiti aşıldı; /me çağrıları da limite sayılır.
Kılavuz

Telefon Numarası Formatı

to alanı esnektir: numarayı boşluklu, tireli veya + ile yazabilirsiniz. Sunucu numarayı aşağıdaki kurallarla tek bir biçime (yalnızca rakam, ülke kodu + numara) çevirir; sonuç yanıtta sent_to olarak döner.

Normalizasyon kuralları

  1. Rakam olmayan tüm karakterler silinir: boşluk, +, -, (, ), nokta vb.
  2. Numara 0 ile başlıyorsa baştaki 0 kaldırılır ve yerine 90 (Türkiye) eklenir.
  3. Numara 10 haneliyse ve 90 ile başlamıyorsa başına 90 eklenir.
  4. Sonuç 10–15 hane değilse istek 400 Geçersiz telefon ile reddedilir.

Örnekler

Girdi (to)Sonuç (sent_to)Açıklama
0555 111 22 33905551112233Baştaki 0 → 90.
+90 (555) 111-22-33905551112233Rakam dışı karakterler silinir.
555111223390555111223310 hane, 90 ile başlamıyor → başına 90 eklenir.
905551112233905551112233Zaten doğru biçimde; önerilen kullanım.
+49 151 1234 56784915112345678Yabancı numara, ülke koduyla yazıldığı için doğru.
123454005 hane; Geçersiz telefon.
0049 151 1234 567840000 öneki: baştaki 0, 90 ile değiştirilir ve numara 16 haneye çıkar.
2125550123902125550123Yanlış kişi Ülke kodu olmadan yazılmış 10 haneli bir ABD numarası Türk numarası sanılır.

Yabancı numaraları mutlaka ülke koduyla gönderin. Ülke kodu olmadan yazılmış 10 haneli bir yabancı numara Türk numarası olarak yorumlanır ve başına 90 eklenir; mesaj gönderilemeyebilir ya da yanlış kişiye gidebilir. Uluslararası 00 önekini de kullanmayın; numarayı +49… veya 49… biçiminde yazın.

Göndermeden önce doğrulayın

Aynı kuralları kendi tarafınızda uygulayarak hatalı numaraları API'ye göndermeden ayıklayabilir ve kayıtlarınızı tek biçimde tutabilirsiniz:

<?php
// PHP 8+ — Inohype WP sunucusuyla aynı kurallar. Geçersizse null döner.
function normalizePhone(string $phone): ?string
{
    $p = preg_replace('/[^0-9]/', '', $phone);

    if (str_starts_with($p, '0')) {
        $p = '90' . substr($p, 1);
    } elseif (strlen($p) === 10 && !str_starts_with($p, '90')) {
        $p = '90' . $p;
    }

    $len = strlen($p);
    return ($len >= 10 && $len <= 15) ? $p : null;
}

var_dump(normalizePhone('0555 111 22 33')); // string(12) "905551112233"
var_dump(normalizePhone('12345'));          // NULL
Kılavuz

Medya Gönderimi

send-message veya send-to-group isteğine media_url eklediğinizde sunucu dosyayı bu adresten indirir ve WhatsApp'a medya olarak yükler. message alanı medyanın açıklaması (caption) olur ve medya gönderirken de zorunludur.

Görsel

Ör. JPG, PNG

Video

Ör. MP4

Ses

Ör. MP3, OGG

Belge

Ör. PDF, DOCX, XLSX, ZIP

Türler örnektir; kabul edilen biçimler ve dosya boyutları WhatsApp'ın kendi sınırlarına tabidir.

Gereksinimler

  • Herkese açık http:// veya https:// adresi. Dosyayı sunucumuz internetten indirir; localhost, iç ağ adresleri veya yalnızca sizin erişebildiğiniz adresler çalışmaz.
  • Doğrudan indirilebilir olmalı. Adres dosyanın kendisini döndürmelidir. Giriş isteyen, önizleme/indirme ara sayfası açan veya HTML sayfası döndüren bağlantılar (ör. bulut sürücü paylaşım bağlantıları) çalışmaz.
  • MIME türü indirilen dosyadan belirlenir. Dosyayı doğru Content-Type başlığıyla sunun. media_mimetype yalnızca mesaj geçmişine kaydedilir, gönderimi etkilemez.
  • Boyut sınırları WhatsApp'a aittir. Çok büyük dosyalar reddedilebilir veya isteği uzatabilir.
  • İndirme süresi isteğe eklenir. Medya gönderirken istemci zaman aşımını en az 60 saniye tutun.
  • Hata durumunda kota düşmez. Dosya indirilemez veya WhatsApp yüklemeyi reddederse 500 Mesaj gönderilemedi: … (grupta Grup mesajı gönderilemedi: …) döner.

Süreli (imzalı) bağlantılar. S3/R2 gibi depolamalardan ön imzalı URL veriyorsanız geçerlilik süresini birkaç dakikadan kısa tutmayın; dosya gönderim anında indirilir.

Örnek: PDF fatura gönderme

curl -X POST "https://wp.inohype.com/api/external/send-message" \
  -H "X-API-Key: wpr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  --max-time 60 \
  -d '{
    "to": "905551112233",
    "message": "Merhaba Ayşe, Kasım ayı faturanız ektedir.",
    "media_url": "https://example.com/faturalar/F-2026-0042.pdf",
    "media_mimetype": "application/pdf"
  }'
{
  "success": true,
  "message": "Mesaj gönderildi",
  "remaining": 4821,
  "sent_to": "905551112233"
}
Kılavuz

Kota ve Hız Limitleri

İki ayrı sınır vardır: toplam kaç mesaj gönderebileceğinizi belirleyen mesaj kotası ve dakikada kaç istek yapabileceğinizi belirleyen hız limiti.

Mesaj kotası

  • Kullanıcı başınadır: tüm WhatsApp hesaplarınız ve API anahtarlarınız aynı kotayı paylaşır. Panelden gönderdiğiniz mesajlar da aynı kotadan düşer.
  • Başarılı her gönderim 1 mesajdır: kişiye veya gruba, metin ya da medya + açıklama fark etmez. Başarısız istekler kotadan düşmez.
  • Limiti paketinize göre yönetici belirler. Kalan hakkınızı yanıtlardaki remaining alanından veya GET /api/external/me ile izleyin.
  • Kota dolunca send-message, send-to-group ve groups uçları 403 Mesaj kotası doldu döner; /me çalışmaya devam eder.

İstek hız limiti

60 istek / dakika / API anahtarı

  • /api/external/* altındaki tüm uçlar için geçerlidir; /me çağrıları ve başarısız istekler de sayılır.
  • Sayaç API anahtarı başına tutulur; anahtar göndermeyen istekler IP adresine göre sınırlanır.
  • 1 dakikalık pencere dolduğunda HTTP 429 döner; pencere sıfırlanınca istekler yeniden kabul edilir.

Hız limiti başlıkları

RateLimit-* başlıklarını izleyerek limite yaklaştığınızı önceden görebilir, 429 aldığınızda ne kadar bekleyeceğinizi Retry-After ile öğrenebilirsiniz.

BaşlıkÖrnekAçıklama
RateLimit-Policy60;w=60Limit ve pencere süresi (saniye).
RateLimit-Limit60Penceredeki toplam istek hakkı.
RateLimit-Remaining0Penceredeki kalan istek hakkı.
RateLimit-Reset42Pencerenin sıfırlanmasına kalan süre (saniye).
Retry-After42429 yanıtında: tekrar denemeden önce beklenecek süre (saniye).
HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
RateLimit-Policy: 60;w=60
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 42
Retry-After: 42
{
  "success": false,
  "error": "Çok fazla istek. Lütfen biraz bekleyin."
}

Hız limiti bir hedef değil, teknik üst sınırdır. WhatsApp, kısa sürede çok sayıda mesaj gönderen hesapları kısıtlayabilir veya yasaklayabilir.

  • Aynı hesaptan gönderilen mesajlar arasında en az 1–3 saniye bekleyin.
  • Toplu gönderimleri bir kuyrukla sıraya alın; aynı anda paralel istek göndermeyin. Bkz. Toplu gönderim kuyruğu.
Kılavuz

Hata Kodları

Hatalı yanıtlar her zaman {"success": false, "error": "…"} biçimindedir. Aşağıdaki tablo tüm uçlarda dönebilecek hataları, nedenlerini ve yapmanız gerekenleri listeler.

HTTPerrorNedenNe yapmalı?
400 to ve message gerekli send-message: alan eksik/boş ya da Content-Type: application/json gönderilmemiş. Gövdeyi ve başlığı düzeltin. Tekrar denemek sonucu değiştirmez.
400 group_id ve message gerekli send-to-group: alan eksik/boş ya da Content-Type eksik. Gövdeyi ve başlığı düzeltin.
400 Geçersiz telefon Normalize edilmiş numara 10–15 hane değil. Numarayı ülke koduyla düzeltin. Bkz. Telefon Numarası Formatı.
401 API anahtarı gerekli X-API-Key başlığı yok veya adı yanlış yazılmış. Başlığı ekleyin. Authorization başlığı kullanılmaz.
401 Geçersiz API anahtarı Anahtar hatalı/eksik kopyalanmış, iptal edilmiş, bağlı hesap silinmiş veya kullanıcı hesabı pasif. Panel → API Keys'te anahtarı kontrol edin; gerekirse yenisini oluşturun.
403 Mesaj kotası doldu Kullanıcı kotanız bitti (me hariç tüm uçları engeller). Kota artışı için yöneticinizle iletişime geçin. Tekrar denemeyin.
429 Çok fazla istek. Lütfen biraz bekleyin. Anahtar başına dakikada 60 istek aşıldı. Retry-After kadar bekleyip tekrar deneyin; istekleri zamana yayın.
503 Hesap bağlı değil Anahtarın bağlı olduğu WhatsApp oturumu kopmuş (ör. telefondan bağlı cihaz kaldırılmış, oturum sonlanmış). Panel → Hesaplar'dan QR kodu yeniden okutun. Geçici kopmalar için üstel beklemeyle tekrar deneyin.
503 WhatsApp Store henüz hazır değil. Lütfen 30 saniye bekleyip tekrar deneyin. Hesap yeni bağlandı veya yeniden bağlanıyor; WhatsApp oturumu henüz tam yüklenmedi (geçici). 30 saniye bekleyip tekrar deneyin.
500 Mesaj gönderilemedi: <ayrıntı> WhatsApp gönderimi tamamlanamadı; ör. medya indirilemedi veya gönderim reddedildi. Ayrıntıyı loglayın. Mesaj gitmiş olabilir; körlemesine tekrar denemeyin.
500 Grup mesajı gönderilemedi: <ayrıntı> Geçersiz grup ID'si, numara grupta değil, grupta yazma yetkisi yok veya medya indirilemedi. Grup ID'sini ve yetkileri kontrol edin; ayrıntıyı loglayın.
500 Gruplar yüklenemedi Grup listesi WhatsApp'tan alınamadı. Kısa süre sonra tekrar deneyin (salt okunur, güvenli).
400 Geçersiz JSON gövdesi İstek gövdesi ayrıştırılamadı (eksik tırnak, sondaki virgül, yanlış kodlama vb.). Gövdeyi bir JSON kütüphanesiyle üretin ve Content-Type: application/json gönderin. Tekrar denemek işe yaramaz.
404 Endpoint bulunamadı Yol veya HTTP metodu yanlış (ör. GET /api/external/send-message). Yanıtta path ve method alanları da döner. Yolu ve metodu Endpoint özeti ile karşılaştırın.
413 İstek gövdesi çok büyük (en fazla 10 MB) JSON gövdesi 10 MB sınırını aşıyor. Medyayı gövdeye gömmeyin; media_url ile adres olarak gönderin.
500 Sunucu hatası Beklenmeyen sunucu hatası. Kısa süre sonra tekrar deneyin; sorun sürerse yöneticinize bildirin.

Tüm /api/… yanıtları JSON'dur. Yanlış yol veya metot (ör. GET /api/external/send-message) 404 {"success":false,"error":"Endpoint bulunamadı"} döndürür. Yine de yanıtı ayrıştırmadan önce durum kodunu ve Content-Type başlığını kontrol edin (ör. önünüzdeki bir proxy/CDN hata sayfası döndürebilir).

Kılavuz

Yeniden Deneme & En İyi Uygulamalar

Ağ kesintileri ve geçici durumlar her entegrasyonda yaşanır. Hangi hatanın tekrar denenebileceğini bilmek hem mesaj kaybını hem de aynı mesajın iki kez gitmesini önler.

Hangi durumda tekrar denemeli?

DurumTekrar dene?Nasıl?
400 401 403Hayırİstek, anahtar veya kota düzeltilmeden sonuç değişmez.
429EvetRetry-After başlığındaki süre kadar bekleyin.
503Evet30 saniyeden başlayan üstel bekleme (30 → 60 → 120 sn). Sürerse panelden hesabı yeniden bağlayın.
500 POSTKörlemesine değilMesaj gitmiş olabilir. Ayrıntıyı loglayın; tekrar göndermeden önce telefonunuzdaki WhatsApp'ta ilgili sohbeti kontrol edin.
5xx GETEvetgroups ve me salt okunurdur; üstel beklemeyle güvenle tekrar denenebilir.
Zaman aşımı / bağlantı koptu (POST)DikkatSunucu mesajı göndermiş olabilir; 500 ile aynı şekilde ele alın.

Idempotency anahtarı yoktur. Aynı isteği iki kez gönderirseniz alıcı mesajı iki kez alır. Her gönderim için kendi kayıt kimliğinizi, HTTP kodunu ve başarılı yanıttaki sent_to değerini loglayın; aynı iş için ikinci kez göndermeden önce bu kaydı kontrol edin.

Üstel beklemeli yeniden deneme

Aşağıdaki yardımcılar yalnızca 429 ve 503 yanıtlarında bekleyip yeniden dener; diğer hatalarda (özellikle 500) hemen hata fırlatır.

#!/usr/bin/env bash
# 429 ve 503'te bekleyip yeniden dener; 500'de DENEMEZ (mesaj gitmiş olabilir).
BODY='{"to":"905551112233","message":"Randevunuz yarın 14.00 için onaylandı."}'

for deneme in 1 2 3 4; do
  kod=$(curl -sS -o yanit.json -D basliklar.txt -w "%{http_code}" \
    -X POST "https://wp.inohype.com/api/external/send-message" \
    -H "X-API-Key: $INOHYPE_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$BODY")

  if [ "$kod" = "429" ] || [ "$kod" = "503" ]; then
    bekle=$(grep -i '^retry-after:' basliklar.txt | tr -dc '0-9')
    [ -z "$bekle" ] && bekle=$(( 30 * 2 ** (deneme - 1) ))
    echo "HTTP $kod, $bekle sn sonra tekrar denenecek ($deneme/4)" >&2
    sleep "$bekle"
    continue
  fi

  cat yanit.json; echo
  break
done

Toplu gönderim kuyruğu

API'de toplu gönderim ucu yoktur; her alıcı için ayrı istek gönderilir. Mesajları sırayla, aralarında 2–3 saniye bekleyerek gönderin ve kota bittiğinde durun. Örnekler yukarıdaki yeniden deneme yardımcılarını kullanır.

#!/usr/bin/env bash
# numaralar.txt: her satırda bir numara. Gereksinim: curl, jq
while IFS= read -r numara; do
  jq -n --arg to "$numara" --arg m "Merhaba, yarınki randevunuzu hatırlatırız. Görüşmek üzere!" \
    '{to: $to, message: $m}' \
  | curl -sS -X POST "https://wp.inohype.com/api/external/send-message" \
      -H "X-API-Key: $INOHYPE_API_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @-
  echo
  sleep 2   # aynı hesaptan mesajlar arası en az 2 sn
done < numaralar.txt

En iyi uygulamalar

Numaraları doğrulayın

Göndermeden önce aynı normalizasyon kurallarıyla kontrol edin; yabancı numaraları ülke koduyla saklayın.

Kişisel ve beklenen mesajlar

Yalnızca sizinle iletişime izin veren kişilere yazın ve mesajları kişiselleştirin. Aynı metnin topluca gönderilmesi ve spam şikâyetleri numaranızın WhatsApp tarafından yasaklanmasına yol açabilir.

Hızı zamana yayın

Aynı hesaptan mesajlar arasında 1–3 saniye bekleyin; paralel istek yerine kuyruk kullanın.

Zaman aşımı belirleyin

Metin mesajlarında 30 sn, medya ve grup listesinde 60 sn istemci zaman aşımı yeterlidir.

Loglayın

Her gönderimde HTTP kodu, error, sent_to ve remaining değerlerini kaydedin. API anahtarını asla loglamayın.

Sağlığı izleyin

/me ile bağlantıyı ve kotayı periyodik kontrol edin; connected: false olduğunda ekibinizi uyarın.

Kılavuz

Entegrasyon Örnekleri

Kopyalayıp kendi projenize uyarlayabileceğiniz, çalışır durumda örnekler. Tüm örnekler API anahtarını kodun içine yazmak yerine ortam değişkeninden (INOHYPE_API_KEY) veya yapılandırma dosyasından okur.

WordPress / WooCommerce

Sipariş Hazırlanıyor (processing) durumuna geçtiğinde müşteriye WhatsApp bildirimi gönderir, sonucu sipariş notu olarak kaydeder ve aynı sipariş için ikinci kez göndermez. Önce anahtarı wp-config.php dosyasına tanımlayın:

define('INOHYPE_API_KEY', 'wpr_xxxxxxxxxxxxxxxxxxxxxxxx');

Ardından aşağıdaki kodu temanızın (tercihen alt temanın) functions.php dosyasının sonuna ya da küçük bir eklentiye ekleyin:

/**
 * Inohype WP — sipariş "Hazırlanıyor" (processing) durumuna geçince
 * müşteriye WhatsApp bildirimi gönderir.
 */
add_action('woocommerce_order_status_processing', 'inohype_wp_siparis_bildirimi', 10, 2);

function inohype_wp_siparis_bildirimi($order_id, $order = null)
{
    if (!defined('INOHYPE_API_KEY')) {
        return;
    }

    $order = $order instanceof WC_Order ? $order : wc_get_order($order_id);
    if (!$order || $order->get_meta('_inohype_wp_bildirildi')) {
        return; // sipariş yok veya daha önce bildirildi
    }

    // Yurt dışı müşterilerde numaranın ülke koduyla girildiğinden emin olun
    $telefon = $order->get_billing_phone();
    if (empty($telefon)) {
        return;
    }

    $mesaj = sprintf(
        "Merhaba %s,\n\n*#%s* numaralı siparişinizi aldık ve hazırlamaya başladık.\nToplam: %s %s\n\nTeşekkür ederiz!",
        $order->get_billing_first_name(),
        $order->get_order_number(),
        $order->get_total(),
        $order->get_currency()
    );

    $yanit = wp_remote_post('https://wp.inohype.com/api/external/send-message', [
        'timeout' => 30,
        'headers' => [
            'X-API-Key'    => INOHYPE_API_KEY,
            'Content-Type' => 'application/json',
        ],
        'body'    => wp_json_encode([
            'to'      => $telefon,
            'message' => $mesaj,
        ]),
    ]);

    if (is_wp_error($yanit)) {
        $order->add_order_note('WhatsApp bildirimi gönderilemedi: ' . $yanit->get_error_message());
        return;
    }

    $kod  = (int) wp_remote_retrieve_response_code($yanit);
    $veri = json_decode(wp_remote_retrieve_body($yanit), true);

    if ($kod === 200 && !empty($veri['success'])) {
        $order->update_meta_data('_inohype_wp_bildirildi', current_time('mysql'));
        $order->add_order_note('WhatsApp bildirimi gönderildi: ' . $veri['sent_to']);
        $order->save();
    } else {
        $order->add_order_note(sprintf(
            'WhatsApp bildirimi başarısız (HTTP %d): %s',
            $kod,
            $veri['error'] ?? 'bilinmeyen hata'
        ));
    }
}

Yoğun mağazalar için: wp_remote_post isteği sipariş akışı sırasında çalışır. Ödeme adımını hiç bekletmemek için gönderimi WooCommerce ile gelen Action Scheduler (as_enqueue_async_action) ile arka plana alabilirsiniz.

Laravel

Laravel HTTP istemcisi (Http::withHeaders) ile küçük bir servis sınıfı ve 429/503'te kendini yeniden kuyruğa alan bir iş (job).

INOHYPE_API_URL=https://wp.inohype.com
INOHYPE_API_KEY=wpr_xxxxxxxxxxxxxxxxxxxxxxxx
// Mevcut dizinin içine ekleyin
'inohype' => [
    'url' => env('INOHYPE_API_URL', 'https://wp.inohype.com'),
    'key' => env('INOHYPE_API_KEY'),
],
<?php

namespace App\Services;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;

class InohypeWp
{
    private function client(): PendingRequest
    {
        return Http::withHeaders(['X-API-Key' => config('services.inohype.key')])
            ->baseUrl(config('services.inohype.url'))
            ->acceptJson()
            ->timeout(60);
    }

    /** @throws \Illuminate\Http\Client\RequestException */
    public function sendMessage(string $to, string $message, ?string $mediaUrl = null): array
    {
        return $this->client()
            ->post('/api/external/send-message', array_filter([
                'to'        => $to,
                'message'   => $message,
                'media_url' => $mediaUrl,
            ]))
            ->throw()
            ->json();
    }

    /** @throws \Illuminate\Http\Client\RequestException */
    public function sendToGroup(string $groupId, string $message, ?string $mediaUrl = null): array
    {
        return $this->client()
            ->post('/api/external/send-to-group', array_filter([
                'group_id'  => $groupId,
                'message'   => $message,
                'media_url' => $mediaUrl,
            ]))
            ->throw()
            ->json();
    }

    public function groups(): array
    {
        return $this->client()->get('/api/external/groups')->throw()->json('groups');
    }

    public function me(): array
    {
        return $this->client()->get('/api/external/me')->throw()->json();
    }
}
<?php

namespace App\Jobs;

use App\Services\InohypeWp;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Http\Client\RequestException;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SendWhatsAppMessage implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 4;

    public function __construct(public string $to, public string $message)
    {
    }

    public function handle(InohypeWp $wp): void
    {
        try {
            $result = $wp->sendMessage($this->to, $this->message);
            logger()->info('WhatsApp gönderildi', [
                'sent_to'   => $result['sent_to'],
                'remaining' => $result['remaining'],
            ]);
        } catch (RequestException $e) {
            $status = $e->response->status();

            if (in_array($status, [429, 503], true)) {
                // Geçici durum: Retry-After kadar (yoksa 30 sn) sonra tekrar kuyruğa al
                $this->release((int) ($e->response->header('Retry-After') ?: 30));
                return;
            }

            // 4xx ve 500: tekrar deneme (500'de mesaj gitmiş olabilir)
            $this->fail($e);
        }
    }
}
use App\Jobs\SendWhatsAppMessage;
use App\Services\InohypeWp;

// Tek mesaj (senkron)
$sonuc = app(InohypeWp::class)->sendMessage('0555 111 22 33', 'Merhaba! Ödemeniz alındı, teşekkür ederiz.');

// Toplu gönderim: işleri 2 sn arayla kuyruğa alın (php artisan queue:work)
foreach ($musteriler as $i => $musteri) {
    SendWhatsAppMessage::dispatch(
        $musteri->phone,
        "Merhaba {$musteri->first_name}, randevunuz yarın 14.00 için onaylandı."
    )->delay(now()->addSeconds($i * 2));
}

Node.js

Bağımlılığı olmayan, Node.js 18+ yerleşik fetch kullanan küçük bir istemci. Hatalarda HTTP kodunu ve Retry-After değerini taşıyan bir hata fırlatır.

// inohype-wp.js — Node.js 18+, ek paket gerekmez
const BASE_URL = 'https://wp.inohype.com';

class InohypeWpError extends Error {
  constructor(status, message, retryAfter) {
    super(message);
    this.name = 'InohypeWpError';
    this.status = status;
    this.retryAfter = retryAfter; // saniye (yalnızca 429)
  }
}

class InohypeWp {
  constructor(apiKey = process.env.INOHYPE_API_KEY, { timeoutMs = 60_000 } = {}) {
    if (!apiKey) throw new Error('INOHYPE_API_KEY tanımlı değil');
    this.apiKey = apiKey;
    this.timeoutMs = timeoutMs;
  }

  async request(method, path, body) {
    const res = await fetch(BASE_URL + path, {
      method,
      headers: {
        'X-API-Key': this.apiKey,
        ...(body ? { 'Content-Type': 'application/json' } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
      signal: AbortSignal.timeout(this.timeoutMs),
    });

    const data = await res.json().catch(() => ({}));
    if (!res.ok) {
      const retryAfter = Number(res.headers.get('retry-after')) || null;
      throw new InohypeWpError(res.status, data.error || `HTTP ${res.status}`, retryAfter);
    }
    return data;
  }

  sendMessage(to, message, mediaUrl) {
    return this.request('POST', '/api/external/send-message', {
      to,
      message,
      ...(mediaUrl ? { media_url: mediaUrl } : {}),
    });
  }

  sendToGroup(groupId, message, mediaUrl) {
    return this.request('POST', '/api/external/send-to-group', {
      group_id: groupId,
      message,
      ...(mediaUrl ? { media_url: mediaUrl } : {}),
    });
  }

  async groups() {
    const data = await this.request('GET', '/api/external/groups');
    return data.groups;
  }

  me() {
    return this.request('GET', '/api/external/me');
  }
}

module.exports = { InohypeWp, InohypeWpError };
const { InohypeWp, InohypeWpError } = require('./inohype-wp');

const wp = new InohypeWp(); // anahtar INOHYPE_API_KEY ortam değişkeninden okunur

(async () => {
  const durum = await wp.me();
  if (!durum.account.connected) {
    throw new Error('WhatsApp hesabı bağlı değil, panelden QR kodu yeniden okutun');
  }

  try {
    const r = await wp.sendMessage('0555 111 22 33', 'Merhaba! Randevunuz yarın 14.00 için onaylandı.');
    console.log('Gönderildi:', r.sent_to, '| kalan kota:', r.remaining);
  } catch (err) {
    if (err instanceof InohypeWpError) console.error(err.status, err.message);
    else throw err;
  }
})();

Python

requests kütüphanesiyle (pip install requests) oturum tabanlı küçük bir istemci.

# inohype_wp.py — pip install requests
import os

import requests

BASE_URL = "https://wp.inohype.com"


class InohypeWpError(Exception):
    def __init__(self, status, message, retry_after=None):
        super().__init__(f"HTTP {status}: {message}")
        self.status = status
        self.message = message
        self.retry_after = retry_after  # saniye (yalnızca 429)


class InohypeWp:
    def __init__(self, api_key=None, timeout=60):
        self.session = requests.Session()
        self.session.headers["X-API-Key"] = api_key or os.environ["INOHYPE_API_KEY"]
        self.timeout = timeout

    def _request(self, method, path, payload=None):
        resp = self.session.request(method, BASE_URL + path, json=payload, timeout=self.timeout)
        try:
            data = resp.json()
        except ValueError:
            data = {}
        if not resp.ok:
            retry_after = resp.headers.get("Retry-After", "")
            raise InohypeWpError(
                resp.status_code,
                data.get("error", resp.reason),
                int(retry_after) if retry_after.isdigit() else None,
            )
        return data

    def send_message(self, to, message, media_url=None):
        payload = {"to": to, "message": message}
        if media_url:
            payload["media_url"] = media_url
        return self._request("POST", "/api/external/send-message", payload)

    def send_to_group(self, group_id, message, media_url=None):
        payload = {"group_id": group_id, "message": message}
        if media_url:
            payload["media_url"] = media_url
        return self._request("POST", "/api/external/send-to-group", payload)

    def groups(self):
        return self._request("GET", "/api/external/groups")["groups"]

    def me(self):
        return self._request("GET", "/api/external/me")


if __name__ == "__main__":
    wp = InohypeWp()
    durum = wp.me()
    print("Bağlı:", durum["account"]["connected"], "| Kalan kota:", durum["quota"]["remaining"])

    try:
        sonuc = wp.send_message("0555 111 22 33", "Merhaba! Randevunuz yarın 14.00 için onaylandı.")
        print("Gönderildi:", sonuc["sent_to"])
    except InohypeWpError as e:
        print("Hata:", e.status, e.message)

PHP (cURL)

Çerçeve kullanmayan projeler için yalnızca ext-curl gerektiren yardımcı fonksiyonlar (PHP 7.4+).

<?php
// inohype-wp.php — PHP 7.4+ ve ext-curl

const INOHYPE_WP_URL = 'https://wp.inohype.com';

function inohype_wp_request(string $method, string $path, ?array $payload = null): array
{
    $headers = ['X-API-Key: ' . getenv('INOHYPE_API_KEY'), 'Accept: application/json'];

    $ch = curl_init(INOHYPE_WP_URL . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT        => 60,
    ]);
    if ($payload !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload, JSON_UNESCAPED_UNICODE));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $body = curl_exec($ch);
    if ($body === false) {
        $hata = curl_error($ch);
        curl_close($ch);
        throw new RuntimeException('Bağlantı hatası: ' . $hata);
    }
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($body, true) ?: [];
    if ($status !== 200) {
        throw new RuntimeException($data['error'] ?? "HTTP $status", $status);
    }
    return $data;
}

function inohype_wp_send(string $to, string $message, ?string $mediaUrl = null): array
{
    $payload = ['to' => $to, 'message' => $message];
    if ($mediaUrl) {
        $payload['media_url'] = $mediaUrl;
    }
    return inohype_wp_request('POST', '/api/external/send-message', $payload);
}

function inohype_wp_send_group(string $groupId, string $message): array
{
    return inohype_wp_request('POST', '/api/external/send-to-group', [
        'group_id' => $groupId,
        'message'  => $message,
    ]);
}

// Kullanım
try {
    $sonuc = inohype_wp_send('0555 111 22 33', 'Merhaba! Ödemeniz alındı, teşekkür ederiz.');
    echo "Gönderildi: {$sonuc['sent_to']} (kalan kota: {$sonuc['remaining']})\n";
} catch (RuntimeException $e) {
    error_log("WhatsApp hatası ({$e->getCode()}): {$e->getMessage()}");
}

C# (.NET)

HttpClient tabanlı, .NET 6+ ile çalışan tip güvenli bir istemci. ASP.NET Core'da IHttpClientFactory ile de kaydedilebilir.

// InohypeWpClient.cs — .NET 6+
using System.Net;
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Serialization;

public sealed class InohypeWpException : Exception
{
    public HttpStatusCode Status { get; }
    public TimeSpan? RetryAfter { get; }

    public InohypeWpException(HttpStatusCode status, string message, TimeSpan? retryAfter)
        : base(message) => (Status, RetryAfter) = (status, retryAfter);
}

public sealed record SendResult(
    [property: JsonPropertyName("success")] bool Success,
    [property: JsonPropertyName("message")] string Message,
    [property: JsonPropertyName("remaining")] int Remaining,
    [property: JsonPropertyName("sent_to")] string SentTo);

public sealed class InohypeWpClient
{
    private static readonly JsonSerializerOptions JsonOptions = new()
    {
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
    };

    private readonly HttpClient _http;

    public InohypeWpClient(HttpClient http, string apiKey)
    {
        _http = http;
        _http.BaseAddress = new Uri("https://wp.inohype.com");
        _http.Timeout = TimeSpan.FromSeconds(60);
        _http.DefaultRequestHeaders.Add("X-API-Key", apiKey);
    }

    public Task<SendResult> SendMessageAsync(string to, string message, string? mediaUrl = null) =>
        PostAsync<SendResult>("/api/external/send-message", new { to, message, media_url = mediaUrl });

    public Task<SendResult> SendToGroupAsync(string groupId, string message, string? mediaUrl = null) =>
        PostAsync<SendResult>("/api/external/send-to-group", new { group_id = groupId, message, media_url = mediaUrl });

    public Task<JsonElement> MeAsync() =>
        SendAsync<JsonElement>(new HttpRequestMessage(HttpMethod.Get, "/api/external/me"));

    private Task<T> PostAsync<T>(string path, object body) =>
        SendAsync<T>(new HttpRequestMessage(HttpMethod.Post, path)
        {
            Content = JsonContent.Create(body, options: JsonOptions)
        });

    private async Task<T> SendAsync<T>(HttpRequestMessage request)
    {
        using var response = await _http.SendAsync(request);
        if (response.IsSuccessStatusCode)
            return (await response.Content.ReadFromJsonAsync<T>())!;

        string error;
        try
        {
            var body = await response.Content.ReadFromJsonAsync<JsonElement>();
            error = body.GetProperty("error").GetString() ?? "";
        }
        catch
        {
            error = $"HTTP {(int)response.StatusCode}";
        }

        throw new InohypeWpException(response.StatusCode, error, response.Headers.RetryAfter?.Delta);
    }
}
using System.Net;

var apiKey = Environment.GetEnvironmentVariable("INOHYPE_API_KEY")
             ?? throw new InvalidOperationException("INOHYPE_API_KEY tanımlı değil");
var wp = new InohypeWpClient(new HttpClient(), apiKey);

try
{
    var r = await wp.SendMessageAsync("0555 111 22 33", "Merhaba! Ödemeniz alındı, teşekkür ederiz.");
    Console.WriteLine($"Gönderildi: {r.SentTo} (kalan kota: {r.Remaining})");
}
catch (InohypeWpException ex) when (ex.Status == HttpStatusCode.TooManyRequests)
{
    Console.WriteLine($"Hız limiti: {ex.RetryAfter?.TotalSeconds ?? 60} sn sonra tekrar deneyin.");
}
catch (InohypeWpException ex)
{
    Console.WriteLine($"Hata ({(int)ex.Status}): {ex.Message}");
}

Bash / cURL: gruba duyuru

Gruplarınızı listeleyip adına göre bulduğu gruba duyuru gönderen betik. JSON'u güvenle üretmek için jq kullanır (Türkçe karakterler ve tırnaklar sorun çıkarmaz).

#!/usr/bin/env bash
# Gereksinim: curl, jq
# Kullanım:   export INOHYPE_API_KEY="wpr_xxxxxxxxxxxxxxxxxxxxxxxx"
#             ./grup-duyuru.sh "Müşteri Duyuru" "*Duyuru:* Bu akşam 22.00 itibarıyla planlı bakım yapılacaktır."
set -euo pipefail

API="https://wp.inohype.com/api/external"
GRUP_ADI="${1:?Grup adı gerekli}"
MESAJ="${2:?Mesaj gerekli}"

# 1) Grupları çek ve yanıtı kontrol et
GRUPLAR=$(curl -sS "$API/groups" -H "X-API-Key: $INOHYPE_API_KEY")
if [ "$(echo "$GRUPLAR" | jq -r '.success')" != "true" ]; then
  echo "Gruplar alınamadı: $(echo "$GRUPLAR" | jq -r '.error')" >&2
  exit 1
fi

# 2) Grup ID'sini ada göre bul
GRUP_ID=$(echo "$GRUPLAR" | jq -r --arg ad "$GRUP_ADI" 'first(.groups[] | select(.name == $ad) | .id) // empty')
if [ -z "$GRUP_ID" ]; then
  echo "Grup bulunamadı: $GRUP_ADI" >&2
  exit 1
fi

# 3) Mesajı gönder
jq -n --arg g "$GRUP_ID" --arg m "$MESAJ" '{group_id: $g, message: $m}' \
| curl -sS -X POST "$API/send-to-group" \
    -H "X-API-Key: $INOHYPE_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-
echo
Kılavuz

Güvenlik

API anahtarı, WhatsApp numaranızdan mesaj gönderme yetkisidir. Bir şifre gibi koruyun.

Yalnızca sunucu tarafı

CORS tüm kökenlere açık (*) olsa da anahtarı tarayıcı JavaScript'ine, mobil uygulamaya veya masaüstü istemcisine koymayın. İstemciler kendi sunucunuza, sunucunuz Inohype WP'ye istek atmalıdır.

Ortam değişkeni / .env

Anahtarı koda yazmayın; .env dosyasında veya bir gizli anahtar yöneticisinde tutun ve .env dosyasını sürüm kontrolüne eklemeyin.

Düzenli yenileyin

Anahtarları belirli aralıklarla ve ekipten biri ayrıldığında yenileyin (adımlar aşağıda).

Yalnızca HTTPS

İstekleri her zaman https://wp.inohype.com adresine gönderin; anahtarı şifrelenmemiş bağlantı üzerinden iletmeyin.

En az yetki

Her entegrasyon (web sitesi, CRM, ekip botu) için ayrı WhatsApp hesabı ve anahtar kullanın; bir anahtarı iptal etmek diğerlerini etkilemez.

Panelde 2FA

Panel hesabınızda iki adımlı doğrulamayı (Google Authenticator / Authy) açık tutun. Panele erişen biri anahtarlarınızı yönetebilir.

.env örneği

# Inohype WP — bu dosyayı asla sürüm kontrolüne eklemeyin
INOHYPE_API_KEY=wpr_xxxxxxxxxxxxxxxxxxxxxxxx
# Gizli yapılandırma
.env
.env.*

Anahtarı yenileme (rotasyon)

  1. Panel → API Keys bölümünde ilgili hesabın mevcut anahtarını iptal edin. Bir hesapta aynı anda tek aktif anahtar bulunur.
  2. Aynı hesap için yeni anahtar oluşturun ve hemen kopyalayın.
  3. Sunucularınızdaki .env / gizli anahtar kaydını güncelleyip uygulamanızı yeniden başlatın.
  4. GET /api/external/me ile yeni anahtarın doğru hesaba bağlı olduğunu doğrulayın.

İptal anında etkili olduğundan, eski anahtarla yapılan istekler bu aralıkta 401 alır. Yenilemeyi düşük trafikli bir zamanda yapın.

Anahtarınız sızdıysa:

  • Anahtarı panelden hemen iptal edin; iptal edilen anahtar anında 401 döner.
  • Panelde mesaj geçmişini ve kalan kotanızı kontrol edin.
  • Yeni anahtarı yalnızca sunucu tarafında, gizli olarak dağıtın.
Destek

SSS / Sorun Giderme

En sık karşılaşılan durumlar ve çözümleri.

Sürekli 401 alıyorum. Ne yapmalıyım?
  • Başlık adının tam olarak X-API-Key olduğundan emin olun. Authorization: Bearer … kullanılmaz.
  • Anahtarın tamamını (wpr_ + 64 karakter) kopyaladığınızı ve tırnak işareti eklemediğinizi kontrol edin.
  • Anahtar panelden iptal edilmiş, bağlı WhatsApp hesabı silinmiş ya da kullanıcı hesabınız pasif olabilir. Panel → API Keys'te anahtarın aktif olduğunu kontrol edin.
  • API anahtarı gerekli mesajı başlığın hiç ulaşmadığını gösterir; bir proxy veya HTTP istemcisi başlığı siliyor olabilir.
503 "Hesap bağlı değil" hatası alıyorum.

Anahtarın bağlı olduğu WhatsApp oturumu kopmuş demektir. Panel → Hesaplar bölümünden hesabı açıp QR kodu telefonunuzdan yeniden okutun. Telefonda WhatsApp → Bağlı Cihazlar listesinden oturumu kaldırırsanız veya WhatsApp uzun süre (yaklaşık 14 gün) telefonda hiç açılmazsa bağlı cihazlar oturumu sonlanabilir.

Yeniden bağlandıktan hemen sonra kısa süreliğine WhatsApp Store henüz hazır değil… hatası görebilirsiniz; 30 saniye bekleyip tekrar deneyin. Durumu kota harcamadan /me ile izleyebilirsiniz.

200 aldım ama mesaj karşı tarafa ulaşmadı.

200 yanıtı mesajın WhatsApp'a iletildiğini gösterir; teslimi garanti etmez. Olası nedenler:

  • Numara WhatsApp'ta kayıtlı değil veya yanlış normalize edildi (ör. ülke kodu olmayan yabancı numara). Yanıttaki sent_to değerini kontrol edin.
  • Alıcı sizi engellemiş veya alıcının telefonu uzun süredir çevrim dışı.
  • WhatsApp, numaranızın gönderimlerini kısıtlamış olabilir (çok hızlı veya istenmeyen gönderimler).

API mesajları kendi hesabınızdan gönderdiği için gönderilen mesajlar telefonunuzdaki WhatsApp'ta ilgili sohbette görünür; tik durumunu oradan kontrol edebilirsiniz.

Numarayı hangi formatta göndermeliyim?

En güvenlisi ülke kodu + numara, yalnızca rakam: 905551112233. 0555 111 22 33 ve +90 555 111 22 33 de kabul edilir. Yabancı numaraları mutlaka ülke koduyla yazın ve 00 önekini kullanmayın. Tüm kurallar: Telefon Numarası Formatı.

Kotam doldu. Nasıl artırırım?

Kota, paketinize göre yönetici tarafından belirlenir; API veya panel üzerinden kendiniz artıramazsınız. Paket yükseltme veya ek kota için yöneticinizle iletişime geçin. Kota tüm hesaplarınız ve anahtarlarınız arasında paylaşılır; kalan hakkınızı /me ile izleyebilirsiniz.

Webhook var mı? Gelen mesajları alabilir miyim?

Şu an yok. API yalnızca giden mesajları destekler; gelen mesajlar, teslim ve okundu bildirimleri için webhook henüz sunulmuyor. Eklendiğinde Değişiklik Günlüğü'nde duyurulacaktır.

Toplu gönderim ucu var mı?

Hayır; her alıcı için ayrı istek gönderilir. Mesajları kuyruğa alıp aralarında 1–3 saniye bekleyerek sırayla gönderin. Hazır örnek: Toplu gönderim kuyruğu.

Birden fazla numaradan gönderim yapabilir miyim?

Evet. Her numarayı panelde ayrı bir hesap olarak bağlayın ve her hesap için ayrı anahtar oluşturun. Mesaj, isteği hangi anahtarla gönderirseniz o anahtarın bağlı olduğu numaradan gider. Kota tüm hesaplar arasında ortaktır.

Grup ID'sini nasıl bulurum?

GET /api/external/groups isteği, bağlı numaranın üye olduğu tüm grupları id değerleriyle döndürür. Grup ID'leri değişmez; bir kez alıp saklayabilirsiniz.

Mesajımdaki < ve > karakterleri neden kayboluyor?

Güvenlik nedeniyle message alanındaki < ve > karakterleri silinir. Yerine ≤, ≥ veya → gibi Unicode karakterleri kullanabilirsiniz.

404 "Endpoint bulunamadı" veya HTML yanıt alıyorum.

404 Endpoint bulunamadı: yanlış yol veya metot kullanıyorsunuz (ör. send-message için GET); yanıttaki path ve method alanlarını Endpoint özeti ile karşılaştırın. Gövdeniz geçerli JSON değilse 400 Geçersiz JSON gövdesi alırsınız. Tamamen HTML bir yanıt geliyorsa istek API'ye ulaşmadan önünüzdeki proxy/CDN tarafından yanıtlanıyor olabilir; adresin https://wp.inohype.com/api/… ile başladığını kontrol edin.

API'yi doğrudan tarayıcıdan (frontend) çağırabilir miyim?

Teknik olarak mümkündür (CORS açık), ancak yapmayın: anahtarınız sayfa kaynağında herkese görünür olur. Tarayıcıdan kendi sunucunuza istek atın; sunucunuz anahtarı ekleyerek Inohype WP'ye iletsin. Bkz. Güvenlik.

Destek

Değişiklik Günlüğü

API'de yapılan değişiklikler. Mevcut uçlar geriye dönük uyumlu kalır.

v1.1

Güncel
  • YeniGET /api/external/me: anahtar, hesap bağlantısı ve kota durumu (kota dolu olsa da çalışır).
  • YeniAnahtar başına dakikada 60 istek hız limiti ve RateLimit-* / Retry-After yanıt başlıkları.
  • YeniTutarlı hata yanıtları: bilinmeyen /api yolları JSON 404, bozuk JSON gövdesi 400, çok büyük gövde 413; harici uçlarda geçici WhatsApp hazır değil durumu 503.
  • DeğiştiÜrün adı Inohype WP olarak güncellendi; adres https://wp.inohype.com.
  • GüvenlikPanel girişinde iki adımlı doğrulama (2FA) desteği.

v1.0

İlk sürüm
  • YeniPOST /api/external/send-message: kişiye metin ve medya gönderimi.
  • YeniPOST /api/external/send-to-group: gruba metin ve medya gönderimi.
  • YeniGET /api/external/groups: grupları listeleme.