API Notivia Social Media (Instagram)

REST sederhana untuk mengelola akun Instagram Business/Creator: publish (gambar, Reels, carousel), baca & balas komentar, dan balas DM. Semua respons berformat JSON.

Base URL	https://socialmedia.notivia.asia
Format	JSON (request body application/json)
Auth	Header Authorization: Bearer <API_KEY>

Autentikasi

Buat API key di panel → tab API. Setiap key terikat ke satu akun Instagram (akun yang login saat key dibuat). Sertakan di tiap request:

Authorization: Bearer 3f9a2c...kunci-anda

Tanpa key yang valid, endpoint yang butuh akun akan menolak (401) atau membalas {"connected":false} untuk /me.

Format Error

Error selalu HTTP status non-2xx + body:

{ "error": "pesan error" }

401	Belum auth / key tidak valid
400	Request salah / error dari Instagram
404	Resource tidak ditemukan

GET /me

Info akun yang terhubung.

curl https://socialmedia.notivia.asia/me \
  -H "Authorization: Bearer KEY"

// 200
{ "user_id":"178414...", "username":"tendangan.sudut",
  "account_type":"BUSINESS", "media_count":42 }

GET /media

Daftar 24 postingan terbaru (dari cache DB). Tambah ?refresh=1 untuk tarik ulang dari Instagram.

// 200
{ "data": [
  { "id":"1812...", "caption":"Halo", "media_type":"IMAGE",
    "media_url":"https://...", "thumbnail_url":null,
    "permalink":"https://www.instagram.com/p/...", "timestamp":"2026-06-28T..." }
] }

Catatan: media_url adalah URL CDN Instagram yang bisa kedaluwarsa beberapa hari.

POST /publish

Menerbitkan konten. Bersifat asinkron: request mengembalikan job_id, proses ke Instagram dijalankan worker. Pantau lewat /publish/status.

Body (pilih salah satu bentuk):

Gambar	{ "image_url": "...", "caption": "..." }
Reels	{ "video_url": "....mp4", "caption": "..." }
Carousel	{ "children": [ {"image_url":"..."}, {"video_url":"..."} ], "caption": "..." } (2–10 item)

curl -X POST https://socialmedia.notivia.asia/publish \
  -H "Authorization: Bearer KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://contoh.com/foto.jpg","caption":"Halo dunia"}'

// 200
{ "job_id": 12, "status": "pending" }

URL gambar/video harus publik & bisa di-fetch Instagram. Pakai /upload kalau filenya lokal.

GET /publish/status?id={job_id}

Status job publish. status: pending → processing → done/error.

// done
{ "status":"done", "result":"{\"id\":\"179...\"}", "error":null }
// error
{ "status":"error", "result":null, "error":"pesan..." }

Pola pemakaian: POST /publish → ambil job_id → polling GET /publish/status tiap ±2 dtk sampai done.

POST /upload

Upload satu gambar (raw body, application/octet-stream). Server resize ke JPEG & host di domainmu, lalu kembalikan URL publik yang bisa dipakai di /publish.

curl -X POST https://socialmedia.notivia.asia/upload \
  -H "Authorization: Bearer KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @foto.jpg

// 200
{ "url": "https://socialmedia.notivia.asia/uploads/178....jpg" }

GET /media/{media_id}/comments

// 200
{ "data": [ { "id":"17...", "text":"keren", "username":"budi",
  "timestamp":"...", "from":{"id":"...","username":"budi"} } ] }

GET /comments/{comment_id}/replies

Daftar balasan sebuah komentar (struktur sama dengan comments).

POST /comments/{comment_id}/reply

Balas komentar (tampil publik di bawah komentar).

curl -X POST .../comments/17.../reply \
  -H "Authorization: Bearer KEY" -H "Content-Type: application/json" \
  -d '{"message":"Terima kasih!"}'

POST /comments/{comment_id}/private-reply

Balas komentar lewat DM (private reply). Body sama: { "message": "..." }.

GET /messages

DM masuk yang tersimpan (dikumpulkan dari webhook). Maks 50 terbaru.

// 200
{ "data": [ { "id":5, "sender_id":"178...", "text":"halo",
  "replied":0, "created_at":"2026-06-28 10:00:00" } ] }

POST /messages/reply

Balas DM spesifik (berdasarkan id baris dari /messages).

curl -X POST .../messages/reply \
  -H "Authorization: Bearer KEY" -H "Content-Type: application/json" \
  -d '{"id":5,"message":"Halo, ada yang bisa dibantu?"}'

Instagram membatasi balasan DM dalam 7 hari sejak pesan terakhir user.

GET /conversations

Daftar percakapan DM (1 baris per lawan chat) untuk tampilan chat. Diurut dari yang terbaru.

// 200
{ "data": [
  { "sender_id":"178...", "username":"budi",
    "last_text":"halo kak", "last_at":"2026-06-28 10:00:00", "unread":2 }
] }

username jatuh ke sender_id kalau IG belum memberi username. unread = jumlah pesan masuk yang belum dibuka. Endpoint ini juga otomatis mengisi username yang masih kosong (best-effort, ke-cache setelah terisi).

GET /conversations/{sender_id}

Seluruh pesan dengan satu lawan chat, urut lama→baru (untuk render bubble). Memanggil ini menandai pesan masuk sbg sudah dibaca.

// 200
{ "data": [
  { "id":5, "text":"halo kak", "direction":"in",  "created_at":"..." },
  { "id":6, "text":"halo, ada yg bisa dibantu?", "direction":"out", "created_at":"..." }
] }

direction: in = dari user, out = balasan akun kamu.

POST /conversations/{sender_id}/send

Kirim DM ke lawan chat & simpan ke riwayat sbg out.

curl -X POST .../conversations/178.../send \
  -H "Authorization: Bearer KEY" -H "Content-Type: application/json" \
  -d '{"message":"Halo, ada yang bisa dibantu?"}'

Instagram membatasi balasan DM dalam 7 hari sejak pesan terakhir user.

GET /conversations/backfill

Isi username yang masih kosong untuk chat lama (best-effort, ambil dari profil IG pengirim). Biasanya tidak perlu dipanggil manual — /conversations sudah melakukannya otomatis.

// 200
{ "updated": 3 }

GET /webhook/subscribe

Daftarkan akun yang sedang login ke webhook app (field messages & comments). Wajib dipanggil sekali agar DM/komentar masuk ke /conversations & /messages.

// 200
{ "subscribe":{"success":true},
  "current":{"data":[{"subscribed_fields":["messages","comments"]}]} }

API Keys

Dikelola dari panel (butuh login sesi browser, bukan via Bearer):

GET /api/keys	daftar key milik akun
POST /api/keys	buat key — { "label": "..." } → balas { "api_key": "..." } (sekali tampil)
POST /api/keys/delete	hapus — { "id": 1 }

Webhook (masuk dari Instagram)

Bukan untuk dipanggil konsumen — ini endpoint yang Instagram panggil untuk mengirim event (DM & komentar). DM masuk otomatis disimpan dan bisa dibaca via /messages.

GET /webhook	verifikasi (challenge) saat setup
POST /webhook	terima event (diverifikasi via signature HMAC)

---

© Notivia · Terms · Privacy