API dan MCP

Halaman ini untuk developer dan siapa pun yang ingin menyambungkan IMMA AI ke aplikasi, n8n, atau agen AI seperti Claude. Kalau Anda hanya memakai dashboard, lihat Mulai cepat.

1. Buat API key

1. Buka dashboard, pilih Developers, lalu tab API keys. Hanya Owner workspace yang bisa membuat key.
2. Klik Create key, beri nama sesuai penggunaannya (satu key untuk satu integrasi), lalu centang izin yang perlu.
3. Salin key sekarang juga. Key hanya tampil sekali dan diawali imma_live_. Kalau hilang, buat key baru dan cabut yang lama.

Izin posts:publish mati secara default. Key dengan izin ini bisa langsung menerbitkan atau menjadwalkan post tanpa persetujuan manusia, termasuk kalau dipegang agen AI. Beri izin ini hanya untuk integrasi yang Anda percaya. Tanpa izin ini, key tetap bisa membuat draf dan link persetujuan. Daftar semua izin ada di Authentication.

Jangan pernah menaruh key di kode yang berjalan di browser atau aplikasi HP, atau di repositori publik.

2. Request pertama

Semua request memakai header Authorization: Bearer. Base URL: https://api.getimma.com/v1.

curl https://api.getimma.com/v1/accounts \
  -H "Authorization: Bearer imma_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0"

Pakai id akun sebagai account_id, lalu buat draf:

curl -X POST https://api.getimma.com/v1/posts \
  -H "Authorization: Bearer imma_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c1a52-0b7a-4c1e-9d0e-2f5f4c1d7a10" \
  -d '{
    "caption": "Rendang 1 kg, pre-order sampai Jumat #rendang",
    "targets": [{ "account_id": "acc_01J..." }],
    "publish": { "mode": "draft" }
  }'

publish.mode bisa draft (disimpan saja), approval (dibuatkan link untuk disetujui manusia), now, atau schedule (keduanya butuh posts:publish). Untuk agen AI, pilih approval. Kirim selalu Idempotency-Key supaya request yang diulang tidak membuat post ganda.

Hal yang sering terlewat: target Instagram wajib punya options berisi igType (feed, carousel, reel, atau story). Detail lengkap: Quickstart dan API reference.

3. Hubungkan agen AI lewat MCP

MCP server ada di https://api.getimma.com/mcp. Agen Anda yang menulis caption dan balasan, IMMA AI yang memposting dan menjaga aturan platform. IMMA AI tidak pernah membalas komentar atau pesan sendiri.

Claude Code:

claude mcp add --transport http imma-ai https://api.getimma.com/mcp --header "Authorization: Bearer API_KEY_ANDA"

Claude Desktop, Cursor, dan n8n juga bisa. Konfigurasinya ada di tab MCP pada halaman Developers dan di MCP quickstart. Claude juga bisa terhubung tanpa API key lewat konektor kustom dengan login OAuth: lihat Connect Claude (halaman teknis, Bahasa Inggris). Hanya Owner workspace yang bisa menyetujui koneksi, dan izin posts:publish tidak dicentang secara default. ChatGPT belum tersedia.

Memutus koneksi: buka Developers > MCP lalu klik Putuskan di samping aplikasi. Akses berhenti pada permintaan berikutnya.

Contoh perintah ke agen: "Buatkan tiga draf post Instagram untuk minggu depan, lalu kirim untuk persetujuan."

Izin pada key menentukan alat apa saja yang terlihat oleh agen. Teks komentar dan pesan dari pihak ketiga ditandai sebagai konten tidak tepercaya supaya agen tidak menganggapnya sebagai perintah.

4. Webhook

Webhook memberi tahu server Anda saat ada kejadian, misalnya post.published, post.failed, comment.created, atau message.received. Fitur ini diaktifkan per workspace atas permintaan selama beta: kalau tab Webhooks di halaman Developers menyatakan belum aktif, hubungi kami.

• Setiap pengiriman ditandatangani dengan header IMMA-Signature. Selalu verifikasi tanda tangan memakai secret endpoint (diawali whsec_, hanya tampil sekali saat endpoint dibuat). Contoh kode Node dan PHP ada di Webhooks.
• URL harus https publik dengan port 443 atau 8443. Redirect tidak diikuti. Balas dengan status 2xx dalam 10 detik.
• Pengiriman diulang sampai 8 kali (sekitar 10 jam). Satu event bisa datang lebih dari sekali, jadi buang duplikat berdasarkan header IMMA-Event-Id.
• Endpoint yang gagal terus selama 3 hari dinonaktifkan otomatis dan Owner diberi tahu.

Aturan yang perlu diingat

• Jendela balasan pesan langsung (DM) hanya 24 jam sejak pesan terakhir pelanggan. Lewat itu, balasan ditolak dengan reply_window_closed.
• Batas request: 120 per menit per key. Kalau kena 429, tunggu sejumlah detik di header Retry-After. Lihat Rate limits.
• Setiap error punya message_id dalam Bahasa Indonesia, dan daftar kode error ada di Errors.
• TikTok belum tersedia. Saat nanti tersedia, posting langsung ke TikTok akan selalu membutuhkan persetujuan eksplisit dari manusia.