Intent-Based Notifications

Intent-based notifications let your AI agent describe what it wants to achieve in natural language. Smooven interprets the intent, composes the message, selects the best channel, and delivers it.

Anatomy of an intent request

POST /v1/agent/notify
{
  "intent": "Remind Sarah about her dentist appointment tomorrow at 10am",
  "urgency": "normal",
  "context": {
    "user_id": "sarah@example.com",
    "appointment_type": "dental checkup",
    "location": "123 Health St, Sydney"
  }
}

Parameters

Parameter	Type	Required	Description
intent	string	Yes	Natural language description of the notification goal
urgency	string	No	low, normal, high, or critical. Affects channel selection and delivery priority. Default: normal
context	object	Yes	Key-value pairs providing structured data. Must include user_id.
preferred_channel	string	No	Suggest a channel without forcing it. Smooven may override if the channel is unavailable.
callback_url	string	No	Webhook URL for delivery status updates

How Smooven processes intents

1. Parse: extract the action (remind), target (Sarah), content (dentist appointment tomorrow at 10am), and any structured data from context
2. Resolve user: look up “sarah@example.com” in the player registry to find available channels
3. Select channel: evaluate available channels against urgency, user preferences, device state, and cost
4. Compose message: generate appropriate content for the selected channel (SMS gets a short text, email gets a formatted message, push gets a notification card)
5. Deliver: send via the selected channel with automatic retry and fallback

Urgency levels and channel selection

Urgency	Preferred channels	Behaviour
low	Push, In-App, Email	Non-intrusive. Batched if possible.
normal	Push, SMS, Email	Standard delivery. Falls back across channels.
high	SMS, Push, RCS	Immediate delivery. Multiple channels if first attempt is slow.
critical	SMS + Push (simultaneously)	Delivered on all available channels. No batching.

Examples

E-commerce order update

{
  "intent": "Tell the customer their order ORD-5678 has shipped and will arrive on Friday",
  "urgency": "normal",
  "context": {
    "user_id": "customer_456",
    "order_id": "ORD-5678",
    "tracking_url": "https://example.com/track/5678"
  }
}

Security alert

{
  "intent": "Warn the user that a new device logged into their account from Melbourne",
  "urgency": "high",
  "context": {
    "user_id": "user_789",
    "device": "Chrome on Windows",
    "location": "Melbourne, AU",
    "ip": "203.0.113.42"
  }
}

Team collaboration

{
  "intent": "Notify the project team that the deployment to production completed successfully",
  "urgency": "low",
  "context": {
    "team_id": "eng-team",
    "service": "checkout-api",
    "version": "2.4.1",
    "environment": "production"
  }
}