Overview Interactive notifications display a message with clickable buttons. Users respond directly in Slack or Teams, and you can track responses via polling or callbacks.
Common use cases:
Deployment approvals
Incident acknowledgement
Shift confirmations
Survey questions
Endpoint Request body Include the response_request field alongside the standard notification fields.
The prompt shown above the buttons. Maximum 4000 characters.
Your correlation ID. Maximum 200 characters.
Configures the interactive behavior. Show response_request fields
2 to 5 response buttons. Each option has:
text (string, 1-75 chars) — Button label shown to the uservalue (string, 1-100 chars) — Machine-readable value returned in responses response_request.timeout_minutes
Minutes before the request expires. Range: 1-1440 (24 hours). After expiry, unresponded users are marked as expired and buttons are disabled.
response_request.disable
string
default: "onUserAction"
When to disable buttons for a given user:
onUserAction — Buttons are disabled immediately after the user clicks. The request completes when all users have responded or the timeout is reached.onTimeout — Buttons remain active until timeout. Users can change their response. Final values are captured at expiry. response_request.callback_url
HTTPS URL to receive a POST with the final results when the request completes. Must be publicly reachable. Validated on submission (DNS resolution, HTTPS required, no private IPs). See Callbacks . Response Unique identifier for this notification request. Use it to check status . { "status" : "ok" , "request_id" : "req_a1b2c3d4e5f6..." }
Example: deployment approval curl -X POST https://app.nextks.com/api/notify \ -H "Content-Type: application/json" \ -H "X-API-Key: nks_abc123..." \ -d '{ "user_emails": ["[email protected] "], "message": "Release v2.4.1 is ready.\nChanges: 3 bug fixes, 1 new feature.\n\nDeploy to production?", "external_reference_id": "deploy-v2.4.1", "response_request": { "options": [ { "text": "Approve", "value": "approve" }, { "text": "Reject", "value": "reject" }, { "text": "Delay 1h", "value": "delay" } ], "timeout_minutes": 60, "callback_url": "https://ci.company.com/hooks/nextks" } }'
Message appearance The notification renders as:
Message text — Your message content with markdown formattingResponse buttons — One button per optionFooter — Shows validity period and sender name (e.g., “Valid for 1h. Sent by Alice via Notifications API.” )
After a user responds (in onUserAction mode), the message is updated to show their choice and the buttons are removed.
Disable modes onUserAction (default)
onTimeout
Buttons disable immediately when the user clicks
The user’s choice is final
Request completes when all users respond or timeout is reached
Best for: approvals, acknowledgements — one-shot decisions
Buttons stay active until timeout
Users can click multiple times; only the last response counts
All responses are captured at timeout
Best for: polls, surveys — allow users to change their mind
