Scheduled messages

Schedule, list, edit and cancel one-time reminders to your own Slack DM over the API.

A scheduled message is a one-time reminder that nima sends to your own Slack DM at a time you choose. You save the exact text and the send time now. At that time nima posts the saved text as a plain direct message from the nima bot to your linked Slack account. Nothing is researched, run or rewritten later, and a reminder never goes to a channel or to another person.

On for every workspace. A reminder needs your Slack account linked to nima in the workspace; without the link, scheduling fails with 400. Scheduled messages do not depend on the workspace triggersEnabled setting that watches need. For the concept, see Watches and reminders.

Operations for scheduled messages

Method	Path	Scope	MCP tool
`GET`	`/v1/scheduled-messages/context`	`subscriptions:read`	`get_scheduling_context`
`POST`	`/v1/scheduled-messages`	`subscriptions:write`	`schedule_message`
`GET`	`/v1/scheduled-messages`	`subscriptions:read`	`list_scheduled_messages`
`PATCH`	`/v1/scheduled-messages/{id}`	`subscriptions:write`	`update_scheduled_message`
`DELETE`	`/v1/scheduled-messages/{id}`	`subscriptions:write`	`cancel_scheduled_message`

Paths are relative to https://api.getnima.io. Every call carries Authorization: Bearer <your key> and needs the scope in the table. The routes are personal: you only ever see and change your own reminders. Another person's reminder id answers 404, exactly like a missing one. Every call also re-checks that you are still an owner, admin or member of the workspace; if not, it answers 403 INSUFFICIENT_PERMISSIONS. See Scopes and permissions and Errors.

Get the scheduling context

GET/v1/scheduled-messages/context

scopesubscriptions:readMCP toolget_scheduling_context

Returns the current time, a suggested time zone and whether your Slack account is linked. Call it before you schedule, so you can confirm the zone with the person instead of guessing.

nowstring

The server time, ISO 8601 UTC.

suggestedTimeZonestring

An IANA zone. nima takes it from your Slack profile time zone (cached for 24 hours) and falls back to UTC when Slack does not answer. It is a suggestion, not a setting: nima has no per-user time zone, so confirm it.

slackConnectedboolean

true when the workspace has a Slack install and your account is mapped to a Slack user. Scheduling needs true.

guidancestring

A short reminder to confirm the zone and ask for a clock time when only a date is given.

Schedule a message

POST/v1/scheduled-messages

scopesubscriptions:writeMCP toolschedule_message

Saves a one-time reminder and returns it in state pending. The request is idempotent per requestKey: send the same key when you retry.

requestKeystringrequired

A stable idempotency key you choose, 1 to 128 characters. Reuse it on a retry.

messagestringrequired

The exact text to send, 1 to 12,000 characters after trimming leading and trailing whitespace. It is otherwise sent as written.

sendAtstringrequired

ISO 8601 datetime with a UTC offset, for example 2026-10-05T09:00:00+03:00. It must be in the future and no more than 366 days ahead.

timeZonestringrequired

A confirmed IANA zone, 1 to 100 characters, such as Asia/Jerusalem. nima checks it is a real zone and uses it to render localDeliveryTime.

Unknown fields are rejected. The response is a ScheduleDto.

A retry with the same requestKey returns the original reminder, even after its due time. Reusing a requestKey with a different message, sendAt or timeZone answers 409; edit the reminder by id instead.

Errors when scheduling

Status	`error`	When
`400`	`VALIDATION_ERROR`	The body does not match the schema. `details.issues` names the field.
`400`	`VALIDATION_ERROR`	"Choose a future time within the next 366 days": `sendAt` is in the past or more than 366 days out.
`400`	`VALIDATION_ERROR`	"Choose a valid IANA timezone".
`400`	`VALIDATION_ERROR`	"Link your Slack account in this workspace before scheduling a message".
`403`	`INSUFFICIENT_PERMISSIONS`	Your role no longer allows managing reminders, or the key lacks `subscriptions:write`.
`409`	`CONFLICT`	You already have 100 pending reminders. Cancel one first.
`409`	`CONFLICT`	The `requestKey` already belongs to a different reminder.
`409`	`CONFLICT`	Scheduled messages are switched off platform-wide (an operator kill switch; on today).

request

curl -X POST https://api.getnima.io/v1/scheduled-messages \
  -H "Authorization: Bearer $NIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestKey": "renewal-call-2026-10-05",
    "message": "Send the renewal quote to Northwind before the 2pm call.",
    "sendAt": "2026-10-05T09:00:00+03:00",
    "timeZone": "Asia/Jerusalem"
  }'

response

{
  "id": "3f0c8d52-7f3b-4a4e-9c61-0d2f5a8e1b47",
  "message": "Send the renewal quote to Northwind before the 2pm call.",
  "sendAt": "2026-10-05T06:00:00.000Z",
  "localDeliveryTime": "Monday, 5 October 2026 at 09:00:00 GMT+3",
  "timeZone": "Asia/Jerusalem",
  "state": "pending",
  "version": 1,
  "delivery": "slack_dm",
  "sentAt": null,
  "failureReason": null,
  "createdAt": "2026-09-30T12:14:03.000Z"
}

List scheduled messages

GET/v1/scheduled-messages

scopesubscriptions:readMCP toollist_scheduled_messages

Returns your own reminders as an array of ScheduleDto, at most 200. Pending reminders come first, ordered by sendAt ascending. Every other reminder (delivering, sent, cancelled, failed and uncertain) follows, latest sendAt first. The 200 cap covers both groups together. There are no query parameters and no pagination.

Read id and version from this list before you edit or cancel a reminder. A reminder in state uncertain may or may not have reached Slack: check Slack before you tell anyone it was sent.

Edit a scheduled message

PATCH/v1/scheduled-messages/{id}

scopesubscriptions:writeMCP toolupdate_scheduled_message

Changes the text, time or time zone of a reminder that is still pending, and returns it with version increased. The new time is validated again with the same rules as scheduling.

versionintegerrequired

The current version from the list, 1 or more. It stops you overwriting a change made in between.

messagestring

New text, 1 to 12,000 characters.

sendAtstring

New send time, ISO 8601 with a UTC offset, future and within 366 days.

timeZonestring

New confirmed IANA zone.

Fields you omit keep their current value. Unknown fields are rejected. The MCP tool takes the same fields plus id.

Errors when editing

Status	`error`	When
`400`	`VALIDATION_ERROR`	The body does not match the schema, or the new time or zone is invalid.
`403`	`INSUFFICIENT_PERMISSIONS`	Your role no longer allows managing reminders, or the key lacks `subscriptions:write`.
`404`	`RESOURCE_NOT_FOUND`	The id does not exist or is not yours.
`409`	`CONFLICT`	The reminder is no longer `pending`, delivery has started, or `version` is stale. List reminders again before editing.
`409`	`CONFLICT`	Scheduled messages are switched off platform-wide (on today).

request

curl -X PATCH https://api.getnima.io/v1/scheduled-messages/3f0c8d52-7f3b-4a4e-9c61-0d2f5a8e1b47 \
  -H "Authorization: Bearer $NIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1, "sendAt": "2026-10-05T08:30:00+03:00" }'

Cancel a scheduled message

DELETE/v1/scheduled-messages/{id}

scopesubscriptions:writeMCP toolcancel_scheduled_message

Cancels a pending reminder. It answers 200 with the reminder in state cancelled, not 204, and the row stays in your list as history. Cancelling an already cancelled reminder returns it unchanged.

Errors when cancelling

Status	`error`	When
`403`	`INSUFFICIENT_PERMISSIONS`	Your role no longer allows managing reminders, or the key lacks `subscriptions:write`.
`404`	`RESOURCE_NOT_FOUND`	The id does not exist or is not yours.
`409`	`CONFLICT`	The reminder is no longer `pending` (delivering, sent, failed or uncertain) or changed in between, so cancellation was not confirmed.

The schedule object

Every operation except the context call returns a ScheduleDto (the list returns an array of them).

idstring

The reminder id, a UUID.

messagestring

The saved text.

sendAtstring

The send time, ISO 8601 UTC.

localDeliveryTimestring

The same moment written out in timeZone, for showing back to a person.

timeZonestring

The IANA zone you gave.

stateenum

One of the states below.

versioninteger

Starts at 1 and increases with each edit. Send it back when editing.

deliverystring

Always slack_dm.

sentAtstring | null

When Slack confirmed the post, otherwise null.

failureReasonstring | null

Why a reminder ended failed or uncertain, otherwise null.

createdAtstring

When the reminder was saved, ISO 8601 UTC.

Scheduled message states

A scheduled message moves pending to delivering to sent, failed or uncertain, or from pending to cancelled. Only pending reminders can be edited or cancelled.

State	Meaning
`pending`	Waiting for `sendAt`. The only state you can edit or cancel.
`delivering`	A worker has claimed it and is posting. Edit and cancel answer `409`.
`sent`	Slack confirmed the post. `sentAt` is set.
`cancelled`	Cancelled before delivery.
`failed`	Not sent. `failureReason` says why, for example `membership_or_permission_revoked` when you lost access before the send, or a refusal such as `no_installation`, `not_a_member` or `not_mapped` when the Slack link is missing.
`uncertain`	Delivery could not be confirmed: the Slack post failed (`post_failed`) or a worker stopped mid-delivery (`delivery_interrupted`). nima never resends an uncertain reminder, so it cannot arrive twice.

Delivery timing and limits for scheduled messages

nima checks for due reminders every 60 seconds, so a reminder arrives within about a minute of sendAt. Each check queues at most 100 due reminders, and any beyond that go out on the next check. Each due reminder is delivered as its own job. The Slack post itself is attempted once: a job that fails before the post is retried up to 3 times, and a failed post ends uncertain rather than being retried. A reminder stuck in delivering for more than 5 minutes becomes uncertain.

Limit	Value
Pending reminders per person	100
Furthest `sendAt`	366 days ahead
Message length	12,000 characters
Reminders returned by the list	200
Destination	Your own linked Slack DM only. Not channels, other people or email.
Recurrence	None. Each reminder is sent once.