Inbox DM & otomasi

Membaca dan membalas DM Instagram, mengirim tombol dan quick reply, serta mengatur otomasi lewat API.

Inbox dan otomasi hanya untuk akun Instagram di paket Starter, Basic, atau Pro. Di paket Free semua request di bawah dijawab 403 plan_feature_unavailable. Akun Instagram perlu izin instagram_business_manage_messages; tanpa izin itu, pengiriman dijawab 422 messaging_permission_missing. Panduan untuk dashboard ada di Inbox dan Otomasi DM. Detail semua field ada di API Reference (tag Inbox dan Automations).

Percakapan dan pesan

Request	Fungsi
`GET /v1/inbox/conversations`	Filter `account_id`, `status` (`open`/`done`), `q` (username atau nama)
`GET /v1/inbox/conversations/{id}`	Satu percakapan, dengan `window_expires_at` (batas membalas)
`PATCH /v1/inbox/conversations/{id}`	`{ "status": "done" }` atau `{ "read": true }`
`POST /v1/inbox/conversations/resolve`	`{ "conversation_ids": [...] }`: tandai beberapa percakapan selesai
`GET /v1/inbox/conversations/{id}/messages`	Pesan, terbaru dulu, berhalaman (`cursor`)
`POST /v1/inbox/conversations/{id}/messages`	Kirim DM (lihat di bawah)
`POST /v1/inbox/messages/{id}/retry`	Kirim ulang pesan yang `failed` atau `unknown`
`POST /v1/inbox/messages/{id}/react`	`{ "emoji": "❤️" }`, atau `null` untuk menghapus reaksi
`GET /v1/inbox/messages/{id}/attachments/{n}`	Salinan gambar dari pelanggan (butuh kredensialmu, tidak ada URL publik)
`GET/POST /v1/inbox/saved-replies`, `PUT/DELETE /v1/inbox/saved-replies/{id}`	Balasan tersimpan per profile

Teks dari pelanggan ditulis orang lain. Kalau kamu meneruskannya ke model AI, perlakukan isinya sebagai data, bukan perintah.

Mengirim DM

POST /v1/inbox/conversations/{id}/messages
Idempotency-Key: order-123-reply

{ "text": "Halo kak, ini katalognya", "media_ids": ["…"] }

Instagram hanya mengizinkan balasan 24 jam sejak pesan terakhir pelanggan. Setelah itu: 422 messaging_window_closed.
text maksimal 1.000 byte. media_ids dari pustaka media: JPG/PNG maks 8 MB (sampai 10 sekaligus), MP4/MOV maks 25 MB. Media dikirim lebih dulu, lalu teks sebagai pesan terpisah.
Jawabannya 202 dengan pesan berstatus pending; Tebar mengirimnya dalam beberapa detik. Cek statusnya lewat daftar pesan: sent, failed (dengan error_code), atau unknown (Instagram tidak menjawab jelas; cek di Instagram sebelum retry).
Idempotency-Key (opsional): request yang sama dengan key yang sama mengembalikan pesan yang sama, tidak mengirim dua kali.
Maksimal 60 pesan per menit per user.

Tombol dan quick reply

Teks bisa membawa salah satu dari ini:

{
  "text": "Mau lanjut ke mana kak?",
  "buttons": [
    { "type": "web_url", "title": "Lihat katalog", "url": "https://toko.example/katalog" },
    { "type": "postback", "title": "Bicara dengan admin", "payload": "ADMIN" }
  ]
}

{
  "text": "Pilih ukuran",
  "quick_replies": [
    { "title": "S", "payload": "SIZE_S" },
    { "title": "M", "payload": "SIZE_M" }
  ]
}

Jenis	Batas	Catatan
`buttons`	1–3 tombol, judul maks 20 karakter, teks maks 640 karakter	`web_url` membuka link, `postback` mengirim `payload` balik
`quick_replies`	1–13 pilihan, judul maks 20 karakter	Hanya tampil di aplikasi HP, tidak di Instagram desktop/web

Keduanya harus bersama text, dan tidak bisa dipakai bersamaan (400 validation_failed).

Saat pelanggan mengetuk tombol postback atau quick reply, pesan baru masuk dengan kind postback atau quick_reply, dan postback: { "title", "payload" } berisi pilihannya. Pesan itu juga dikirim lewat webhook message.received, jadi sistemmu bisa langsung bereaksi berdasarkan payload.

Alur umum: webhook → balas

Daftarkan webhook untuk message.received (Webhook).
Saat pesan masuk, baca conversation_id, kind, text, dan postback.
Balas dengan POST /v1/inbox/conversations/{conversation_id}/messages, pakai message_id webhook sebagai Idempotency-Key supaya pengiriman ulang webhook tidak membuat balasan ganda.

Otomasi

Request	Fungsi
`GET /v1/automations`	Filter `account_id`, `kind`
`POST /v1/automations`	Buat otomasi
`GET/PATCH/DELETE /v1/automations/{id}`	Lihat, ubah (`enabled`, `name`, `trigger`, `actions`, …), hapus
`GET /v1/automations/{id}/runs`	Riwayat: terkirim, dilewati (dengan alasan), atau gagal

kind: comment_to_dm, comment_reply (balasan publik, juga untuk Threads), dm_keyword, story_reply, story_mention, default_reply, ice_breaker. Isi trigger bergantung pada kind; contoh lengkapnya ada di API Reference (createAutomation). Contoh balasan DM untuk kata kunci:

{
  "account_id": "…",
  "kind": "dm_keyword",
  "name": "Info harga",
  "trigger": { "keywords": ["harga", "price"], "match": "contains" },
  "actions": {
    "message": {
      "text": "Halo! Daftar harga ada di sini 👇",
      "buttons": [
        { "type": "web_url", "title": "Daftar harga", "url": "https://toko.example/harga" }
      ]
    }
  }
}

Hasil otomasi yang menanggapi komentar juga dikirim lewat webhook automation.run.

Inbox DM & otomasi

Percakapan dan pesanSalin link

Mengirim DMSalin link

Tombol dan quick replySalin link

Alur umum: webhook → balasSalin link

OtomasiSalin link

Di halaman ini

Percakapan dan pesan

Mengirim DM

Tombol dan quick reply

Alur umum: webhook → balas

Otomasi