PushizoDocs

Telegram ve Viber: bot mesajlaşması, derin bağlantıyla abonelik ve gelen kutusu

Telegram ve Viber kanalları işletmenizin botu üzerinden metin, görsel ve düğmeli mesaj gönderir; kişilerin yanıtları Gelen kutusuna düşer (ADR-0086). İki kanal da telefon numarasıyla değil bot kimliğiyle çalışır: kişi…

Telegram ve Viber kanalları işletmenizin botu üzerinden metin, görsel ve düğmeli mesaj gönderir; kişilerin yanıtları Gelen kutusuna düşer (docs/adr/0086-telegram-viber.md). İki kanal da telefon numarasıyla değil bot kimliğiyle çalışır: kişi bota yazmadan mesaj gönderilemez. Bu yüzden abonelik, kişiye özel bir derin bağlantı ile kullanıcınıza bağlanır. Kanallar plan özelliği olarak messengers (Starter ve üzeri) gerektirir.

1. Kurulum

SağlayıcıGerekenlerNotlar
telegram_bot@BotFather'dan bot belirteciDoğrulamada bot kullanıcı adı okunur (telegram_bot_username)
viber_botViber Admin Panel kimlik belirteci, gönderici adı (≤28), isteğe bağlı https avatarDoğrulamada bot URI'si okunur (viber_uri)
mock—Gerçek gönderim yok; sonuç sohbet/kullanıcı kimliğinin son dört hanesine göre (0001 geçersiz, 0002 kalıcı hata, 0003 geçici, 0004 hız sınırı)
PUT /internal/v1/apps/{appId}/channels/telegram
{ "provider": "telegram_bot", "bot_token": "123456789:AA…" }

PUT /internal/v1/apps/{appId}/channels/viber
{ "provider": "viber_bot", "auth_token": "4453b6ac…", "sender_name": "Markam", "sender_avatar": "https://cdn.markam.com/logo.png" }

Belirteçler zarf şifreli saklanır; yanıtta ve loglarda yer almaz. Kayıttan sonra kanal otomatik doğrulanır. Ardından webhook'u sağlayıcıya tek çağrıyla kaydedin (panelde kanal kartındaki Webhook'u kaydet düğmesi):

POST /internal/v1/apps/{appId}/channels/telegram/hook/register

Telegram setWebhook (gizli secret_token ile), Viber set_webhook çağrılır. Webhook adresi API_URL tabanlıdır ve https olmalıdır. Elle kurulum için adres ve Telegram gizli belirteci GET …/channels/telegram/hook ile alınır (görüntüleme denetim kaydına yazılır).

2. Aboneyi bağlama (derin bağlantı)

Sunucunuz kullanıcı için tek kullanımlık bir bağlantı üretir ve bunu uygulamanızda veya e-postada gösterir:

POST /v1/apps/{appId}/messenger-links
Authorization: Bearer <users:write anahtarı>
{ "channel": "telegram", "external_id": "musteri-42", "ttl_seconds": 86400 }

201 { "url": "https://t.me/markam_bot?start=Qm9…", "token": "Qm9…", "user_id": "usr_…", "expires_at": "…" }
  • Telegram bağlantısı https://t.me/<bot>?start=<belirteç>, Viber bağlantısı viber://pa?chatURI=<uri>&context=<belirteç> biçimindedir.
  • Kişi bağlantıyı açıp botu başlattığında sohbet kimliği bu kullanıcıya abonelik olarak bağlanır (opt_in_source = deep_link). Belirteç bir kez kullanılır, süresi dolar (varsayılan 7 gün, en çok 30 gün) ve veritabanında yalnızca özeti tutulur.
  • Geçersiz veya kullanılmış belirteçle başlatan kişinin aboneliği yine oluşur ama kullanıcıya bağlanmaz.
  • Viber'de kişi sohbeti açtığında henüz abone olmayabilir: bağlantı kaydedilir, abonelik "bekliyor" kalır ve kişi abone olunca ya da bota yazınca etkinleşir.
  • Kişi botu engellerse (Telegram) veya abonelikten çıkarsa (Viber) abonelik kapanır; STOP/BAŞLA anahtar sözcükleri de çalışır. SDK bu kanallarda abonelik kaydedemez; sohbet kimliği yalnızca bot üzerinden bağlanır.

3. İçerik

AlanAçıklama
contentsDüz metin (Telegram ≤4096, Viber ≤7000 karakter); Liquid ile kişiselleştirilir
messenger_image_urlGörsel (https); metin açıklama olur (Telegram ≤1024, Viber ≤768)
messenger_buttonsEn fazla 6 düğme: { "type": "url", "text", "url" } veya { "type": "reply", "text", "payload" }
{
  "app_id": "app_…",
  "contents": { "tr": "Merhaba {{ user.properties.first_name }}, siparişiniz yolda." },
  "messenger_image_url": "https://cdn.markam.com/kargo.png",
  "messenger_buttons": [
    { "type": "url", "text": "Siparişi izle", "url": "https://markam.com/siparis" },
    { "type": "reply", "text": "Destek", "payload": "destek" }
  ],
  "target": { "include_aliases": { "external_id": ["musteri-42"] }, "channels": ["telegram", "viber"] }
}

Telegram'da metin biçimlendirmesiz gönderilir. Bağlantı düğmeleri izlenen kısa linke çevrilir; tıklama teslim raporuna yazılır. Yanıt düğmesine basan kişinin seçimi gelen kutusunda kişinin mesajı olarak görünür. Panelde içerik editöründeki Telegram/Viber sekmesi iki kanal için ortaktır.

4. Teslim ve okundu

  • Telegram: Bot API ayrı teslim bildirimi vermez; Telegram mesajı kabul ettiğinde teslimat delivered olur. Bot engellenmişse veya sohbet bulunamazsa abonelik geçersiz işaretlenir.
  • Viber: delivered ve seen geri çağrıları teslim ve açılma (okundu) olarak işlenir; failed teslimatı başarısız yapar. Kişi kayıtlı değilse veya abone değilse abonelik geçersiz işaretlenir.

5. Gelen kutusu ve AI ajanı

Kişinin metin mesajı, düğme seçimi ve gönderdiği medya (sağlayıcı kimliğiyle) gelen kutusunda Telegram veya Viber konuşması olarak görünür. Gelen kutusundan yanıt metin olarak gider. Anahtar sözcüklerin kanallarına telegram ve viber eklenebilir; konuşmalı AI ajanı (AI ajanı) bu kanalları da üstlenebilir.

6. Güvenlik

  • Telegram webhook istekleri X-Telegram-Bot-Api-Secret-Token başlığıyla, Viber istekleri X-Viber-Content-Signature (kimlik belirteciyle HMAC-SHA256) ile doğrulanır; eşleşmeyen istek 401 alır.
  • Webhook adresindeki belirteç kanala ve sağlayıcıya bağlıdır; yanlış kanal yolunda 404 döner.
  • Derin bağlantı belirteci app'e özeldir: başka app'in botunda kullanılamaz.

Bu sayfada