Docs/Using Plugins/Integration API

Integration API

The Integration API allows external systems to create, read, update, and delete reminder items programmatically. This is the appropriate path when reminders are created by a backend service, a CRM, or any system outside of an agent conversation.

Authentication

All Integration API requests require a secret query parameter. The value must match either the Primary Key or the Secondary Key of the target configuration.

?secret={primaryKey or secondaryKey}

Primary and secondary keys are generated when the configuration is created and can be refreshed independently. Using two keys allows key rotation without downtime: update one caller at a time to the new key before revoking the old one.

See Plugin Setup for key generation and refresh details.

Base URL Pattern

All Integration API endpoints follow this pattern:

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

Segment	Description
`agentId`	The ID of the agent that owns this configuration.
`configurationId`	The ID of the plugin configuration instance.
`reminderId`	A unique identifier for the reminder. Supplied by the caller, not generated by the server.

Create a Reminder

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

Request body:

Field	Type	Required	Description
`countryCode`	string	Yes	International dialing code, e.g. `+62`.
`phoneNumber`	string	Yes	Recipient phone number without the country code.
`recipientName`	string	No	Display name for logging purposes.
`notificationTemplateName`	string	Yes	The template identifier in the messaging account.
`templateParameters`	string[]	Yes	Values for the template placeholders in order.
`sendTimes`	datetime[]	Yes	One or more scheduled delivery times. Minimum one required.
`timezone`	string	No	Timezone for interpreting `sendTimes`. Defaults to `UTC`.

Example:

{
  "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"
}

Update Reminder Status

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

Use this endpoint to change the status of an existing reminder from an external system.

Request body:

Field	Type	Description
`date`	datetime	The timestamp of the status change.
`status`	string	The new status: `active`, `completed`, `expired`, or `cancelled`.

Example:

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

This is useful when the underlying event (e.g., a payment or appointment) is resolved in your external system before the reminder fires — cancelling it prevents unnecessary delivery.

Delete a Reminder

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

Permanently removes the reminder item. No response body is returned on success.

Get a Reminder

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

Returns the full reminder item including all fields, status, send times, and history.

Response example:

{
  "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"
    }
  ]
}

Error Handling

Scenario	Response
Invalid or missing `secret`	`401 Unauthorized`
`agentId` or `configurationId` not found	`404 Not Found`
`reminderId` not found (on GET/PUT/DELETE)	`404 Not Found`
Invalid request body	`400 Bad Request` with error details

Plugin Setup — how to obtain and refresh integration keys.
Create Reminder Items — creating reminders via the admin UI.
Webhook Notifications — receive callbacks when reminders are delivered.
Reminder Overview

PreviousAI Function Tool

NextProcessing and Delivery