Integration API

Integration API memungkinkan sistem eksternal membuat, membaca, memperbarui, dan menghapus reminder item secara terprogram. Ini adalah jalur yang tepat bila reminder dibuat oleh layanan backend, CRM, atau sistem apa pun di luar percakapan agent.

Autentikasi

Semua request Integration API membutuhkan query parameter secret. Nilainya harus sama dengan Primary Key atau Secondary Key milik konfigurasi tujuan.

?secret={primaryKey or secondaryKey}

Primary key dan secondary key dibuat saat konfigurasi dibuat dan dapat diperbarui secara terpisah. Memakai dua key memungkinkan rotasi key tanpa downtime: perbarui pemanggil satu per satu ke key baru sebelum mencabut key lama.

Lihat Plugin Setup untuk detail pembuatan dan refresh key.

Pola Base URL

Semua endpoint Integration API mengikuti pola berikut:

/api/reminder/{agentId}/{configurationId}/{reminderId}?secret={key}

Segmen	Deskripsi
`agentId`	ID agent pemilik konfigurasi ini.
`configurationId`	ID instance konfigurasi plugin.
`reminderId`	Identifier unik untuk reminder. Ditentukan oleh pemanggil, bukan dibuat oleh server.

Membuat Reminder

POST /api/reminder/{agentId}/{configurationId}/{reminderId}?secret={key}

Request body:

Field	Tipe	Wajib	Deskripsi
`countryCode`	string	Ya	Kode telepon internasional, misalnya `+62`.
`phoneNumber`	string	Ya	Nomor telepon penerima tanpa kode negara.
`recipientName`	string	Tidak	Nama tampilan untuk keperluan logging.
`notificationTemplateName`	string	Ya	Identifier template di akun messaging.
`templateParameters`	string[]	Ya	Nilai untuk placeholder template, sesuai urutan.
`sendTimes`	datetime[]	Ya	Satu atau beberapa waktu pengiriman terjadwal. Minimal satu wajib diisi.
`timezone`	string	Tidak	Zona waktu untuk menafsirkan `sendTimes`. Default-nya `UTC`.

Contoh:

{
  "countryCode": "+62",
  "phoneNumber": "81234567890",
  "recipientName": "Ani Wijaya",
  "notificationTemplateName": "loan_payment_reminder",
  "templateParameters": ["Rp 1.500.000", "31 Mei 2025"],
  "sendTimes": [
    "2025-05-29T08:00:00+07:00",
    "2025-05-31T08:00:00+07:00"
  ],
  "timezone": "Asia/Jakarta"
}

Memperbarui Status Reminder

PUT /api/reminder/{agentId}/{configurationId}/{reminderId}?secret={key}

Gunakan endpoint ini untuk mengubah status reminder yang sudah ada dari sistem eksternal.

Request body:

Field	Tipe	Deskripsi
`date`	datetime	Timestamp perubahan status.
`status`	string	Status baru: `active`, `completed`, `expired`, atau `cancelled`.

Contoh:

{
  "date": "2025-05-30T10:00:00Z",
  "status": "cancelled"
}

Ini berguna ketika kejadian yang mendasarinya (misalnya pembayaran atau janji temu) sudah selesai di sistem eksternal Anda sebelum reminder dikirim. Membatalkannya mencegah pengiriman yang tidak perlu.

Menghapus Reminder

DELETE /api/reminder/{agentId}/{configurationId}/{reminderId}?secret={key}

Menghapus reminder item secara permanen. Tidak ada response body yang dikembalikan jika berhasil.

Mengambil Reminder

GET /api/reminder/{agentId}/{configurationId}/{reminderId}?secret={key}

Mengembalikan reminder item lengkap, termasuk semua field, status, waktu kirim, dan history.

Contoh response:

{
  "id": "rem-abc123",
  "countryCode": "+62",
  "phoneNumber": "81234567890",
  "recipientName": "Ani Wijaya",
  "notificationTemplateName": "loan_payment_reminder",
  "templateParameters": ["Rp 1.500.000", "31 Mei 2025"],
  "sendTimes": ["2025-05-29T08:00:00+07:00", "2025-05-31T08:00:00+07:00"],
  "timezone": "Asia/Jakarta",
  "status": "active",
  "nextSendTime": "2025-05-29T01:00:00Z",
  "lastSendTime": null,
  "lastAttempts": 0,
  "history": [
    {
      "date": "2025-05-28T14:00:00Z",
      "action": "Created",
      "detail": "Reminder created via Integration API",
      "status": "active"
    }
  ]
}

Penanganan Error

Skenario	Response
`secret` tidak valid atau tidak ada	`401 Unauthorized`
`agentId` atau `configurationId` tidak ditemukan	`404 Not Found`
`reminderId` tidak ditemukan (pada GET/PUT/DELETE)	`404 Not Found`
Request body tidak valid	`400 Bad Request` beserta detail error

Halaman Terkait

Plugin Setup: cara mendapatkan dan memperbarui integration key.
Create Reminder Items: membuat reminder lewat UI admin.
Webhook Notifications: menerima callback saat reminder terkirim.
Reminder Overview

PreviousAI Function Tool

NextProcessing and Delivery