BroadRouter

Arapça WhatsApp sohbet botu mimarisi: sesli mesajdan yanıta

BroadNet Inference ekibi · 5 dk okuma · Yayımlandı · Güncellendi

Arapça bir WhatsApp asistanının beş parçası var: WhatsApp Business Platform'dan mesaj alan bir webhook, bir kuyruk, sesli mesajlar için konuşmadan metne, yanıtı taslak hâline getiren bir LLM ve API üzerinden yanıt veren bir gönderici. Bir sesli mesajı dönüştürüp BroadNet Transcribe Arabic ile yazıya dökmek ses dakikası başına $0.0042 tutar.

Arapça bir WhatsApp sohbet botunun beş parçaya ihtiyacı var: resmî WhatsApp Business Platform’dan mesaj alan bir webhook, bir kuyruk, sesli mesajlar için konuşmadan metne, Arapça yanıt taslakları yazan bir LLM ve WhatsApp’ın 24 saatlik penceresi içinde yanıt veren bir gönderici. Sesli mesajlar önemli, çünkü Arapça konuşan birçok müşteri yazmak yerine lehçeyle konuşuyor.

BroadRouter’ı BroadNet işletiyor, bu yüzden örneklerde BroadNet Inference kullanılıyor. OpenAI uyumlu herhangi bir konuşmadan metne ve sohbet sağlayıcısı aynı yerlere oturur.

Arapça bir WhatsApp sohbet botunun parçaları neler?

WhatsApp user
   │  text or voice note
   ▼
WhatsApp Business Platform (Cloud API)
   │  webhook POST
   ▼
1. Webhook receiver ── verify signature, store event, return 200
   │
   ▼
2. Queue (Redis, SQS, a database table)
   │
   ▼
3. Worker
   ├─ voice note? download media → ffmpeg → speech to text
   ├─ build prompt: system rules + recent history + new message
   └─ LLM drafts reply (or hands over to a human)
   │
   ▼
4. Sender ── POST /messages on the Cloud API
   │
   ▼
5. Store ── conversation state, opt-in status, audit log

1. Webhook alıcısı

WhatsApp Cloud API gelen mesajları, kaydettiğiniz bir webhook’a HTTPS POST istekleri olarak iletir. İki kural bu parçayı sağlıklı tutar:

  • Her isteği doğrulayın. Meta’nın belgeleri, JSON yükünün uygulama gizli anahtarınızla HMAC-SHA256 değerini hesaplamanızı ve X-Hub-Signature-256 başlığıyla karşılaştırmanızı söylüyor. Eşleşmeyen her şeyi reddedin.
  • 200’ü hızlı döndürün. Olayı saklayın ve onaylayın. Webhook işleyicisinin içinde ses indirmeyin ya da LLM çağırmayın. Teslimat başarısız olursa Meta “immediately, then a few more times with decreasing frequency over the next 7 days” (BroadRouter çevirisi: hemen, sonra sonraki 7 gün boyunca azalan sıklıkla birkaç kez daha) yeniden dener ve tekilleştirmeyi sizin yapmanızı ister.

WhatsApp mesaj kimliğini bir idempotency anahtarı olarak kullanın; böylece yeniden teslim edilen bir webhook asla iki yanıt üretmez.

2. Kuyruk

Kuyruk, WhatsApp’ın teslimat zamanlamasını sizin işleme sürenizden ayırır. Ayrıca eşzamanlılığı çıkarım limitlerinize göre sınırlamanızı sağlar. Bir BroadNet kullandıkça öde anahtarı dakikada 30 isteğe ve aynı anda 4 isteğe izin verir; bu yüzden 429’da yeniden deneyen küçük bir işçi havuzu doğru yapıdır. Bkz. hatalar ve yeniden denemeler ve 429 hız sınırlarıyla nasıl başa çıkılır.

3. İşçi: sesli mesajdan metne

Bir sesli mesaj için webhook size medya id’si, audio/ogg; codecs=opus gibi bir mime_type ve WhatsApp’ta yapılmış kayıtlar için voice: true içeren bir audio nesnesi verir. İşçi indirme URL’sini almak için medya kimliğine GET isteği atar, dosyayı erişim token’ınızla indirir, sonra dönüştürüp yazıya döker. BroadNet’in uç noktası WAV ya da MP3 kabul eder, bu yüzden önce dönüştürün:

import os, subprocess, tempfile
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

def transcribe_voice_note(ogg_bytes: bytes) -> str:
    with tempfile.TemporaryDirectory() as d:
        src, wav = os.path.join(d, "in.ogg"), os.path.join(d, "in.wav")
        open(src, "wb").write(ogg_bytes)
        subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-i", src,
                        "-ar", "16000", "-ac", "1", wav], check=True)
        with open(wav, "rb") as audio:
            return client.audio.transcriptions.create(
                model="broadnet/cohere-transcribe-arabic",
                file=audio,
                language="ar",   # without it, Arabic can come back in Latin letters
            ).text

Geçici dizin çağrıdan sonra silinir; bu da sesi disklerinizden uzak tutar. WhatsApp sesli mesaj rehberinde dışa aktarılmış sohbetler için toplu bir sürüm var; Arapça konuşmadan metne rehberi biçimleri ve sınırları ele alıyor. Dosyalar 26.214.400 baytın (25 MiB) altında kalmalı; sıradan sesli mesajlar bunun çok altındadır.

3b. İşçi: yanıt taslağı

Bir transkripte tam olarak yazılmış bir mesaj gibi davranın, ama modele konuşmadan geldiğini söyleyin; çünkü transkriptlerde noktalama yoktur ve tanıma hataları içerebilir:

SYSTEM = """You are the WhatsApp assistant of a clinic in Dubai.
Customers write or speak in Gulf Arabic, other dialects, MSA, English or Arabizi.
Reply in simple Modern Standard Arabic unless the customer used English.
Keep replies under 60 words. Plain text only: no links, no markdown.
You can: answer opening hours, explain how to book, collect name and preferred time.
If the message is a complaint, medical question or you are unsure, reply that a
staff member will follow up, and set handover=true."""

def draft_reply(history: list[dict], text: str, from_voice: bool) -> str:
    note = "(transcribed voice note, may contain errors) " if from_voice else ""
    r = client.chat.completions.create(
        model="broadnet/qwen3.8-27b",
        max_tokens=1500,
        messages=[{"role": "system", "content": SYSTEM}, *history[-10:],
                  {"role": "user", "content": note + text}],
    )
    return r.choices[0].message.content

Yönlendirme için modelden serbest metin yerine yapılandırılmış çıktı (intent, handover, reply) isteyin ve alanlara göre hareket edin; ücretsiz JSON şema oluşturucu şemayı örnek bir yanıttan yazar. BroadNet’in testlerinde Qwen3.8 27B Körfez ve Mısır lehçelerini anladı ve akıcı Arapça yazdı; DeepSeek V4.1 Flash token başına daha ucuz ve BroadNet’in sınırsız planlarındaki model. İkisi de yanıt vermeden önce akıl yürütür, bu yüzden max_tokens içinde yer bırakın. Lehçeyle başa çıkma LLM’lerle Körfez, Mısır ve Levant Arapçası yazısında ayrıntılı olarak ele alınıyor.

4. Gönderici

Yanıtlar, telefon numarası kimliğiniz için Cloud API’nin mesajlar uç noktası üzerinden gider. Sohbet yanıtları için düz metin gönderin. WhatsApp biçimlendirmesi (kalın, listeler) görüntülenir, ama Markdown tabloları ve başlıkları görüntülenmez; bu yüzden modele bunları üretmemesini söyleyin.

5. Depolama

Sohbet durumunu (çoğu destek botu için son on tur fazlasıyla yeter), müşterinin izin durumunu ve botun ne gönderdiğini ve nedenini kaydeden bir denetim günlüğünü tutun. İhtiyacınızdan fazlasını saklamayın: sesli mesaj transkriptleri çoğu zaman adlar, adresler ve sağlık ayrıntıları içerir.

Bir sohbet botu için hangi WhatsApp politika kuralları geçerli?

WhatsApp, işletmelerin onu nasıl kullandığı konusunda katıdır ve kurallar müşterilerinizi olduğu kadar numaranızı da korur. Yayına almadan önce WhatsApp Business Messaging Policy’yi okuyun. Pratikte:

  1. Önce izin. Politika, yalnızca numarasını size vermiş ve WhatsApp’ta sizden haber almayı kabul etmiş kişilerle iletişim kurmanıza izin verir. Bir müşterinin size yazması pazarlamaya onay değildir.
  2. İstenmeyen mesaj yok. Politika şöyle diyor: “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.” (BroadRouter çevirisi: İletişimlerinizle insanların kafasını karıştırmayın, onları aldatmayın, dolandırmayın, yanıltmayın, spam göndermeyin ya da şaşırtmayın.) Sizinle iletişime geçmemiş ya da izin vermemiş kişilere asla ilk mesajı göndermeyin.
  3. 24 saatlik müşteri hizmetleri penceresine uyun. Müşterinin son mesajından sonraki 24 saat içinde serbest biçimli yanıtlara izin verilir. Bunun dışında yalnızca onaylı mesaj şablonları gönderebilirsiniz.
  4. Bir insan sunun. 24 saatlik pencere içinde otomatik yanıtlara izin verilir, ama politika bir kişiye giden “prompt, clear, and direct escalation paths” (BroadRouter çevirisi: hızlı, açık ve doğrudan yükseltme yolları) ister.
  5. İzin geri çekmelere uyun. Politika, engelleme, durdurma ya da abonelikten çıkma yönündeki her talebe uymanız gerektiğini söylüyor. “stop” ya da “توقف” mesajını böyle bir talep sayın.

Bir kural daha var; bu Meta’nın değil, bizim kuralımız: yeni kişilere ilk yanıtları sade tutun. URL içermeyen kısa, düz metin bir yanıt en güvenlisidir. Tanımadıkları bir işletmeden gelen bağlantı dolu mesajlar kullanıcılara spam gibi görünür; sizi engelleyip şikâyet edebilirler. Bağlantıları daha sonra, müşteri istediğinde paylaşın.

Arapça bir WhatsApp botunu çalıştırmanın maliyeti ne?

Konuşmadan metne ses dakikası başına faturalanır. BroadNet Transcribe Arabic ile:

Hacim Maliyet
Bir dakikalık sesli mesaj $0.0042
Bir saatlik sesli mesaj $0.25
30 saniyelik 10.000 sesli mesaj $21.00

LLM yanıtları kullandıkça öde modelinde token başına faturalanır: 1M token başına Qwen3.8 27B girdi için $0.175, çıktı için $2.17; DeepSeek V4.1 Flash girdi için $0.175, çıktı için $0.52. On turluk geçmişi olan bir destek yanıtı akıl yürütme dahil birkaç bin token’dır; bu yüzden tek bir yanıt, yukarıdaki 1M token fiyatlarının binde birkaçı kadar tutar. Aylık bir rakam için mesaj hacminizi ücretsiz LLM API maliyet hesaplayıcısına girin. Bot bütün gün DeepSeek V4.1 Flash üzerinde çalışıyorsa, fiyatlar sayfasındaki ayda $60 tutan Full Moon planıyla karşılaştırın.

Sesli mesajları nasıl gizli tutarsınız?

Sesli mesajlar, bir işletmenin işlediği en kişisel verilerden biridir. BroadNet Inference ses, istem ve transkriptleri istekten sonra saklamaz (bkz. sıfır veri saklama), ama bu yalnızca çıkarım adımını kapsar. Kendi kuyruğunuzun, günlüklerinizin ve veritabanınızın transkriptleri ne kadar tutacağına karar verin ve medya dosyalarını işledikten sonra silin.

Yayına alma kontrol listesi

  • Webhook imzası doğrulanıyor, işlemeden önce 200 döndürülüyor.
  • WhatsApp mesaj kimliği üzerinde idempotency.
  • Sesli mesajlar WAV’a dönüştürülüp language=ar ile yazıya dökülüyor.
  • İşçi havuzu hız sınırlarınıza göre boyutlandırılmış, 429’da geri çekilme var.
  • Sistem istemi lehçeyi, dil düzeyini, uzunluğu ve “bağlantı yok” kuralını belirliyor.
  • Bir insana devretme yolu var ve test edildi.
  • İzin kaydediliyor; istenmeyen gönderim yok; 24 saatlik pencere dışında yalnızca şablonlar.
  • Transkriptler bir takvime göre siliniyor.

Yanıt veren bir bot yerine yalnızca sesli mesajların taleplere dönüştürülmesi gerekiyorsa, işletmeler için sesli mesajı metne çevirme bu daha basit hattı anlatıyor.

Sık sorulan sorular

Bana hiç yazmamış müşterilere mesaj atabilir miyim?

Yalnızca işletmenizden haber almayı kabul ettilerse ve yalnızca onaylı mesaj şablonlarıyla. İstenmeyen mesajlar WhatsApp politikalarını ihlal eder ve numaranızın kısıtlanmasına yol açabilir.

Sesli mesajları yazıya dökmeden önce neden dönüştürmeliyim?

WhatsApp sesli mesajları Ogg/Opus dosyalarıdır, BroadNet'in transkripsiyon uç noktası ise WAV ya da MP3 kabul eder. Tek bir ffmpeg komutu bunları 16 kHz mono WAV'a dönüştürür.

Yanıtları hangi LLM yazmalı?

Kendi mesajlarınızda test edin. BroadNet, testlerinde Qwen3.8 27B'nin Körfez ve Mısır lehçelerini anladığını ve akıcı Arapça yazdığını bildiriyor; DeepSeek V4.1 Flash token başına daha ucuz ve sabit ücretli planlarda kullanılabiliyor.

Bir WhatsApp botu şablon olmadan ne kadar süre yanıt verebilir?

Müşterinin son mesajından sonraki 24 saatlik müşteri hizmetleri penceresi içinde serbest biçimli yanıtlar gönderebilirsiniz. Bu pencerenin dışında WhatsApp Business Messaging Policy yalnızca onaylı mesaj şablonlarına izin verir.

WhatsApp sohbet botlarının insana devretmesi gerekir mi?

Evet. Politika otomasyona izin verir, ama sohbette bir insan temsilciye aktarma, telefon numarası, e-posta ya da destek formu gibi hızlı, açık ve doğrudan yükseltme yolları ister.

BroadNet sesli mesajları saklıyor mu?

Hayır. BroadNet Inference ses ve transkriptleri istek için işler ve saklamaz. Kendi sunucularınızda ve WhatsApp'ta yine kopyalar bulunur; oralardaki saklamayı da planlayın.

Markdown olarak okuChatGPT asistanına sorClaude asistanına sorPerplexity asistanına sor