Giriş yapınÜcretsiz denemeyi başlatın
easyCoexistence Resmi API'ler

Instagram mesaj webhook'u: DM payload'ı, echo'lar ve alanlar

Instagram'ın mesaj webhook alanı, profesyonel bir hesabın DM'lerini geldikleri anda iletir: metin, ekler, paylaşımlar, Story yanıtları, etiketlemeler, satır içi yanıtlar ve silmeler. Her olay, gönderenin Instagram'a özgü kapsamlı ID'si, alıcı, zaman damgası ve bir message nesnesi içeren bir messaging dizisinde yer alır; hesabın kendi gönderdiği mesajlar da aynı alanda, is_echo değeri true olarak geri gelir.

easyCoexistence, bağlı her Instagram hesabını messages alanına abone eder ve DM'lerini, echo'lar dahil, geldikleri anda HTTPS uç noktanıza iletir; hesabın gizli anahtarıyla imzalanır; iletme bir kopya tutmaz ve DM'ler varsayılan olarak saklanmaz.

is_echo

Hesabın kendi gönderdiği bir mesaj olayında true olarak ayarlanır.

24 hours

Kullanıcı eylemlerinin çoğu için standart mesajlaşma penceresi; bu süre içinde uygulama kişiye yanıt verebilir.

ig_post

Paylaşılan bir gönderinin ek türü; eski paylaşım türü yalnızca 1 Şubat 2026'ya kadar desteklendi.

story_mention

Biri hesabı Story'sinde etiketlediğinde Meta'nın gönderdiği DM olayının ek türü.

2534041

Hesap sahibi Instagram doğrudan mesajlarına erişimi kapattığında, 200 kodu altındaki hata alt kodu.

Messages alanı ne zaman tetiklenir?

Biri profesyonel hesaba DM gönderdiğinde ve hesap bir DM gönderdiğinde. Meta'nın örnekleri ve referansları bu durumları listeler; her biri message nesnesi içeren bir messaging olayıdır:

  • Metin ve ek olarak medya: resimler, videolar, sesler ve dosyalar.
  • ig_post, ig_reel veya reel eki olarak paylaşılan bir gönderi ya da Reel.
  • reply_to.story ile hesabın Story'sine yanıt ve story_mention eki olarak hesabı etiketleyen bir Story.
  • reply_to.mid ile önceki bir mesaja satır içi yanıt ve quick_reply.payload ile hızlı yanıt.
  • Kişinin sildiği mesaj (is_deleted), desteklenmeyen medya (is_unsupported) ve Click-to-Direct reklamına tıklayan birinden gelen mesaj (referral).
  • Hesabın gönderdiği ve is_echo değeri true olarak geri gelen mesaj.

Messages bildirimi nasıl görünür?

object değeri instagram olan bir JSON içeren bir POST. Yorumdan farklı olarak mesaj, hesabın entry öğesi içindeki bir messaging dizisinde yer alır ve her öğe sender, recipient, timestamp ve message taşır. Hesabın Story'sine verilen bir yanıt şöyle görünür:

A messages notification, as Meta sends it
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<MESSAGE_TEXT>",
            "reply_to": {
              "story": {
                "url": "<CDN_URL_FOR_THE_STORY>",
                "id": "<STORY_ID>"
              }
            }
          }
        }
      ]
    }
  ]
}

Her alan ne anlama gelir?

Meta'nın Instagram Login altında bir mesaj olayı için belgelediği alanlar, dıştan içe doğru:

  • entry[].id: profesyonel hesabın ID'si. entry[].time: Meta'nın bildirimi gönderdiği zaman; Meta'nın mesajlaşma örnekleri bunu milisaniye cinsinden verir.
  • sender.id ve recipient.id: gelen bir DM'de kişinin Instagram'a özgü ID'si ve hesabın ID'si; echo'da ise bu ikisi ters yönde.
  • timestamp: mesajın gönderildiği zaman; Meta'nın örneklerinde milisaniye cinsinden. Mesajları varış sırasına göre değil, buna göre sıralayın.
  • message.mid: mesaj ID'si; tekilleştirme, tepki verme ve reply_to.mid ile bu mesaja yanıt verme için.
  • message.text: mesaj metin içerdiğinde eklenir.
  • message.attachments[]: her biri bir type ve bir payload ile, genellikle bir url içerir. Paylaşılan bir gönderinin ig_post payload'ı, açıklama olan title ve ig_post_media_id ekler.
  • message.reply_to: satır içi yanıt için mid, Story yanıtı için ise Story'nin url ve id değerleriyle birlikte story.
  • message.quick_reply.payload ve message.referral: seçilen hızlı yanıt ve Click-to-Direct reklamının ref, ad_id, source, type ve ads_context_data değerleri.
  • message.is_deleted, is_echo, is_self ve is_unsupported: yalnızca true olduklarında eklenir.
  • message.admin_text ve handoff_reason: uygun uygulamalarda, Meta Business Agent gibi bir Meta uygulamasının konuşmayı devrettiğine dair bildirim; mid veya text olmadan da gelebilir.

Echo'lar nasıl çalışır?

Hesap bir mesaj gönderdiğinde, Meta bunun için de is_echo değeri true olan bir messages olayı gönderir. Bu durumda sender.id hesap, recipient.id ise kişinin Instagram'a özgü ID'sidir; hesabın kendisine gönderdiği bir test mesajı ayrıca is_self taşır. Echo'lar, bir konuşma kaydının ihtiyaç duyduğu hesabın ne söylediğini kaydeder; ancak yanıt verip vermeyeceğine karar veren bir işleyicinin bunları atlaması gerekir. Hesap bir mesaja tepki verdiğinde ya da tepkiyi kaldırdığında Meta echo göndermez.

An echo of a message the account sent
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448061203,
      "messaging": [
        {
          "sender": { "id": "<IG_ID>" },
          "recipient": { "id": "<IGSID>" },
          "timestamp": 1793448060950,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<REPLY_TEXT>",
            "is_echo": true
          }
        }
      ]
    }
  ]
}

Hangi ID'ye yanıt verirsiniz?

sender.id, kişinin Instagram'a özgü ID'si. Biri hesaba mesaj gönderdiğinde ya da medyasına yorum yaptığında Meta bunu oluşturur ve bu ID o kişiye ve o hesaba özgüdür. recipient.id bu değere ayarlanmış POST /<IG_ID>/messages yanıtı gönderir. Olay ad veya kullanıcı adı taşımaz; name ve username gibi alanlarla GET /<IGSID> bunları döndürür, çünkü hesaba mesaj göndermiş bir kişi bu sorgunun gerektirdiği onayı vermiştir.

Bir mesaj 24 saatlik pencereyi nasıl açar?

Bir uygulama, ancak kişi hesaba mesaj gönderdikten sonra ve yalnızca eylemlerinin açtığı standart mesajlaşma penceresi içinde kişiye mesaj gönderebilir. Çoğu eylem için bu süre 24 saattir; Click-to-Direct reklamına tıkladıktan sonra gönderilen ilk mesajdan itibaren ise 7 güne kadar uzayabilir. Kişiden gelen yeni bir mesaj yeni bir pencere açar, bu yüzden takip edilmesi gereken zaman damgası en son olanıdır; echo ise hesabın kendi mesajıdır ve hiçbir pencereyi uzatmaz. Kişilerin yazdığı yanıtlar, human_agent etiketiyle, Meta'nın ayrı 7 günlük Human Agent penceresini kullanabilir.

Bir messages olayı neleri taşımaz?

Meta'nın mesajlaşma referanslarına göre, bir işleyicinin aramış olabileceği bazı şeyler eksiktir:

  • Kişinin adı veya kullanıcı adı: yalnızca Instagram'a özgü ID vardır; bunu GET /<IGSID> çözümler.
  • Tek seferlik görüntülenen medya: URL'si olmayan geçici bir ek olarak gelir.
  • Tam karusel görseli: karusel gönderideki tek bir görsele verilen bir tepki ya da iletme, ilk görseli bildirir.
  • Tepkiler, düzenlemeler ve okundu bilgileri: kendi alanlarında gelirler.
  • Okundu işareti: webhook ile iletilen bir mesaj, bir yanıt gönderilene kadar Instagram gelen kutusunda okunmamış kalır.

Meta hangi diğer mesajlaşma alanlarını listeler?

Meta'nın Instagram Login için alan listesi ve örnekleri, messages dışında bunları da adlandırır; her biri kendi messaging olayıdır. easyCoexistence her hesabı yalnızca messages, comments ve mentions alanlarına abone eder, bu yüzden bunların hiçbiri ilettiği şeyin parçası değildir:

  • message_reactions: kişi bir mesaja tepki verir ya da tepkiyi kaldırır; reaction.mid, action değeri react veya unreact ve reaction ile emoji.
  • message_edit: kişi bir mesajı düzenler; message_edit.mid, yeni metin ve num_edit ile.
  • messaging_postbacks: kişi bir buz kırıcıya ya da şablon düğmesine dokunur; postback.mid, title ve payload ile.
  • messaging_referral: zaten bir konuşmada olan kişi ref parametreli bir ig.me bağlantısını açar.
  • messaging_seen: kişi bir mesajı okur; read.mid ile.
  • messaging_optins, messaging_handover ve standby: sonuncu ikisi, Meta'nın devir protokolü altında bir konuşmayı paylaşan uygulamalar içindir.

Hesap neyi açmalı?

Mesajlara erişime izin verin. Meta, mesajları API üzerinden yönetilebilmeden önce profesyonel bir hesabın bunu açmasını şart koşar: Instagram uygulamasında Ayarlar, Mesajlar ve hikaye yanıtları, Mesaj denetimleri, Bağlı araçlar yolunda. Kapalıyken gönderimler 200 kodu, 2534041 alt koduyla başarısız olur. Uygulamanın ayrıca instagram_business_basic ve instagram_business_manage_messages izinlerine ve sahip olmadığı ya da yönetmediği hesaplara hizmet vermek için Advanced Access'e ihtiyacı vardır.

easyCoexistence bir DM'yi nasıl iletir?

Yorum gibi: Meta'nın hesap için ilettiği her entry, platform, account_id, external_id ve entry alanlarından oluşan bir zarf içinde HTTPS uç noktanıza POST edilir; X-EC-Signature içinde hesabın gizli anahtarıyla imzalanır, bir kez gönderilir ve hiçbir kopya tutulmaz. Echo'lar diğerleriyle birlikte iletilir, bu yüzden yanıt vermeden önce is_echo değerini kontrol edin. Yanıt vermek için send_social_dm'i account_id ve olayın sender.id değeriyle recipient_id olarak çağırın; 24 saatlik pencere içinde. Bir DM ile başlayan otomasyonlar aynı olaylar üzerinde çalışır.

A forwarded DM with an image
{
  "platform": "instagram",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<IG_ID>",
  "entry": {
    "id": "<IG_ID>",
    "time": 1793448000512,
    "messaging": [
      {
        "sender": { "id": "<IGSID>" },
        "recipient": { "id": "<IG_ID>" },
        "timestamp": 1793447999874,
        "message": {
          "mid": "<MESSAGE_ID>",
          "attachments": [
            { "type": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
          ]
        }
      }
    ]
  }
}

Yaygın hatalar

  • Echo'lara yanıt vermek. is_echo değeri ayarlı bir olay, hesabın kendi mesajıdır ve buna yanıt vermek hesabı kendisiyle bir döngüye sokar.
  • Bir mesajın her zaman metni olduğunu varsaymak. Ekler, paylaşımlar, Story etiketlemeleri ve silmeler bir text alanı olmadan gelir; bu yüzden message nesnesinin ne içerdiğine göre dallanın.
  • Mesajları varış sırasına göre sıralamak. Meta, bir hatadan sonra mesajları sırasız iletebilir; bu yüzden zaman damgasına göre sıralayın.
  • time ve timestamp değerlerini saniye olarak ayrıştırmak. Meta'nın mesajlaşma örnekleri ikisini de milisaniye cinsinden verir; saniye olarak okununca çok uzak gelecekteki tarihler olurlar.
Bunu EasyCoexistence'la yapmak

send_social_dm, yanıtı 24 saatlik pencere içinde gönderir; otomasyonlar sabit bir metin ya da yapay zekâ ile kendiliğinden yanıt verebilir. Bağlantı başına ayda US$ 9'dan başlar, bağlantı ekledikçe US$ 0.75'e kadar düşer. İlk 3 gün ücretsiz deneme.

Sık sorulan sorular

Instagram mesaj webhook'larındaki zaman damgaları saniye mi, milisaniye mi?

Meta'nın mesajlaşma örneklerinde, hem timestamp hem entry time için milisaniye. Saniye olarak okunursa çok uzak gelecekteki tarihler olurlar.

Instagram DM webhook'undan gönderenin kullanıcı adını nasıl alırım?

GET /<IGSID> çağrısını name ve username gibi alanlarla yapın. Olay yalnızca kişinin Instagram'a özgü ID'sini taşır.

Instagram DM webhook'ları neden gelmiyor?

Hesabın Mesajlara erişime izin ver seçeneğini açtığını, /subscribed_apps üzerinden messages alanına abone olduğunu ve uygulamanın sahip olmadığı hesaplar için Advanced Access ile Live durumunda olduğunu kontrol edin.

easyCoexistence Instagram mesaj tepkilerini iletiyor mu?

Hayır. Tepkiler message_reactions alanında gelir; easyCoexistence hesapları yalnızca messages, comments ve mentions alanlarına abone eder.

Okumaya devam edin

İlk kanalınızı iki dakikada bağlayın.

Beklemeniz gereken platform incelemesi yok. WhatsApp, Instagram, TikTok veya başka bir kanalı bağlayın, ardından yapay zekânızdan paylaşım yapmasını, yanıtlamasını ya da rapor vermesini isteyin ve işini izleyin.

  • 3 gün ücretsiz
  • İstediğiniz zaman iptal
  • Yalnızca resmi API'ler
  • 7/24 izleniyor

Doğrulama tarihi