/notify

The /notify endpoint is the primary way to send notifications through Smooven. It supports both direct channel delivery and intent-based routing.

Endpoint

POST https://api.smooven.io/v1/agent/notify

Authentication

Header	Value
Authorization	Bearer YOUR_SECRET_KEY
Content-Type	application/json

Request body

Direct channel mode

{
  "channel": "sms",
  "to": "+61400000000",
  "message": "Your verification code is 482910",
  "sender_id": "MySender",
  "callback_url": "https://your-server.com/webhooks"
}

Intent-based mode

{
  "intent": "Remind Sarah about her appointment tomorrow at 2pm",
  "urgency": "normal",
  "context": {
    "user_id": "sarah@example.com",
    "appointment_id": "apt_123"
  },
  "callback_url": "https://your-server.com/webhooks"
}

Parameters

Parameter	Type	Required	Description
channel	string	Conditional	Channel to use: sms, rcs, push, email, inapp. Required if intent is not set.
to	string	Conditional	Recipient identifier (phone number, email, or player ID). Required if intent is not set.
message	string	Conditional	Message content. Required for SMS.
intent	string	Conditional	Natural language intent description. Required if channel is not set.
urgency	string	No	low, normal, high, critical. Default: normal
context	object	Conditional	Structured data for intent processing. Must include user_id for intent-based mode.
preferred_channel	string	No	Hint for intent-based mode. Smooven may override.
callback_url	string	No	Webhook URL for delivery status updates
sender_id	string	No	Custom sender identifier (SMS, email)
rcs	object	No	RCS-specific options (cards, buttons)
push	object	No	Push-specific options (title, body, deep link)
email	object	No	Email-specific options (from, subject, html, template)
inapp	object	No	In-app specific options (type, title, body, action)

Response

Success (200)

{
  "success": true,
  "notification_id": "ntf_abc123def456",
  "channel_used": "sms",
  "status": "queued",
  "timestamp": "2026-03-05T08:00:00Z"
}

Error (400/401/429)

{
  "success": false,
  "error": {
    "code": "invalid_recipient",
    "message": "The phone number +614000 is not in valid E.164 format"
  }
}

Error codes

Code	HTTP Status	Description
invalid_recipient	400	Recipient identifier is invalid or missing
invalid_channel	400	Requested channel is not supported
missing_content	400	No message content or intent provided
unauthorized	401	Invalid or missing API key
rate_limited	429	Too many requests. Check Retry-After header.
quota_exceeded	429	Monthly message limit reached for your plan
internal_error	500	Unexpected server error. Contact support.

Rate limits

Plan	Requests per second
Developer	10
Growth	50
Business	200
Enterprise	Custom