Overview
Omi supports two types of notifications you can send to users:Direct Notifications
Send immediate, exact-text messages to specific users
Proactive Notifications
AI-generated contextual messages based on real-time conversations
Direct Flow
Proactive Flow
Direct Notifications
Send immediate messages to specific users. Perfect for alerts, updates, and responses to user actions.Use Cases
Use Cases
- Task reminders and event notifications
- Service updates or changes
- Real-time alerts and warnings
- Responses to user queries
- New feature announcements
API Reference
| Setting | Value |
|---|---|
| Method | POST |
| URL | https://api.omi.me/v2/integrations/{app_id}/notification |
| Auth | Bearer <YOUR_APP_SECRET> |
| Parameter | Required | Description |
|---|---|---|
uid | Yes | Target user’s Omi ID |
message | Yes | Notification text |
Implementation
Get Credentials
You’ll need your App ID and App Secret from the Omi developer portal.
Send Notification
Make a POST request with the user ID and message:
Handle Response
Check the response status code to confirm delivery.
Code Examples
- Node.js
- Python
Proactive Notifications
Context-aware, AI-generated notifications that leverage user data during real-time conversations. You provide a prompt template, Omi generates the personalized message.Unlike direct notifications, proactive notifications require an app with specific capabilities and user-granted permissions.
Use Cases
Use Cases
- Real-time mentoring advice during meetings
- Context-aware suggestions based on conversation topics
- Personalized insights based on user’s goals
- Intelligent responses to specific phrases
- Meeting action item reminders
How It Works
How It Works
- User installs your app and grants permissions
- During conversations, Omi sends transcripts to your webhook
- Your webhook analyzes the transcript and returns a prompt template
- Omi fills in user context (name, facts, etc.) and generates the notification
- User receives a personalized, contextual notification
App Configuration
Your app needs these capabilities:Available Scopes
| Scope | Template Variable | Description |
|---|---|---|
user_name | {{user_name}} | User’s display name |
user_facts | {{user_facts}} | Known facts about the user |
user_context | {{user_context}} | Relevant conversation context |
user_chat | {{user_chat}} | Recent chat history with your app |
Webhook Implementation
Your webhook receives real-time transcripts and returns notification prompts: Incoming Request:Complete Example
- Python (FastAPI)
- Node.js (Express)
Testing
Enable Developer Mode
Open Omi app → Settings → Developer Mode
Install Your App
Install your app in Developer Mode and grant requested scopes
Set Webhook URL
Configure your webhook URL in Developer Settings
Trigger Notifications
Start a conversation and say trigger phrases (e.g., “what do you think?”)
Verify
Notification should appear within 30 seconds
Rate Limit: 1 proactive notification per user per app every 30 seconds.
Best Practices
Rate Limiting
- Implement delays between notifications
- Avoid duplicate messages
- Group related notifications
Content Quality
- Keep messages concise and clear
- Include relevant context
- Use appropriate urgency levels
Error Handling
- Implement retry with exponential backoff
- Log errors for debugging
- Monitor delivery status
Security
- Store credentials securely
- Validate user IDs before sending
- Use HTTPS for all endpoints
Troubleshooting
Error Codes
| Code | Meaning | Solution |
|---|---|---|
| 401 | Unauthorized | Verify API credentials and Bearer token format |
| 404 | User not found | Check that user ID exists and has your app installed |
| 429 | Rate limited | Implement rate limiting with exponential backoff |
| 500 | Server error | Retry with backoff, check Omi status page |
Direct Notifications Not Sending
Direct Notifications Not Sending
Check these:
- API credentials are correct
- User ID is valid
- Bearer token is properly formatted
- Request includes required headers
Proactive Notifications Not Appearing
Proactive Notifications Not Appearing
Check these:
- App has
proactive_notificationcapability enabled - User has installed your app
- User has granted requested scopes
- Webhook is returning proper response format
- Prompt is at least 5 characters
Notifications Not Contextual
Notifications Not Contextual
Solutions:
- Request additional scopes in app configuration
- Include more template variables in your prompt
- Make prompts more specific about using the context