Wiki Provinsi Gorontalo

Panduan Bot GodigiTalk-GoCloud

Panduan pengelolaan bot GodigiTalk-GoCLoud: akses SSO, ruang privat, aplikasi dan API key, integrasi notifikasi, pemantauan pengiriman, serta perintah server dan mailserver.

Edisi 21 November 2026 · Panel 0.27.0 · Untuk administrator dan pengelola integrasi.

Panduan administrator panel dan pengelola integrasi notifikasi Nextcloud Talk. Screenshot pada panduan ini mengikuti penempatan dan keterangan dalam panduan Markdown proyek. Nama menu dan batas layanan mengacu pada edisi 21 November 2026.

Daftar isi

  1. Mulai dari sini
  2. Masuk ke panel
  3. Login Godigi dan sesi habis
  4. Membaca Ringkasan
  5. Verifikasi Akun Nextcloud saya
  6. Memahami daftar Ruang Talk
  7. Buat atau hubungkan ruang privat
  8. Cek dan perbaiki koneksi bot
  9. Daftar aplikasi dan akses
  10. Tambah aplikasi dan simpan key
  11. Ubah ruang, ganti, atau cabut key
  12. Tetapkan penanggung jawab aplikasi
  13. Riwayat pemilik dan laporan CSV
  14. Tes notifikasi dari panel
  15. Panduan integrasi yang bisa disalin
  16. Kontrak API dan hasil pengiriman
  17. Contoh kirim dari Linux / Bash
  18. Contoh Windows dan jadwal otomatis
  19. Pantau Pengiriman dan detail error
  20. Kirim ulang satu pesan
  21. Kirim ulang massal dan hanya yang gagal
  22. Riwayat batch, refresh, dan CSV
  23. Pemberitahuan dan status dibaca
  24. Kelola pengguna dan hak administrator
  25. Aktivitas admin dan penelusuran
  26. Perintah chat untuk server Nextcloud
  27. Perintah pemeriksaan mailserver
  28. Tindakan mailserver dengan konfirmasi
  29. Laporan eksternal, PDF, dan Markdown
  30. Pemecahan masalah
  31. Checklist operasional dan referensi

01. Mulai dari sini

Godigi Bot / NextcloudBot menghubungkan server dan aplikasi ke ruang privat Nextcloud Talk. Panel adalah tempat mengelola aplikasi, API key, ruang, pengguna, dan hasil pengiriman. Anda tidak perlu membuat bot Telegram baru atau memasang Docker baru untuk setiap server.

Istilah Artinya
Aplikasi Identitas pengirim API, misalnya server-a atau mailserver.
Ruang Talk Percakapan privat tempat anggota menerima pesan.
Alias / destination Nama tujuan API, misalnya server-a. Bukan token ruang.
API key Rahasia akses khusus satu aplikasi.
Gorontalo Bot Identitas pengirim bot bersama.
bot-room-manager Akun layanan untuk pengelolaan ruang.
Pemilik aplikasi Penanggung jawab yang dicatat panel; tidak otomatis mendapat peran admin.
  1. Siapkan akun SSO Godigi yang sudah disetujui sebagai administrator panel. Login ke Nextcloud dengan identitas SSO yang sama minimal satu kali.
  2. Buka Akun Nextcloud saya dan verifikasi akun. Buat ruang privat baru atau hubungkan ruang yang Anda moderatori.
  3. Buat aplikasi, pilih ruang tujuan, lalu simpan API key yang hanya ditampilkan satu kali.
  4. Kirim tes dari panel. Setelah itu, uji API dari server menggunakan key aplikasi tersebut.
  5. Pantau Pengiriman. Jika gagal, periksa detail, perbaiki penyebab, lalu kirim ulang. Gunakan batch untuk beberapa pesan.
  6. Tetapkan penanggung jawab aplikasi, pantau pemberitahuan, dan unduh laporan sesuai kebutuhan.

Rujukan: panduan proyek NextcloudBot edisi 21 November 2026 dan panel 0.27.0. Alur yang belum tersedia pada data dokumentasi dijelaskan berdasarkan kode dan panduan panel; bukan hasil pengujian produksi baru.

02. Masuk ke panel

Alamat panel: https://bot.gorontaloprov.go.id/admin. Gunakan browser dengan JavaScript dan cookie aktif.

Halaman awal sebelum login.

  1. Buka alamat panel, kemudian klik Masuk dengan SSO Godigi.
  2. Pastikan halaman berikutnya berada di sso.gorontaloprov.go.id sebelum memasukkan kredensial.
  3. Selesaikan login SSO. Administrator akan masuk ke Ringkasan; akun baru masuk ke status Non-register dan belum boleh mengelola panel.
  4. Untuk keluar, gunakan tombol Keluar di bagian bawah menu samping. Pada layar kecil, buka Menu terlebih dahulu.

Keluar dari panel tidak selalu mengakhiri sesi Godigi. Jika Godigi masih login, masuk lagi dapat berlangsung tanpa meminta password. Jangan membagikan API key, cookie, password, atau OTP.

03. Login Godigi dan sesi habis

Password hanya dimasukkan pada Godigi. Panel bot tidak meminta password Nextcloud atau password Godigi di formulir pengelolaan aplikasi.

Formulir SSO sebelum kredensial diisi.

  1. Isi email dan kata sandi pada Godigi, lalu klik Masuk. Selesaikan OTP/MFA apabila diminta.
  2. Jika sesi panel habis, baca pemberitahuan sesi berakhir. Panel mengarahkan kembali ke login SSO secara otomatis.
  3. Sesudah login, panel kembali ke halaman sebelumnya beserta filter URL yang aman, misalnya tanggal, aplikasi, dan status batch.
  4. Periksa ulang pekerjaan sebelum melanjutkan. Formulir POST tidak dikirim ulang otomatis; teks yang belum disimpan mungkin perlu diisi kembali.
  5. Jika akses telah dicabut, login SSO tidak mengembalikan hak admin. Hubungi administrator panel untuk peninjauan akses.

Sesi panel berlaku maksimal 1 jam dan berakhir setelah 15 menit tanpa aktivitas yang memperbarui sesi. Refresh otomatis di latar belakang tidak memperpanjang sesi. Jika formulir lama gagal validasi saat sesi masih aktif, muat ulang halaman dan isi ulang; jangan menonaktifkan pemeriksaan keamanan.

04. Membaca Ringkasan

Ringkasan adalah titik awal pemantauan dan pintasan menuju halaman kerja. Angka mengikuti data yang masih tersimpan, bukan arsip sepanjang umur server.

Dashboard dengan statistik pengiriman dan akses cepat.

  1. Baca Total pesan, Diterima Talk, Dalam antrean, dan Gagal dikirim.
  2. Gunakan Hubungkan aplikasi untuk menyiapkan pengirim baru, atau kartu ruang untuk mengelola tujuan.
  3. Bagian Integrasikan server dalam tiga langkah menyediakan tautan ruang, aplikasi, tes, panduan, dan Unduh panduan .md.
  4. Buka Pemberitahuan untuk hasil batch dan perubahan pemilik. Badge menunjukkan jumlah yang belum Anda tandai dibaca.
  5. Gunakan Perbarui bila memerlukan data halaman terbaru; pemantauan batch memiliki pembaruan otomatis tersendiri.

Angka pada Ringkasan berubah mengikuti kondisi layanan. Periksa status terbaru saat menjalankan pekerjaan.

05. Verifikasi Akun Nextcloud saya

Verifikasi menghubungkan identitas SSO panel dengan akun Nextcloud yang benar, termasuk akun lama yang sudah ditautkan.

Identitas SSO, hasil verifikasi, dan daftar ruang pribadi.

  1. Login Nextcloud di https://gocloud.gorontaloprov.go.id menggunakan Godigi minimal sekali.
  2. Di panel, buka Akun Nextcloud saya lalu klik Verifikasi akun & perbarui ruang.
  3. Cocokkan nama dan UID Nextcloud serta waktu pemeriksaan terakhir. Tidak ada password yang perlu dimasukkan.
  4. Ruang saya hanya memuat grup privat lokal tempat Anda menjadi pemilik atau moderator. Percakapan pribadi dan ruang yang hanya Anda ikuti sebagai anggota tidak ditampilkan.
  5. Untuk ruang yang belum terhubung, isi alias unik lalu klik Hubungkan ruang pilihan. Tindakan ini menambahkan akun layanan sebagai moderator dan mengaktifkan bot.
  6. Periksa Aplikasi / bot milik saya untuk daftar penanggung jawab aplikasi. Verifikasi ulang setelah perubahan keanggotaan ruang.

Verifikasi dibatasi setiap 30 detik dan tidak memindai terus-menerus. Daftar ruang adalah hasil pemeriksaan terakhir. Kepemilikan aplikasi, peran moderator Talk, dan hak administrator panel adalah tiga hal yang berbeda.

06. Memahami daftar Ruang Talk

Halaman ini menampilkan alias yang sudah terhubung beserta tautan ruang. Satu ruang dapat menerima beberapa aplikasi; satu aplikasi hanya boleh mengirim ke tujuan yang diizinkan.

Kartu ruang terhubung dan tombol pemeriksaan.

  1. Buka Ruang Talk. Catat alias API pada kartu ruang, bukan hanya nama tampilannya.
  2. Klik nama ruang untuk membuka percakapan Talk dan periksa peserta penerima notifikasi.
  3. Cek koneksi bot memeriksa bot aktif dan peran bot-room-manager tanpa mengirim pesan.
  4. Atur akses aplikasi membuka pengaturan pengirim yang memakai tujuan tersebut.
  5. Gulir ke bawah untuk membuat ruang atau menghubungkan ruang yang sudah ada.

Untuk server A, B, C: gunakan aplikasi dan key terpisah. Anda boleh memakai satu ruang per server dan membedakan kategori dengan hashtag. Aplikasi fail2ban dan nextcloud-alerts saat dokumentasi sama-sama memakai alias notifications; keberadaan alias lama di daftar tidak berarti notifikasi aktif harus dipisah ke sana.

07. Buat atau hubungkan ruang privat

Selesaikan verifikasi Akun Nextcloud saya sebelum menjalankan operasi ruang.

Contoh isian ruang baru; belum disubmit.

  1. Ruang baru: isi Nama ruang, misalnya Notifikasi Server A, dan Alias tujuan API, misalnya server-a. Alias maksimal 64 karakter; gunakan huruf, angka, minus, atau garis bawah, dimulai huruf/angka.
  2. Klik Buat ruang & hubungkan bot. Ruang dibuat privat, akun Anda diundang sebagai moderator, dan bot diaktifkan.
  3. Pastikan Hasil pengaturan ruang menunjukkan Terhubung. Jika belum lengkap, gunakan Lanjutkan pengaturan bila tersedia; periksa ruang yang sudah terbentuk sebelum membuat ulang.
  4. Ruang yang sudah ada: pastikan Anda moderator grup privat. Tambahkan bot-room-manager sebagai moderator lewat peserta Talk, lalu Perbarui panel.
  5. Pada Hubungkan ruang yang ada, pilih ruang, isi alias unik, lalu klik Hubungkan ruang. Alternatifnya gunakan Hubungkan ruang pilihan di Akun Nextcloud saya.
  6. Buka Talk dan kelola peserta penerima notifikasi sesuai kebutuhan.

Untuk ruang baru yang dibuat panel, akun layanan adalah pemilik teknis dan akun pembuat diundang sebagai moderator. Catatan pemilik aplikasi tidak otomatis memindahkan kepemilikan teknis ruang. Menambahkan bot-room-manager saja belum cukup: ruang tetap perlu dihubungkan dari panel.

08. Cek dan perbaiki koneksi bot

Gunakan pemeriksaan sebelum melakukan perbaikan. Status belum dapat dipastikan menunjukkan pemeriksaan tidak memperoleh bukti yang cukup, bukan selalu berarti bot mati.

Ruang Mailserver: bot aktif dan akun layanan moderator; formulir tes dibuka tanpa mengirim.

  1. Klik Cek koneksi bot pada ruang tujuan. Baca status bot, peran bot-room-manager, dan waktu pemeriksaan.
  2. Jika izin atau keanggotaan kurang, pastikan akun Anda pemilik/moderator ruang, lalu gunakan Perbaiki koneksi bot.
  3. Perbaikan menambahkan akun layanan jika perlu, menjadikannya moderator, dan mengaktifkan bot. Tindakan dicatat di audit; tidak membuat ruang baru.
  4. Buka Tes kirim pesan, pilih aplikasi pengirim yang diizinkan, dan isi pesan. Gulir bila tombol kirim berada di bawah layar.
  5. Klik Kirim pesan tes ke ruang ini hanya ketika siap mengirim pesan nyata. Buka detail pengiriman untuk error atau percobaan. Siapkan tes baru digunakan untuk pesan berikutnya.

Pemeriksaan dibatasi sekali per 5 detik per admin; perbaikan sekali per 30 detik. Ruang terhapus atau layanan bot dinonaktifkan secara global memerlukan administrator Nextcloud. Tes ruang memantau tiap 5 detik hingga 2 menit saat halaman terlihat dan perangkat online.

09. Daftar aplikasi dan akses

Setiap server atau aplikasi sebaiknya memiliki key sendiri, sehingga izin dan pengirimannya dapat dilacak secara terpisah.

Kartu aplikasi dengan status, pemilik, ruang, dan menu pengelolaan.

  1. Buka Aplikasi & akses. Periksa nama, status Aktif/Dicabut, pemilik, alias ruang, dan batas permintaan.
  2. Panduan aplikasi membuka contoh API sesuai aplikasi tersebut. Unduh .md menyimpan panduan yang dapat dibagikan tanpa key.
  3. Kelola akses menyediakan perubahan ruang, rotasi key, dan pencabutan key.
  4. Tetapkan / pindahkan pemilik mengatur penanggung jawab. Riwayat perubahan pemilik menampilkan perubahan dan laporan.
  5. Gulir ke Tambah aplikasi jika formulir tidak berada di samping daftar pada ukuran layar Anda.

Semua administrator panel memiliki akses pengelolaan yang luas. Pemilik aplikasi bukan pembatas akses antar-admin. API key hanya memberi hak API aplikasi terkait, bukan hak login panel atau pengambilan perintah agen mailserver.

10. Tambah aplikasi dan simpan key

Contoh server baru: aplikasi server-a dengan ruang Notifikasi Server A dan alias server-a. Endpoint pengiriman tetap sama untuk semua server.

Contoh formulir belum disubmit; pada screenshot dipilih ruang notifications yang sudah tersedia.

  1. Di Tambah aplikasi, isi Nama aplikasi yang unik, maksimal 64 karakter. Gunakan huruf/angka/minus/garis bawah dan mulai dengan huruf atau angka.
  2. Pilih Ruang Talk tujuan yang benar. Jika belum ada, siapkan ruang terlebih dahulu.
  3. Klik Tambah & buat API key. Pada halaman key, pilih seluruh isi kolom API key lalu salin ke penyimpanan rahasia backend/server.
  4. Klik Saya sudah menyimpan key setelah nilai tersimpan. Key hanya tampil pada halaman pembuatannya dan tidak dapat dilihat kembali di panel.
  5. Buka Tes notifikasi untuk menguji jalur panel, lalu gunakan Panduan aplikasi untuk menguji key dari server.
  6. Ulangi dengan nama dan key sendiri untuk server-b serta server-c; tidak perlu endpoint atau Docker baru.

Jangan menaruh key di frontend, Git, URL, screenshot, chat, atau log. Jika key hilang, ganti key dari Kelola akses. Halaman yang menampilkan key asli sengaja tidak difoto. Untuk tugas terjadwal, simpan key di secret manager atau environment layanan yang aksesnya dibatasi.

11. Ubah ruang, ganti, atau cabut key

Perubahan key langsung memengaruhi permintaan API baru. Siapkan pembaruan konfigurasi server pengirim sebelum melakukan rotasi.

Menu konfirmasi tersedia; tidak ada key yang dirotasi atau dicabut untuk dokumentasi.

  1. Ubah ruang: buka Kelola akses, pilih Ubah ruang tujuan, lalu Simpan. Sesuaikan nilai destination pada server dan contoh integrasi.
  2. Rotasi: buka Ganti / buat key baru, baca dampaknya, lalu Konfirmasi ganti key. Simpan key baru dan perbarui server yang menggunakannya.
  3. Rotasi membuat key lama langsung tidak berlaku serta mengaktifkan kembali aplikasi. Uji dari server untuk memastikan konfigurasi sudah sinkron.
  4. Cabut: buka Cabut API key lalu Konfirmasi pencabutan. Permintaan baru akan ditolak.
  5. Pesan yang sudah masuk antrean tetap diproses setelah pencabutan. Pencabutan bukan tombol membatalkan pesan yang sudah diterima gateway.

Untuk aplikasi mailserver, rotasi key juga harus disinkronkan pada konfigurasi agen mailserver. Tidak ada masa tumpang tindih key lama/baru yang dijanjikan oleh panel.

12. Tetapkan penanggung jawab aplikasi

Pemilik awal mengikuti akun pembuat aplikasi. Administrator dapat menetapkan aplikasi lama atau memindahkan tanggung jawab ke akun SSO terdaftar.

Formulir pemilik pada aplikasi backup.

  1. Pastikan akun tujuan pernah login SSO ke panel agar muncul pada pilihan.
  2. Pada kartu aplikasi, buka Tetapkan / pindahkan pemilik.
  3. Pilih Pemilik baru dan isi Alasan / catatan bila diperlukan, maksimal 500 karakter.
  4. Klik Simpan pemilik aplikasi. Periksa pemilik terbaru dan riwayatnya.
  5. Jika panel menyatakan pemilik sudah berubah di perangkat lain, muat ulang dan tinjau keadaan terbaru sebelum mengirim formulir lagi.

Pemindahan tidak mengganti key, ruang, status aplikasi, atau identitas pembuat yang diketahui. Pengguna Non-register tetap tanpa akses meski menjadi pemilik. Penetapan role admin dilakukan terpisah di Pengguna.

13. Riwayat pemilik dan laporan CSV

Riwayat per aplikasi memuat pemilik lama, pemilik baru, administrator, waktu WITA, dan catatan. Pemilik yang tidak diketahui ditulis Belum tercatat.

Filter tanggal/admin, CSV, serta ringkasan perubahan.

  1. Buka Riwayat perubahan pemilik pada aplikasi.
  2. Isi Tanggal mulai dan Tanggal akhir, pilih Administrator yang mengubah, lalu Terapkan filter. Tanggal akhir mencakup seluruh hari WITA.
  3. Baca total perubahan sesuai filter, jumlah administrator, dan waktu terakhir. Muat riwayat sebelumnya menambah hasil lama.
  4. Unduh CSV sesuai filter mencakup seluruh hasil filter, bukan hanya halaman terlihat. Terapkan perubahan isian sebelum mengunduh.
  5. Refresh berjalan saat riwayat terbuka. Jika sedang membaca halaman lama, gunakan Tampilkan perubahan terbaru ketika tersedia.

Riwayat memuat 20 perubahan per halaman. Pemeriksaan otomatis mulai 30 detik dan melambat sampai 120 detik jika tidak berubah; tab tersembunyi/offline dijeda. Jika ekspor terlalu besar, persempit rentang tanggal. Batas ekspor pemilik 32 MB; hasil tidak dipotong diam-diam.

14. Tes notifikasi dari panel

Tes panel memeriksa jalur antrean ke Talk menggunakan akses admin. Tes ini tidak membuktikan API key pada server sudah benar.

Contoh pesan Markdown sudah diisi, belum dikirim.

  1. Buka Tes notifikasi, pilih Aplikasi yang aktif, lalu Ruang Talk tujuan yang diizinkan.
  2. Isi Pesan notifikasi maksimal 4.000 karakter. Gunakan label #uji agar mudah dibedakan dari kejadian nyata.
  3. Klik Kirim tes notifikasi. Pesan benar-benar dikirim ke anggota ruang.
  4. Baca Hasil pengiriman: ID, status, jumlah percobaan, serta error bila ada. Status dipantau tiap 3 detik hingga 2 menit.
  5. Jika pemantauan berhenti, gunakan Perbarui status atau cari ID di Pengiriman. Jangan membuat pesan baru hanya karena status belum selesai.
  6. Pastikan pesan terlihat pada ruang yang dipilih, kemudian lanjutkan uji API dari server.

Maksimal 10 tes/menit per administrator; batas aplikasi juga berlaku. sent / Diterima Talk berarti Nextcloud menerima pesan, bukan bukti semua anggota sudah membacanya.

15. Panduan integrasi yang bisa disalin

Panduan API tersedia dari menu Panduan integrasi, Ringkasan, dan kartu aplikasi. Gunakan contoh yang sesuai pengirim agar alias tujuan tidak tertukar.

Panduan bawaan panel dan tombol unduh Markdown.

  1. Buka Panduan integrasi. Bagian pertama menjelaskan pembuatan dan penghubungan ruang.
  2. Pada Pilih contoh sesuai aplikasi, pilih pengirim lalu klik Tampilkan contoh. Jika aplikasi memiliki beberapa tujuan, pilih tujuannya.
  3. Pastikan nama aplikasi dan alias tujuan benar. Pilih contoh Linux/Bash + curl, PowerShell, Python, Node.js, atau PHP.
  4. Klik Salin contoh pada bahasa yang digunakan. Masukkan key di server secara aman, bukan ke dokumen ini.
  5. Klik Unduh panduan .md untuk panduan dengan pilihan saat ini. Jika ruang/izin berubah, unduh ulang.

Contoh tidak menyertakan API key. Bash memerlukan curl dan jq; PowerShell memakai prompt rahasia pada contoh interaktif. Untuk pekerjaan terjadwal, ganti prompt dengan pembacaan konfigurasi rahasia layanan.

16. Kontrak API dan hasil pengiriman

Base URL: https://bot.gorontaloprov.go.id. Gunakan HTTPS dengan validasi sertifikat. Semua endpoint di tabel memerlukan Authorization: Bearer API_KEY.

Pemilihan aplikasi mailserver dan contoh Linux pada panel.

Metode / jalur Kegunaan
POST /v1/messages Body JSON destination dan text; HTTP 202 berarti diterima antrean.
GET /v1/messages/ Status pesan milik aplikasi dengan key yang sama.
GET /v1/destinations Alias tujuan yang diizinkan untuk key tersebut.

POST memakai Content-Type: application/json. Teks 1-32.000 karakter, tidak hanya spasi; body maksimal 128 KiB. Respons memuat id, status, attempts, created, updated, message_id, error. message_id bisa kosong meski pesan diterima. Default kuota 120 permintaan/menit per aplikasi, termasuk cek status. Endpoint pesan menerima teks, bukan unggahan file.

17. Contoh kirim dari Linux / Bash

Contoh berikut untuk satu pengiriman interaktif. Prasyarat: curl, jq, akses HTTPS, aplikasi aktif, alias yang diizinkan. Ganti server-a dengan alias Anda. Contoh ini ditulis untuk disalin; tidak dijalankan selama pembuatan panduan.

BASE_URL='https://bot.gorontaloprov.go.id'
read -rsp 'API key aplikasi: ' BOT_API_KEY; echo
DESTINATION='server-a'
TEXT='**Status Server A**
Layanan berjalan normal.
#servera #status'
EVENT_ID="$(date +%s)-$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n')"
PAYLOAD=$(jq -n --arg destination "$DESTINATION" --arg text "$TEXT" \
  '{destination:$destination,text:$text}')

# Simpan EVENT_ID dan PAYLOAD untuk retry kejadian yang sama.
curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 30 \
  "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $BOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $EVENT_ID" \
  --data-binary "$PAYLOAD"

# Isi ID dari respons HTTP 202, kemudian cek status.
JOB_ID='ID_DARI_RESPONS'
curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 30 \
  "$BASE_URL/v1/messages/$JOB_ID" \
  -H "Authorization: Bearer $BOT_API_KEY"
unset BOT_API_KEY
  1. HTTP 202: simpan id dan pantau status setiap 5-10 detik dengan batas waktu. queued = antre; sending = dikirim; sent = diterima Talk; failed = perlu ditindaklanjuti.
  2. Saat timeout, 429, atau 5xx, ulangi terbatas dengan jeda bertahap menggunakan EVENT_ID dan PAYLOAD yang sama. Jangan menjalankan blok pembentukan ID baru untuk retry.
  3. Gunakan ID baru untuk peristiwa baru. Deduplikasi berlaku 30 hari per aplikasi, panjang Idempotency-Key maksimal 200 karakter. Payload berbeda dengan ID sama menghasilkan 409.

Setelah HTTP 202, jangan membuat pesan baru hanya karena masih antre. Gangguan antara Talk menerima pesan dan gateway menerima respons masih dapat menyebabkan duplikasi; periksa percakapan sebelum retry hasil yang tidak pasti.

18. Contoh Windows dan jadwal otomatis

Contoh PowerShell berikut mengirim teks UTF-8. Gunakan alias tujuan yang sudah diizinkan. Jangan menempelkan key asli ke file panduan.

$baseUrl = 'https://bot.gorontaloprov.go.id'
$secret = Read-Host 'API key aplikasi' -AsSecureString
$apiKey = [System.Net.NetworkCredential]::new('', $secret).Password
$eventId = [guid]::NewGuid().ToString()
$headers = @{
  Authorization = "Bearer $apiKey"
  'Idempotency-Key' = $eventId
}
$payload = @{
  destination = 'server-a'
  text = "**Status Server A**`nLayanan normal.`n#servera #status"
} | ConvertTo-Json
$job = Invoke-RestMethod -Method Post `
  -Uri "$baseUrl/v1/messages" -Headers $headers `
  -ContentType 'application/json; charset=utf-8' `
  -Body ([Text.Encoding]::UTF8.GetBytes($payload)) -TimeoutSec 30
$job
Invoke-RestMethod -Uri "$baseUrl/v1/messages/$($job.id)" `
  -Headers @{Authorization="Bearer $apiKey"} -TimeoutSec 30
$apiKey = $null
  1. Untuk Task Scheduler, cron, backup, atau monitoring, gunakan key dari secret manager atau environment proses backend. Jangan memakai prompt interaktif pada jadwal otomatis.
  2. Simpan ID peristiwa dan payload sebelum mencoba kirim. Retrying tugas harus memakai ID yang sama sampai hasilnya diketahui.
  3. Catat waktu, aplikasi, alias, ID pesan, dan status; jangan mencatat header Authorization. Gunakan jeda bertahap serta jumlah percobaan terbatas.
  4. Contoh Python, Node.js, dan PHP dapat disalin langsung dari Panduan integrasi sesuai aplikasi. Jangan memanggil API dengan key rahasia dari JavaScript browser.

19. Pantau Pengiriman dan detail error

Halaman Pengiriman menampilkan pesan yang tersimpan, aplikasi, waktu WITA, status, dan jumlah percobaan.

Filter pengiriman dan panel retry massal.

  1. Pilih Filter aplikasi dan Filter status, lalu Terapkan filter. Reset menghapus filter.
  2. Cari pesan berdasarkan aplikasi, waktu, dan ID pengiriman. Gunakan halaman Berikutnya bila diperlukan; maksimal 50 pesan per halaman.
  3. Klik Detail error & percobaan pada pesan. Cocokkan tujuan dan isi sebelum mengambil tindakan.
  4. Jika status queued atau sending, pantau terlebih dahulu. sent tidak perlu dikirim ulang.
  5. failed perlu diperiksa penyebabnya: koneksi, izin ruang, bot aktif, key aplikasi, atau gangguan Nextcloud.

Teks Markdown mungkin ditampilkan sebagai sumber teks pada panel. Hasil pemformatan dibaca di Talk. Jika tabel lebih lebar dari layar HP, geser tabel secara horizontal; menu dapat dibuka/tutup lewat Menu.

20. Kirim ulang satu pesan

Retry tersedia untuk pesan gagal. Perbaiki akar masalah dan periksa ruang sebelum mengirim ulang, terutama bila kegagalan sebelumnya adalah timeout.

Detail pesan sent dan satu percobaan berhasil; retry dinonaktifkan karena sudah diterima Talk.

  1. Buka Detail error & percobaan. Baca status, jumlah percobaan, HTTP/error, dan Aktivitas kirim ulang.
  2. Riwayat queued berarti percobaan gagal sementara lalu dijadwalkan ulang. interrupted berarti hasil belum dapat dipastikan setelah worker berhenti.
  3. Untuk failed, buka Kirim ulang lalu Konfirmasi kirim ulang. Pesan memakai tujuan asalnya.
  4. Perbarui status dan periksa percobaan baru. Jika tetap gagal, tangani error baru sebelum mencoba lagi.
  5. Jika bot gagal karena izin, buka Ruang Talk dan lakukan pemeriksaan/perbaikan yang sesuai.

Jangan mengubah pesan berhasil menjadi gagal untuk memunculkan tombol. Pengiriman ke Talk bersifat setidaknya sekali, sehingga hasil jaringan yang tidak pasti perlu ditinjau.

21. Kirim ulang massal dan hanya yang gagal

Batch membantu mengulang beberapa pesan gagal tanpa memilih satu per satu pada setiap putaran. Satu batch maksimal 10 pesan.

Area pemilihan batch; tombol tidak aktif ketika belum ada pesan gagal dipilih.

  1. Pada Pengiriman, pilih status Gagal lalu Terapkan filter.
  2. Centang pesan yang ingin ditindaklanjuti pada halaman ini. Pilih-semua mengambil maksimal 10 pesan yang memenuhi syarat; pesan webhook tidak tersedia untuk pemilihan massal.
  3. Klik Kirim ulang yang dipilih. Pantau ringkasan, progress, dan hasil masing-masing pesan. Gunakan Perbarui progres jika perlu.
  4. Setelah selesai, baca hasil gagal dan Tidak dijadwalkan. Penolakan penjadwalan perlu diperiksa terpisah, misalnya kuota atau keadaan pesan sudah berubah.
  5. Klik Kirim ulang yang masih gagal (N) untuk membuat batch baru dari pesan yang masih gagal. Pesan sukses atau masih diproses tidak diulang.
  6. Pilihan / batch baru menyiapkan pemilihan berikutnya. Lanjutkan proses batch digunakan hanya bila ditawarkan panel setelah proses terputus.

Hasil batch, kuota aplikasi, dan kuota administrator tetap berlaku. Tidak dijadwalkan berbeda dari pesan yang benar-benar sudah dicoba dan gagal. Tidak ada batch produksi yang dibuat untuk dokumentasi ini.

22. Riwayat batch, refresh, dan CSV

Riwayat batch hanya menampilkan batch milik akun Anda yang masih tersimpan. Hasil pesan mengikuti status terbaru, sehingga laporan dapat berubah setelah retry berikutnya.

Filter, unduhan CSV, kontrol refresh, dan ringkasan batch.

  1. Isi Dari tanggal dan Sampai tanggal dalam WITA, pilih aplikasi/status, lalu Terapkan filter. Tanggal mengacu pada waktu batch dibuat.
  2. Filter aplikasi memilih batch yang memuat aplikasi itu. Semua pesan dalam batch terpilih tetap masuk tampilan dan ekspor, termasuk aplikasi lain dalam batch tersebut.
  3. Baca Berhasil, Gagal, dan Masih diproses. Total lintas halaman dihitung per pesan per batch; pesan yang ada pada dua batch dihitung dua kali.
  4. Buka kartu batch untuk hasil setiap pesan. Buka progres & tindakan batch membawa Anda ke penanganan ulang.
  5. Unduh laporan CSV mencakup seluruh hasil filter, bukan hanya halaman terlihat. Batas 10.000 baris; persempit tanggal jika batas tercapai.
  6. Jeda menghentikan refresh otomatis; Perbarui sekarang mengambil kondisi terbaru. Interval 15 detik saat proses aktif dan 60 detik saat tenang.

Tab tersembunyi/offline menjeda pembaruan. Metadata batch disimpan hingga 30 hari, 25 batch per halaman. unavailable berarti riwayat pesan tidak tersedia, bukan sukses. CSV adalah potret saat diunduh; gunakan UTF-8 saat membukanya di Excel.

23. Pemberitahuan dan status dibaca

Pemberitahuan menyatukan hasil batch dan perubahan pemilik aplikasi. Status dibaca disimpan per akun SSO agar konsisten antarperangkat.

Panel pemberitahuan, filter, badge, dan tautan tindak lanjut.

  1. Klik Pemberitahuan. Pilih Semua, Belum dibaca, atau Sudah dibaca sesuai kebutuhan.
  2. Pada batch selesai, baca jumlah berhasil/gagal lalu buka detail atau kirim ulang yang gagal bila tersedia.
  3. Pada perubahan pemilik, periksa aplikasi, pemilik lama/baru, admin pelaksana, waktu, dan catatan. Buka riwayat pemilik menuju aplikasi tersebut.
  4. Gunakan Tandai sudah dibaca setelah ditinjau, atau Tandai belum dibaca lagi bila masih perlu tindak lanjut.
  5. Tandai semua sudah dibaca membersihkan status belum dibaca secara massal. Membuka/menutup panel saja tidak menandai pesan dibaca.

Hasil batch hanya untuk pembuat batch; perubahan pemilik terlihat oleh administrator. Pemberitahuan mencakup 30 hari terakhir dan maksimal 50 ditampilkan sesuai filter. Badge dibaca tidak sama dengan status pesan Talk sudah dibaca. Pemeriksaan otomatis dijeda ketika tab tersembunyi/offline.

24. Kelola pengguna dan hak administrator

Login Godigi tidak otomatis memberi hak pengelolaan. Akun baru muncul sebagai Non-register setelah berhasil login sekali.

Daftar pengguna saat dokumentasi hanya berisi akun administrator yang sedang login.

  1. Minta calon pengguna login panel dengan SSO. Ia belum dapat mengelola aplikasi sebelum disetujui.
  2. Administrator membuka Pengguna dan memeriksa identitas/ID SSO calon pengguna.
  3. Buka Tetapkan administrator pada akun yang benar, baca dampaknya, lalu Konfirmasi tetapkan admin.
  4. Pengguna perlu login kembali setelah persetujuan. Peran admin memberi akses penuh ke aplikasi, ruang, key, dan pengguna.
  5. Untuk mencabut, buka Cabut akses lalu Konfirmasi cabut akses. Akun menjadi Non-register dan seluruh sesi aktifnya berakhir.
  6. Periksa hasil perubahan di Aktivitas admin. Penetapan pemilik aplikasi tidak menggantikan proses persetujuan ini.

Panel mencegah pencabutan akses diri sendiri dan administrator terakhir. Tombol persetujuan hanya muncul pada baris akun lain yang memenuhi syarat.

25. Aktivitas admin dan penelusuran

Aktivitas administrator membantu menjawab siapa melakukan perubahan, kapan, dan terhadap objek apa.

Daftar 30 aktivitas terakhir pada panel.

  1. Buka Aktivitas admin. Cocokkan waktu WITA, ID admin, aktivitas, serta objek/detail perubahan.
  2. Contoh aktivitas: login/logout, application_created, destination_changed, user_approved, user_access_revoked, room_connected.
  3. Untuk laporan pemilik yang dapat difilter dan diekspor, gunakan Riwayat perubahan pemilik di kartu aplikasi.
  4. Untuk kegagalan kirim, gunakan Detail error & percobaan; untuk pengiriman massal gunakan Riwayat batch.
  5. Saat melapor masalah, catat URL halaman, waktu WITA, aplikasi, alias tujuan, ID pesan/batch, dan pesan error. Jangan sertakan kredensial.

Halaman audit menampilkan 30 aktivitas terbaru; bukan ekspor audit tanpa batas. Gunakan waktu dan objek aktivitas untuk membedakan pengujian terdahulu dari perubahan operasional terbaru.

26. Perintah chat untuk server Nextcloud

Ketik satu perintah per pesan di ruang yang dikonfigurasi untuk server tersebut. Semua perintah tanpa tanda /. Akses perintah dibatasi pada identitas Nextcloud Chaerollah, bukan sekadar nama tampilan.

Perintah Kegunaan
bantuan Daftar perintah dan cara penggunaan terkini.
ping Memeriksa balasan bot.
status Ringkasan kondisi server.
fail2ban Status proteksi Fail2ban.
nextcloud Ringkasan kondisi Nextcloud.
backup Informasi hasil/status backup; tidak menjalankan backup.
disk Informasi penggunaan penyimpanan.
  1. Buka ruang notifikasi server Nextcloud yang sudah terhubung. Mulai dengan bantuan.
  2. Ketik status atau perintah lain di tabel tanpa slash. Tunggu balasan sebelum mengulang.
  3. Jika data tidak tersedia atau kedaluwarsa, ikuti keterangan bot; jangan menafsirkannya sebagai server sehat.
  4. Gunakan hashtag seperti #fail2ban dan #nextcloud untuk membedakan notifikasi dalam ruang server yang sama.

Perintah ini hanya membaca kondisi. Tidak melakukan restart, update, ban/unban, atau menjalankan shell bebas. Hasil terlihat oleh semua anggota ruang. Menambahkan aplikasi/API key baru di panel tidak otomatis memasang agen perintah pada server baru.

27. Perintah pemeriksaan mailserver

Gunakan ruang Notifikasi Mailserver dan akun Chaerollah. bantuan adalah rujukan sintaks terkini. IP, EMAIL, DOMAIN, dan ID pada tabel adalah placeholder yang harus diganti; tanda berarti opsional, bukan diketik.

Sintaks Kegunaan
status; ping; fail2ban; disk Ringkasan layanan, balasan bot, proteksi, penyimpanan. Kirim satu per pesan.
pengguna; riwayat Informasi pengguna dan riwayat.
cek IP jam 1-72 jumlah log 1-5 Reputasi Spamhaus/AbuseIPDB, negara, ban, blacklist/whitelist, ringkasan login dan log.
akun EMAIL Pemeriksaan akun email.
diblokir; whitelist; daftartolak; pindai Pemeriksaan daftar dan hasil pemindaian.
antrean EMAIL|deferred halaman Daftar antrean sesuai filter.
detailantrean QUEUE-ID Detail satu item antrean.
caripengirim ALAMAT|DOMAIN Pencarian pengirim; dapat memerlukan beberapa menit.
authip IP jam; sasl IP jam Rincian autentikasi berdasarkan IP.
periksaemail MESSAGE-ID Pemeriksaan email.
spamhaus status; spamhaus cek REFERENSI Status dan pemeriksaan referensi Spamhaus.

cek dan logip mengarah ke pemeriksaan IP yang sama; gunakan cek sebagai perintah utama. Reputasi atau asal negara bukan bukti tunggal penyalahgunaan. Tinjau hasil dan log sebelum memilih tindakan. Integrasi Telegram tetap terpisah; hak admin Telegram tidak dikelola dari Talk.

28. Tindakan mailserver dengan konfirmasi

Semua tindakan perubahan harus ditinjau melalui pratinjau. Setelah sasaran dan dampaknya benar, balas konfirmasi KODE; untuk membatalkan, batal KODE. Kode berlaku 60 detik, sekali pakai, terikat akun dan ruang.

Sintaks Dampak
ban IP JAIL ALASAN Ban manual Fail2ban; durasi mengikuti jail.
unban IP JAIL Tanpa jail: melepas IP dari seluruh jail yang sedang membannya.
blacklist IP|CIDR DURASI ALASAN Blokir firewall manual; terpisah dari Fail2ban. Durasi: 30m, 12h, 7d, 2w, permanen.
unblacklist IP|CIDR Cabut blokir firewall manual, bukan ban Fail2ban.
izinkanip IP|CIDR CATATAN; cabutip IP|CIDR Tambah/cabut whitelist IP.
izinkandomain DOMAIN|EMAIL CATATAN; cabutdomain DOMAIN|EMAIL Tambah/cabut whitelist domain/email.
bukaakun EMAIL; tahanakun EMAIL; lepasakun EMAIL Buka lockout, tahan akun dan cabut sesi, atau lepas penahanan.
tahanantrean EMAIL; hapusantrean EMAIL Tahan antrean pengirim lokal; penghapusan hanya antrean HOLD.
hapusqueueid QUEUE-ID; hapusmassal MESSAGE-ID; hapusitem EMAIL ITEM-ID Hapus antrean atau item sesuai sasaran.
hapuspengirim ALAMAT|DOMAIN semua|palsu Mode wajib: semua, atau indikator DMARC gagal (palsu).
tolak DOMAIN|EMAIL|IP ALASAN; cabuttolak DOMAIN|EMAIL|IP Tambah/cabut penolakan SMTP, bukan ban Fail2ban.

Titik koma memisahkan sintaks; kirim satu perintah per pesan. Penghapusan email/antrean bisa permanen. Mode palsu bukan kepastian pemalsuan; salinan bukti pengirim hanya sampel, bukan backup lengkap. Jika hasil tindakan tidak pasti, periksa kondisi dahulu; jangan mengonfirmasi ulang secara buta.

29. Laporan eksternal, PDF, dan Markdown

Notifikasi mailserver memakai kategori #mailserver, #login, #fail2ban, #spam, #antrean, #layanan, dan #laporan. Pesan Talk diformat Markdown; konversi HTML Telegram dilakukan pada jalur Talk.

Fitur / sintaks Cara menggunakan
lapor IP kategori catatan Tinjau bukti dan kategori sebelum konfirmasi pelaporan AbuseIPDB. Tidak otomatis melakukan ban.
autolapor status|aktif|uji|nonaktif Lihat status atau kelola pelaporan otomatis; tindakan perubahan mengikuti konfirmasi.
spamhaus siapkan REFERENSI JENIS INDEKS KATEGORI Ikuti hasil pemeriksaan; tinjau pratinjau sebelum konfirmasi submission.
Lampiran PDF Buka file dari pesan Bot Laporan Mailserver di ruang Notifikasi Mailserver. Tidak perlu tautan publik.
  1. Untuk PDF baru, cari pesan berlabel #mailserver #laporan dan buka lampirannya. Notifikasi ketersediaan saja berbeda dari lampiran file yang benar-benar terkirim.
  2. Gunakan filter aplikasi mailserver di panel untuk meninjau notifikasi hasil pengiriman. Antrean file ditangani layanan PDF khusus, bukan endpoint pesan teks.
  3. Bila PDF belum masuk, catat nama laporan dan waktu. Minta operator memeriksa layanan PDF; API POST /v1/messages tidak menerima unggahan PDF.
  4. Format pesan: tebal, miring, daftar, tautan, dan blok kode untuk log. Hashtag membantu pengelompokan. Hindari HTML mentah pada API teks Talk.

Layanan PDF memeriksa laporan baru sekitar tiap 60 detik, maksimal 20 MiB per PDF. File dibagikan privat dengan izin baca; laporan lama tidak dikirim massal otomatis. Ketersediaan lampiran juga bergantung pada izin ruang/file. Isi percakapan dan laporan privat tidak disertakan dalam manual ini.

30. Pemecahan masalah

Mulai dari identitas, izin ruang, lalu status pengiriman. Bedakan error login panel, respons API, dan error dari Nextcloud Talk.

Gejala Langkah berikutnya
Non-register / akses ditolak Minta administrator meninjau ID SSO di Pengguna. Login ulang setelah persetujuan.
Sesi habis Selesaikan login SSO; kembali ke halaman/filter sebelumnya. Isi ulang formulir yang belum tersimpan.
Validasi formulir gagal Muat ulang halaman, pastikan cookie aktif, jangan kirim ulang formulir tab lama. Jika berulang, catat waktu/URL tanpa token.
Ruang tidak muncul Verifikasi akun, pastikan grup privat dan Anda moderator; perbarui daftar.
Bot 404 / status tidak pasti Periksa ruang masih ada, keanggotaan dan peran bot-room-manager. Jalankan Cek koneksi, lalu perbaiki jika berhak.
Tes panel berhasil, server 401 Key server salah/lama/dicabut. Tes panel tidak menggunakan key server.
API 400 / 413 Periksa JSON, panjang teks, idempotensi, dan ukuran body.
API 403 destination tidak diizinkan; cek GET /v1/destinations dan izin aplikasi.
API 404 ID tidak ditemukan atau milik aplikasi lain.
API 409 Idempotency-Key sama tetapi payload berbeda.
API 429 Kurangi frekuensi; retry setelah jeda. Cek status juga memakai kuota.
5xx / timeout Retry terbatas dengan ID/payload sama. Periksa apakah Talk sudah menerima sebelum mengulang.
Batch kosong / CSV kosong Periksa akun pembuat, filter tanggal/aplikasi/status, dan masa simpan 30 hari.
Perintah chat tidak dibalas Pastikan akun Chaerollah, ruang benar, tanpa slash, satu perintah; mulai bantuan. Key aplikasi baru tidak memasang agen perintah.

Informasi untuk eskalasi: waktu WITA, halaman, aplikasi, alias, ID pesan/batch, status/error, dan langkah sebelum masalah. Jangan menyertakan API key, password, OTP, cookie, atau isi konfigurasi rahasia.

31. Checklist operasional dan referensi

Gunakan checklist ini saat menyerahkan integrasi kepada pengelola server atau melakukan pemeriksaan berkala.

Alamat Kegunaan
https://bot.gorontaloprov.go.id/admin Panel administrator.
https://gocloud.gorontaloprov.go.id Nextcloud / Talk.
https://bot.gorontaloprov.go.id/healthz Health API notifikasi.
https://bot.gorontaloprov.go.id/admin/healthz Health panel untuk pendaftaran SSO: GET tanpa login, HTTP 200 ok.
https://bot.gorontaloprov.go.id/auth/callback Callback aplikasi Godigi, bukan Health Check URL.
  1. Akun SSO yang benar sudah disetujui; akun Nextcloud terverifikasi dan moderator ruang sesuai.
  2. Ruang privat terhubung; bot aktif; bot-room-manager moderator; peserta penerima sudah tepat.
  3. Aplikasi aktif dengan pemilik yang benar; alias sesuai; key tersimpan aman di server, tidak di dokumen.
  4. Tes panel berhasil dan uji dari server dengan API key juga berhasil; id/status dicatat.
  5. Idempotensi, retry terbatas, batas kuota, dan kategori hashtag sudah diterapkan.
  6. Pengelola memahami detail error, kirim ulang, batch, CSV, dan status pemberitahuan per akun.
  7. Untuk HP: buka/tutup Menu, gulir formulir, dan geser tabel bila kolom melebar. Jangan mengira tombol hilang sebelum memeriksa bagian bawah halaman.
  8. Setelah bekerja, logout panel pada perangkat bersama dan simpan laporan yang diperlukan sebelum masa retensi berakhir.

Dasar dokumen: panduan proyek edisi 21 November 2026, templates dan panduan integrasi panel, logika sesi/akses, serta grammar perintah Talk dalam repositori NextcloudBot. Health check bukan tes login SSO end-to-end. Tidak ada deployment, rotasi key, pengiriman tes, retry pesan, atau perubahan akses produksi dalam pekerjaan dokumentasi ini.

Rujukan dokumentasi

Panduan ini diadaptasi dari docs/panduan/Panduan-NextcloudBot.md pada proyek Nextcloud AIO, edisi 21 November 2026 (panel 0.27.0). Sumber pendukung: template dan panduan integrasi bot-admin, logika sesi panel, serta dokumentasi dan grammar perintah talk-status dan mailserver-talk. Contoh kode hanya menggunakan placeholder; sesuaikan alias dengan izin aplikasi Anda.

Perintah bantuan di ruang terkait dan Panduan integrasi pada panel menjadi rujukan sintaks operasional saat aplikasi berubah.