Özet: Whapi Agent Skill'i tek komutla kurmak, AI ajanlarının WhatsApp API'de en sık yaptığı üç hatayı önler: yanlış Chat ID'ler, yanlış auth header'ları ve webhook yerine polling. 7 referans kategorisini kodlar ve Cursor, Claude Code, Codex, GitHub Copilot ile 40'tan fazla diğer ajanla çalışır.
Kurulum: npx skills add Whapi-Cloud/whapi-whatsapp-api-skill · Node.js 18+ gerektirir · GitHub · Dokümantasyon
Agent Skill Nedir?
Cursor'dan veya Claude Code'dan bir WhatsApp botu kurmasını istediğinizde, ajan binlerce API'yi kapsayan eğitim verisine başvurur — bunların hiçbiri bugünkü haliyle Whapi.Cloud için özel olarak yetkili değildir. Sonuç: makul görünen ama üretimde sessizce başarısız olan kod.
Agent Skill bunun çözümüdür. Projenizin içinde duran ve ajan, ilgili bir görev algıladığında otomatik olarak bağlamına yüklenen yapılandırılmış bir bilgi dosyasıdır (SKILL.md). Onu sürekli talimatlar olarak düşünün: "Whapi.Cloud'un WhatsApp API'siyle geliştirirken tam olarak bu alan isimlerini, kimlik doğrulama desenlerini ve mimari kuralları kullan."
Standart 2025 sonlarında vercel-labs/skills aracılığıyla tanıtıldı ve bugün 40'tan fazla AI ajanı tarafından destekleniyor. Skill'leri tek bir npx skills add komutuyla kurarsınız. Yapılandırma dosyası yok, boilerplate yok — ajan otomatik olarak algılar.
MCP kiler, Agent Skill ise tarif. Whapi MCP sunucusu, ajanınıza WhatsApp API'yi çağırmak için 165 araç verir. Agent Skill ise hangi durumda hangi aracın çağrılacağını, hangi parametrelerin kullanılacağını ve hangi desenlerden kaçınılacağını öğretir. Birlikte, AI tarafından üretilen WhatsApp kodundaki en yaygın hata modlarını kapatırlar.
Sorun: AI Ajanlarının WhatsApp'ta Yanlış Yaptığı Şeyler
AI kod ajanları genel amaçlıdır. Spesifik grounding olmadan, doğru görünen ama runtime'da bozulan kod üretirler. Bu hataların hiçbiri derleme zamanında ortaya çıkmaz — yalnızca API 400 veya 401 döndürdüğünde görünür.
İşte en yaygın on hata ve Whapi Agent Skill'in neyi düzelttiği:
| AI'nin yazdığı (yanlış) | Whapi.Cloud'un gerektirdiği (doğru) | Etkisi |
|---|---|---|
[email protected] |
[email protected] |
Eski format — her gönderim 400 döndürür |
{"message": "hello"} |
{"body": "hello"} |
Yanlış alan adı — mesaj sessizce düşürülür |
{"chat_id": "..."} |
{"to": "..."} |
Gönderim araçları chat_id'yi değil to'yu kullanır |
X-API-Key: your_token |
Authorization: Bearer your_token |
Yanlış auth header — her istekte 401 |
API_KEY=your_token |
API_TOKEN=your_token |
Yanlış ortam değişkeni adı — MCP sunucusu asla yakalamaz |
Genel sendMessage() |
sendMessageText, sendMessageImage vb. |
Genel bir araç yok — 400 hatası |
Döngüde getMessages polling |
updateChannelSettings ile webhook |
5+ saniye gecikme, rate limit'i yakar, olayları kaçırır |
| Gelen tüm mesajlara cevap vermek | Cevaplamadan önce from_me: true'yu filtrele |
Bu filtre olmadan bot kendine döngü halinde cevap verir |
sendBulkMessages(recipients: [...]) |
Her alıcı için gecikmelerle bir kez sendMessageText |
Bu araç yok — halüsinasyonlu endpoint |
{"webhookUrl": "https://..."} |
{"webhooks": [{"url": "...", "mode": "body", ...}]} |
Webhook yapılandırması iç içe webhooks[] dizisini kullanmalı |
Agent Skill vs. MCP: İki Katman, Bir Stack
Eğer zaten Whapi MCP sunucusunu kullanıyorsanız, Agent Skill tek başına MCP'nin sağlamadığı bilgi katmanını ekler. Whapi.Cloud, her ikisini de sunan tek WhatsApp API sağlayıcısıdır.
| Agent Skill | MCP Sunucusu (whapi-mcp) | |
|---|---|---|
| Ne sağlar | Bilgi: API'nin nasıl doğru kullanılacağı | Yetenek: API'yi çağırmak için 165 araç |
| Kurulum yöntemi | npx skills add ... |
mcp.json'a giriş eklemek |
| Whapi hesabı gerekir mi? | Hayır — bağlam olarak yüklenir | Evet — geçerli bir API_TOKEN gerekir |
| API çağrısı yapar mı? | Hayır — yalnızca referans dosyası | Evet — canlı API çağrıları yürütür |
| Halüsinasyonu önler mi? | Evet — birincil amacı budur | Kısmen — araç şemaları yardımcı olur, desenler olmaz |
Whapi Agent Skill Neleri İçerir
Whapi Agent Skill, AI ajanınızın API'ye kuralları bilerek ulaşması için 7 referans kategorisini kodlar. Her referans dosyası doğru ve yanlış örnekler, halüsinasyon önleyici kontrol listeleri ve Whapi'ye özgü notlar içerir.
1. Temel Kavramlar (KRİTİK)
Chat ID formatı hataları, AI tarafından üretilen WhatsApp kodunda 400 hatalarının tek başına en yaygın kaynağıdır. Skill üç formatı kodlar:
- Kişisel sohbet:
{phone}@s.whatsapp.net— ör.[email protected] - Grup:
{id}@g.us—getGroupsaracılığıyla alın; ID'yi asla manuel olarak oluşturmayın - Kanal / Newsletter:
{id}@newsletter—getNewslettersaracılığıyla alın
Ayrıca MCP kurulumunu ve doğru API_TOKEN ortam değişkeni adıyla Authorization: Bearer {token} kimlik doğrulamasını kapsar.
2. Mesaj Gönderme (KRİTİK)
Ajanın her içerik türü için doğru aracı seçmesini sağlayan tam bir karar ağacı:
- Metin →
sendMessageText(alan:body) - JPG/PNG/WebP görsel →
sendMessageImage(alan:media) - MP4 video →
sendMessageVideo - GIF (MP4 dosyası) →
sendMessageGif - Dairesel video →
sendMessageShort - MP3/WAV ses dosyası →
sendMessageAudio - OGG Opus sesli not →
sendMessageVoice - Belge/PDF →
sendMessageDocument - WebP sticker →
sendMessageSticker - Anket →
sendMessagePoll - Etkileşimli butonlar/liste →
sendMessageInteractive - Konum →
sendMessageLocation
3. Mesaj Alma (KRİTİK)
Döngüde getMessages polling yapmak anti-desendir — WhatsApp mesaj alımı yalnızca webhook gerektirir. Skill, doğru iç içe webhook yapılandırma yapısını öğretir ve polling'in ölçekte neden başarısız olduğunu açıklar: 5+ saniye gecikme, sürekli rate limit tüketimi, yoklama aralıkları arasında kaçırılan olaylar.
4. Gruplar (YÜKSEK)
Grup oluşturma, katılımcı yönetimi, davet bağlantısı üretme, yönetici rolleri atama. Skill, createGroup, getGroups ve katılımcı yönetim araçları aracılığıyla tüm yaşam döngüsünü kapsar. Grup ID'leri @g.us formatını kullanır ve API üzerinden alınmalıdır.
5. Kanallar / Newsletter'lar (YÜKSEK)
WhatsApp Kanalları oluşturma, @newsletter Chat ID'si aracılığıyla mesaj gönderme, abone ve yöneticileri yönetme. Büyük WhatsApp kitleleri için Kanal, yayın döngüsünden daha güvenlidir — ban riski yok, mesaj başına zorunlu gecikme yok.
6. Topluluklar (ORTA)
Topluluklar oluşturma, grupları bağlama, özel Duyurular grubu aracılığıyla duyuru gönderme. Duyurular doğrudan alt gruplara değil, özellikle Duyurular grubu üzerinden gitmelidir.
7. Entegrasyon Desenleri (YÜKSEK)
Üretime hazır iki tarif:
- Bot deseni: Webhook yapılandır → mesaj al →
from_me: true'yu filtrele → cevapla. Echo botlar, anahtar kelime yanıtlayıcıları ve AI destekli asistanlar için çalışır. - Yayın deseni: Alıcı başına zorunlu gecikmelerle döngü, ısıtılmış numara gereksinimleri, kişiselleştirme kuralları ve
getLimitsüzerinden kota kontrolü.
Kullanım Senaryoları: Skill Bugün Nerede Yardımcı Olur
İşte Whapi Agent Skill'in ilk denemede doğru kod ürettiği beş somut iş akışı.
1. WhatsApp Müşteri Destek Botu
Cursor'dan bir destek botu oluşturmasını istersiniz. Skill olmadan Cursor bir polling döngüsü yazar ve @c.us Chat ID'leri kullanır. Skill ile bir webhook işleyicisi üretir, from_me'yi filtreler ve otomatik olarak @s.whatsapp.net kullanır. Her bot cevap işleyicisinde from_me: true'yu filtreleyin, aksi halde WhatsApp botunuz kendisine sonsuz döngüde mesaj atar.
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.json
if "messages" not in data:
return {"status": "ok"}
for message in data["messages"]:
if message.get("from_me"):
continue # prevent infinite loop
if message.get("type") != "text":
continue
chat_id = message["chat_id"] # e.g., "[email protected]"
text = message["text"]["body"] # correct field name: body
reply(chat_id, f"Got it: {text}")2. Web Formundan Lead Bildirimi
Yeni bir lead form gönderir. Ajanınız satış ekibine WhatsApp mesajı gönderir. Skill, ajanın halüsinasyonlu genel bir gönderim endpoint'i değil, body alanı ve doğru @s.whatsapp.net Chat ID'si ile sendMessageText kullanmasını garanti eder.
3. Grup Bildirim Sistemi
Bir WhatsApp grubuna güncelleme göndermek istersiniz. Skill, ajana grup ID'lerinin @g.us formatı kullandığını, ID'yi almak için getGroups'u çağırmanız gerektiğini (asla manuel oluşturmayın) ve to parametresinin tam Chat ID dizesini aldığını öğretir.
4. WhatsApp Kanal Yayını
Yüzlerce aboneye ulaşmanız gerekir. Skill, yayın döngüsünden önce Kanal yaklaşımını öne çıkarır — ban riski yok, mesaj başına zorunlu gecikme yok, aboneler kendileri abone olur. Büyük kitleler için doğru varsayılan budur.
5. Kontrollü Toplu Mesajlaşma
Bir listeye doğrudan mesajlama gerektiğinde: 15 dakikada en fazla 10 mesaj, gönderimler arası minimum 60–90 saniye, ısıtılmış numara zorunlu, alıcı başına kişiselleştirilmiş içerik. 60 saniyelik gecikmeler ve kişiselleştirme olmadan WhatsApp mesajı göndermek, anti-spam tespitini ve hesap askıya alınmasını tetikler. Kalan kotayı kontrol etmek için önce getLimits'i çağırın.
Kurulum: Tek Komut, Tüm Ajanlar
Whapi WhatsApp Agent Skill'i tek komutla kurun:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skillGereksinim: Node.js 18 veya üstü.
Belirli bir ajana yönlendirmek veya global kurmak için:
# Install for Cursor only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent cursor
# Install for Claude Code only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent claude-code
# Install globally (available in all projects)
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --globalKurulumdan sonra skill, ajanınız WhatsApp ile ilgili bir görev algıladığında otomatik olarak yüklenir. Kendisi aktifleşmezse:
- Cursor: Sohbette
@.agents/skills/whapi/AGENTS.md'ye referans verin veya/whapi'yi çalıştırın - Claude Code: Oturum başında
/file .agents/skills/whapi/AGENTS.md'yi çalıştırın veya/whapi'yi çalıştırın - GitHub Copilot: Sohbette
#.agents/skills/whapi/AGENTS.md'ye referans verin
MCP Sunucu Kurulumu (Cursor)
Ajanın canlı WhatsApp API çağrıları yapmasına izin vermek için Whapi MCP sunucusunu %USERPROFILE%\.cursor\mcp.json'a ekleyin:
{
"mcpServers": {
"whapi-mcp": {
"command": "npx",
"args": ["-y", "whapi-mcp@latest"],
"env": { "API_TOKEN": "YOUR_TOKEN" }
}
}
}Token'ınızı panel.whapi.cloud/dashboard'dan alın. Yapılandırmayı kaydettikten sonra Cursor'u yeniden başlatın ve (argümansız) checkHealth'i çağırın — bağlı bir kanal "status.text": "AUTH" döndürür.
Tam kurulum kılavuzu: support.whapi.cloud/help-desk/ai-tools/agent-skills
Henüz Kapsam Dışında Olanlar — ve Yoldaki Şeyler
Mevcut sürüm en yaygın iş akışlarına odaklanıyor. Bazı alanlar henüz skill'in referans dosyalarında yok:
- Etkileşimli mesajlar (
sendMessageInteractive): Belgelenmiş, ancak kararsız olarak işaretlenmiş — teslimat WhatsApp sürümleri arasında değişir. Aktif olarak izleniyor. - WhatsApp Durum / Story'ler: MCP'de mevcut (165 araç), henüz skill'in referans kategorilerinde belgelenmemiş.
- Commerce / Siparişler / Ürünler: WhatsApp katalog ve sipariş akışları API'de mevcut, ancak henüz skill'in desen kütüphanesinde değil.
- Gelişmiş medya yönetimi: Dosya kodlaması, boyut sınırları ve streaming ses etrafındaki uç durumlar henüz kapsanmıyor.
- WhatsApp Aramaları: Webhook üzerinden gelen arama tespiti listelenmiş; arama yönetim desenleri beklemede.
Agent Skill'ler, AI ajanlarının doğrudan doğru uygulamaya atlaması için yıllarca süren API deneme yanılmasını tek bir dosyaya kodlar. Whapi Agent Skill, belgelediğimiz her geliştirici iş akışıyla büyüyen yaşayan bir belgedir. Katkılar memnuniyetle karşılanır.
Whapi.Cloud ile Başlarken
Whapi Agent Skill ücretsiz ve açık kaynaktır. Onu canlı WhatsApp API ile kullanmak için bir Whapi.Cloud hesabına ihtiyacınız var — süresi olmayan ücretsiz bir sandbox mevcut, 5 aktif sohbet ve günde 150 mesaj kapsar. Meta onayı yok, şablon kısıtlaması yok.
- whapi.cloud'da ücretsiz hesap oluşturun
- QR kod aracılığıyla WhatsApp numaranızı eşleştirin
- Kanal token'ınızı dashboard'dan kopyalayın
- Çalıştırın:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill - Ajan yapılandırmanıza MCP sunucu girişini ekleyin
- Ajanınızdan isteyin: "WHAPI kullanarak bir WhatsApp mesajı gönder"
Ajan skill'i yükleyecek, checkHealth ile bağlantıyı doğrulayacak ve sizi doğru alan adları, Chat ID formatı ve auth header ile ilk gönderim boyunca yönlendirecektir. Skill kurulumundan teslimat onayına kadar ilk çalışan WhatsApp gönderiminiz on dakikadan az sürer.
GitHub: github.com/Whapi-Cloud/whapi-whatsapp-api-skill
Dokümantasyon: support.whapi.cloud/help-desk/ai-tools/agent-skills
MCP entegrasyonu: whapi.cloud/mcp-whatsapp-api
