Webhook pesan Instagram: payload DM, echo, dan field
Field webhook pesan Instagram mengirimkan DM akun profesional saat tiba: teks, lampiran, postingan yang dibagikan, balasan Story dan mention, balasan sebaris, serta penghapusan. Setiap event berada dalam array messaging dengan ID pengirim yang dilingkup Instagram, penerima, timestamp, dan objek pesan. Pesan yang dikirim akun itu sendiri kembali lewat field yang sama dengan is_echo bernilai true.
easyCoexistence berlangganan setiap akun Instagram yang terhubung ke pesan dan meneruskan DM-nya, termasuk echo, ke endpoint HTTPS Anda saat tiba, ditandatangani dengan rahasia akun itu; penerusan tidak menyimpan salinan, dan DM tidak disimpan secara default.
Bernilai true pada event pesan untuk pesan yang dikirim akun itu sendiri.
Jendela pesan standar untuk sebagian besar aksi pengguna, selama app dapat membalas orang tersebut.
Tipe lampiran untuk postingan yang dibagikan; tipe share lama hanya didukung sampai 1 Februari 2026.
Tipe lampiran event DM yang dikirim Meta saat seseorang menyebut akun dalam Story-nya.
Subkode kesalahan di bawah kode 200, ketika pemilik akun menonaktifkan akses ke DM Instagram.
Kapan field pesan terpicu?
Saat seseorang mengirim DM ke akun profesional, dan saat akun itu mengirim satu. Contoh dan referensi Meta mencantumkan kasus berikut, masing-masing berupa event messaging dengan objek pesan:
- Teks, dan media sebagai lampiran: gambar, video, audio, dan file.
- Postingan atau Reel yang dibagikan, sebagai lampiran
ig_post,ig_reel, atau reel. - Balasan atas Story akun, dengan
reply_to.story, dan Story yang menyebut akun, sebagai lampiranstory_mention. - Balasan sebaris atas pesan sebelumnya, dengan
reply_to.mid, dan balasan cepat, denganquick_reply.payload. - Pesan yang dihapus orang tersebut (
is_deleted), media tidak didukung (is_unsupported), dan pesan dari seseorang yang mengklik iklan Click-to-Direct (referral). - Pesan yang dikirim akun, yang kembali dengan
is_echobernilai true.
Seperti apa notifikasi pesan?
Sebuah POST dengan JSON yang object-nya bernilai instagram. Berbeda dengan komentar, pesan berada dalam array messaging di dalam entry akun, dan setiap elemen memuat sender, recipient, timestamp, dan objek pesan. Balasan atas Story akun terlihat seperti ini:
{
"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>"
}
}
}
}
]
}
]
}Apa arti setiap field?
Field yang didokumentasikan Meta untuk event pesan di bawah Instagram Login, dari luar ke dalam:
- entry[].id: ID akun profesional. entry[].time: kapan Meta mengirim notifikasi; sampel pesan Meta menyajikannya dalam milidetik.
- sender.id dan recipient.id: pada DM masuk, ID berlingkup Instagram milik orang tersebut dan ID akun; pada echo, keduanya terbalik.
- timestamp: kapan pesan dikirim, dalam milidetik pada sampel Meta. Urutkan pesan berdasarkan field ini, bukan urutan kedatangan.
- message.mid: ID pesan, untuk deduplikasi, reaksi, dan membalas pesan itu dengan
reply_to.mid. - message.text: disertakan saat pesan memuat teks.
- message.attachments[]: masing-masing dengan type dan payload, biasanya url. Payload
ig_postpada postingan yang dibagikan menambahkanig_post_media_iddan title, yaitu keterangannya. - message.
reply_to: mid untuk balasan sebaris, atau story dengan url dan id Story untuk balasan Story. - message.
quick_reply.payload dan message.referral: balasan cepat yang dipilih, dan ref,ad_id, source, type, sertaads_context_datadari iklan Click-to-Direct. - message.
is_deleted,is_echo,is_self, danis_unsupported: hanya disertakan saat bernilai true. - message.
admin_textdanhandoff_reason: pada aplikasi yang memenuhi syarat, pemberitahuan bahwa aplikasi Meta, seperti Meta Business Agent, mengalihkan percakapan; bisa tiba tanpa mid atau teks.
Bagaimana echo bekerja?
Saat akun mengirim pesan, Meta juga mengirim event pesan untuk itu, dengan is_echo bernilai true. sender.id kemudian berupa akun dan recipient.id berupa ID berlingkup Instagram milik orang tersebut, dan pesan uji yang dikirim akun ke dirinya sendiri juga membawa is_self. Echo mencatat apa yang dikatakan akun, yang dibutuhkan log percakapan, tetapi handler yang memutuskan apakah membalas harus melewatinya. Meta tidak mengirim echo saat akun memberi reaksi pada pesan atau menghapus reaksi.
{
"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
}
}
]
}
]
}ID mana yang dibalas?
sender.id, ID berlingkup Instagram milik orang tersebut. Meta membuatnya saat seseorang mengirim pesan ke akun atau berkomentar pada medianya, dan ID itu spesifik untuk orang tersebut dan akun tersebut. POST /<IG_ID>/messages dengan recipient.id yang diisi ID itu mengirim balasan. Event tidak memuat nama atau username; GET /<IGSID> dengan field seperti name dan username mengembalikannya, karena orang yang telah mengirim pesan ke akun telah memberikan persetujuan yang dibutuhkan pencarian itu.
Bagaimana pesan membuka jendela 24 jam?
Aplikasi hanya dapat mengirim pesan kepada seseorang setelah orang itu mengirim pesan ke akun, dan hanya dalam jendela pesan standar yang dibuka oleh aksinya. Untuk sebagian besar aksi, jendela layanan pelanggan 24 jam berlangsung, dan hingga 7 hari dari pesan pertama yang dikirim setelah mengklik iklan Click-to-Direct. Pesan baru dari orang tersebut membuka jendela baru, jadi timestamp terakhirnya yang perlu dilacak; echo adalah pesan akun itu sendiri dan tidak memperpanjang apa pun. Balasan yang ditulis orang tersebut dapat memakai jendela Human Agent 7 hari yang terpisah dari Meta, ditandai human_agent.
Apa yang tidak dibawa event pesan?
Beberapa hal yang mungkin dicari handler tidak ada, menurut referensi pesan Meta:
- Nama atau username orang tersebut: hanya ID berlingkup Instagram, yang diselesaikan oleh GET /<IGSID>.
- Media sekali lihat: tiba sebagai lampiran sementara tanpa URL.
- Gambar karusel yang tepat: reaksi terhadap, atau penerusan, satu gambar dalam postingan karusel melaporkan gambar pertama.
- Reaksi, edit, dan tanda sudah dibaca, yang datang pada field tersendiri.
- Penanda baca: pesan yang dikirim lewat webhook tetap belum dibaca di kotak masuk Instagram hingga balasan dikirim.
Field pesan lain apa yang disebut Meta?
Daftar field dan contoh Meta untuk Instagram Login menyebut selain pesan, masing-masing berupa event messaging tersendiri. easyCoexistence berlangganan setiap akun hanya ke pesan, komentar, dan mention, sehingga tidak satu pun dari ini termasuk yang diteruskannya:
message_reactions: seseorang memberi reaksi pada pesan atau menghapus reaksi, dengan reaction.mid, action bernilai react atau unreact, serta reaction dan emoji.message_edit: seseorang mengedit pesan, denganmessage_edit.mid, teks baru, dannum_edit.messaging_postbacks: seseorang menekan icebreaker atau tombol template, dengan postback.mid, title, dan payload.messaging_referral: seseorang yang sudah dalam percakapan membuka tautan ig.me dengan parameter ref.messaging_seen: seseorang membaca pesan, dengan read.mid.messaging_optins,messaging_handover, dan standby: dua yang terakhir untuk aplikasi yang berbagi percakapan di bawah protokol handover Meta.
Apa yang harus diaktifkan akun?
Izinkan akses ke pesan. Meta mengharuskan akun profesional mengaktifkannya sebelum pesannya dapat dikelola melalui API, di aplikasi Instagram pada Pengaturan, Pesan dan balasan Story, Kontrol pesan, Alat terhubung. Selama dinonaktifkan, pengiriman gagal dengan kode 200, subkode 2534041. Aplikasi juga memerlukan instagram_business_basic dan instagram_business_manage_messages, dengan Advanced Access untuk melayani akun yang tidak dimilikinya atau dikelolanya.
Bagaimana easyCoexistence meneruskan DM?
Seperti komentar: setiap entry yang Meta kirimkan untuk akun di-POST ke endpoint HTTPS Anda di dalam amplop berisi platform, account_id, external_id, dan entry, ditandatangani di X-EC-Signature dengan rahasia akun, sekali dan tanpa salinan yang disimpan. Echo diteruskan bersama yang lain, jadi periksa is_echo sebelum membalas. Untuk menjawab, panggil send_social_dm dengan account_id dan sender.id dari event sebagai recipient_id, dalam jendela 24 jam. Otomatisasi yang dimulai dari DM berjalan pada event yang sama.
{
"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>" } }
]
}
}
]
}
}Kesalahan umum
- Membalas echo. Event dengan is_echo adalah pesan akun itu sendiri, dan membalasnya membuat akun terjebak dalam perulangan dengan dirinya sendiri.
- Menganggap pesan selalu memiliki teks. Lampiran, postingan yang dibagikan, mention Story, dan penghapusan tiba tanpa field teks, jadi cabanglah sesuai isi objek pesan.
- Mengurutkan pesan berdasarkan kedatangan. Meta dapat mengirim pesan tidak berurutan setelah kegagalan, jadi urutkan berdasarkan timestamp.
- Membaca time dan timestamp sebagai detik. Sampel pesan Meta memberikan keduanya dalam milidetik, dan jika dibaca sebagai detik, hasilnya menjadi tanggal jauh di masa depan.
send_social_dm membalas dalam jendela 24 jam, dan otomatisasi dapat membalas sendiri dengan teks tetap atau AI. US$ 9 sampai US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Apakah timestamp webhook pesan Instagram dalam detik atau milidetik?
Milidetik, pada sampel pesan Meta, untuk timestamp maupun waktu entry. Jika dibaca sebagai detik, hasilnya menjadi tanggal jauh di masa depan.
Bagaimana cara mendapatkan username pengirim dari webhook DM Instagram?
Panggil GET /<IGSID> dengan field seperti name dan username. Event hanya memuat ID berlingkup Instagram milik orang tersebut.
Mengapa webhook DM Instagram saya tidak datang?
Periksa apakah akun telah mengaktifkan Izinkan akses ke pesan, apakah akun berlangganan pesan melalui /subscribed_apps, dan apakah aplikasi berstatus Live dengan Advanced Access untuk akun yang tidak dimilikinya.
Apakah easyCoexistence meneruskan reaksi pesan Instagram?
Tidak. Reaksi datang pada message_reactions, dan easyCoexistence berlangganan akun ke pesan, komentar, dan mention.
Lanjut membaca
Hubungkan saluran pertama Anda dalam dua menit.
Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.
- Gratis 3 hari
- Batalkan kapan saja
- Hanya API resmi
- Dipantau 24/7
Diverifikasi pada