Notifications

Types of Notifications 📬

1. 📱 Direct Text Notifications

Direct text notifications allow you to send immediate messages to specific OMI users. This is useful for alerts, updates, or responses to user actions.

Example Use Cases

Send task reminders and event notifications
Notify users about service updates or changes
Deliver real-time alerts and warnings
Respond to user queries or actions
Announce new features or important changes

2. 🎯 Proactive Notifications

Proactive notifications are context-aware, AI-generated messages that leverage user data to send personalized, intelligent notifications during real-time conversations. Unlike direct notifications where you send the exact message text, proactive notifications let you provide a prompt template and Omi generates the final message based on user context.

Example Use Cases

Provide real-time mentoring advice during meetings
Suggest relevant information based on conversation topics
Offer context-aware reminders
Send personalized insights based on user’s goals and history
Trigger intelligent responses to specific conversation patterns

Implementing Notifications 🛠️

Step 1: Set Up Authentication 🔑

Before sending notifications, you’ll need:

Your OMI App ID (app_id)
Your OMI App Secret (API Key)

Store these securely as environment variables:

OMI_APP_ID=your_app_id_here
OMI_APP_SECRET=your_app_secret_here

Step 2: Configure Your Endpoint 🔌

Base URL and Endpoint

* **Method:** `POST`
* **URL:** `/v2/integrations/{app_id}/notification`
* **Base URL:** `api.omi.me`

Required Headers

* **Authorization:** `Bearer <YOUR_APP_SECRET>`
* **Content-Type:** `application/json`
* **Content-Length:** `0`

Query Parameters

* `uid` (string, **required**): The target user's OMI ID
* `message` (string, **required**): The notification text

Step 3: Implement the Code 💻

Here’s a complete Node.js implementation:

const https = require('https');

/**
 * Sends a direct notification to an Omi user.
 * @param {string} userId - The Omi user's unique ID
 * @param {string} message - The notification text
 * @returns {Promise<object>} Response data or error
 */
function sendOmiNotification(userId, message) {
    const appId = process.env.OMI_APP_ID;
    const appSecret = process.env.OMI_APP_SECRET;

    if (!appId) throw new Error("OMI_APP_ID not set");
    if (!appSecret) throw new Error("OMI_APP_SECRET not set");

    const options = {
        hostname: 'api.omi.me',
        path: `/v2/integrations/${appId}/notification?uid=${encodeURIComponent(userId)}&message=${encodeURIComponent(message)}`,
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${appSecret}`,
            'Content-Type': 'application/json',
            'Content-Length': 0
        }
    };

    return new Promise((resolve, reject) => {
        const req = https.request(options, (res) => {
            let data = '';
            res.on('data', chunk => data += chunk);
            res.on('end', () => {
                if (res.statusCode >= 200 && res.statusCode < 300) {
                    try {
                        resolve(data ? JSON.parse(data) : {});
                    } catch (e) {
                        resolve({ raw: data });
                    }
                } else {
                    reject(new Error(`API Error (${res.statusCode}): ${data}`));
                }
            });
        });
        req.on('error', reject);
        req.end();
    });
}

Step 4: Test Your Implementation 🧪

Set up your environment variables:

export OMI_APP_ID="your_app_id"
export OMI_APP_SECRET="your_app_secret"

Test with a sample notification:

sendOmiNotification("user_id_here", "Test notification!")
    .then(response => console.log("Success:", response))
    .catch(error => console.error("Error:", error));

Verify the notification appears in the user’s OMI app

Best Practices 🎯

Rate Limiting
- Implement reasonable delays between notifications
- Avoid sending duplicate notifications
- Group related notifications when possible
Content Guidelines
- Keep messages concise and clear
- Include relevant context
- Use appropriate urgency levels
Error Handling
- Implement retry logic for failed attempts
- Log errors for debugging
- Monitor notification delivery status
Security
- Store API credentials securely
- Validate user IDs before sending
- Implement request timeouts

Troubleshooting 🔍

Common Issues

Authentication Errors
- Verify your API credentials
- Check the Bearer token format
- Ensure environment variables are set
Delivery Issues
- Validate the user ID exists
- Check message encoding
- Verify network connectivity
Rate Limiting
- Monitor API response headers
- Implement exponential backoff
- Track notification frequency

Error Response Codes

Status Code	Meaning	Action
401	Unauthorized	Check API credentials
404	User not found	Verify user ID
429	Too many requests	Implement rate limiting
500	Server error	Retry with backoff

Example Implementations 💡

1. Task Reminder

function sendTaskReminder(userId, taskName, dueDate) {
    const message = `Reminder: "${taskName}" is due ${dueDate}`;
    return sendOmiNotification(userId, message);
}

2. Service Update

function sendServiceUpdate(userId, serviceName, status) {
    const message = `${serviceName} status: ${status}`;
    return sendOmiNotification(userId, message);
}

Implementing Proactive Notifications 🔔

Proactive notifications require creating an OMI app with specific capabilities. Unlike direct notifications, these leverage the app system to access user context and generate intelligent, personalized messages.

Step 1: Create Your OMI App 🔑

First, create an app in the OMI App Store with the following configuration: Required Capabilities:

external_integration - Enables real-time transcript webhooks
proactive_notification - Allows sending AI-generated contextual notifications

Example App Configuration:

{
  "name": "Your App Name",
  "description": "App description",
  "capabilities": ["external_integration", "proactive_notification"],
  "external_integration": {
    "triggers_on": "transcript_processed",
    "webhook_url": "https://yourapp.com/webhook"
  },
  "proactive_notification": {
    "scopes": ["user_name", "user_facts", "user_context", "user_chat"]
  }
}

Available Scopes:

Scope	Template Variable	Description
`user_name`	`{{user_name}}`	User’s name
`user_facts`	`{{user_facts}}`	User’s known facts
`user_context`	`{{user_context}}`	Relevant conversation context
`user_chat`	`{{user_chat}}`	Recent chat history with app

Important: Users must install your app from the OMI App Store and grant the requested scopes before you can send them proactive notifications.

Step 2: Set Up Your Webhook Server 🔌

Your app’s webhook endpoint receives real-time transcripts during conversations. When you want to send a notification, return a notification prompt in your webhook response. Webhook receives:

POST /your-webhook?session_id={session_id}&uid={user_id}

Request includes:

session_id: Unique conversation identifier
segments: Array of transcript segments with speaker info
User context (based on requested scopes)

Response Format:

{
  "session_id": "abc123",
  "notification": {
    "prompt": "You are mentoring {{user_name}}. Based on {{user_facts}} and {{user_context}}, provide brief advice in 50 words.",
    "params": ["user_name", "user_facts", "user_context"]
  }
}

Template variables are replaced with actual user data by OMI, then AI generates the final notification.

Step 3: Deploy and Publish Your App 💻

Deploy your webhook server to a public HTTPS endpoint
Test your app in Developer Mode
Submit for review in the OMI App Store
Users install your app and grant permissions

Here’s a complete Python implementation:

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

app = FastAPI()

class TranscriptSegment(BaseModel):
    text: str
    speaker: str
    is_user: bool

class RealtimeRequest(BaseModel):
    session_id: str
    segments: List[TranscriptSegment]

@app.post("/webhook")
def proactive_notification(data: RealtimeRequest):
    # Detect trigger phrases
    transcript = " ".join([s.text for s in data.segments])
    
    if "what do you think" in transcript.lower():
        return {
            "session_id": data.session_id,
            "notification": {
                "prompt": """You are mentoring {{user_name}}. 
                Based on {{user_facts}} and the discussion {{user_context}}, 
                provide specific advice in 100 words.""",
                "params": ["user_name", "user_facts", "user_context"]
            }
        }
    
    return {"session_id": data.session_id}

Step 4: Test Your Implementation 🧪

Enable Developer Mode in OMI app (Settings → Developer Mode)
Install your app in Developer Mode
Set webhook URL in Developer Settings
Grant requested scopes to your app
Start a conversation with trigger phrases
Verify notification appears

Testing Checklist:

App configuration has both required capabilities
Webhook endpoint is publicly accessible via HTTPS
User has installed the app
User has granted the requested scopes
Webhook returns proper notification format
Notification appears within 30 seconds

Rate Limit: 1 notification per user per app every 30 seconds.

Best Practices 🎯

For Direct Notifications:

Implement rate limiting
Keep messages concise
Validate user IDs
Handle errors gracefully

For Proactive Notifications:

Only trigger on relevant conversation moments
Use session state to avoid duplicate notifications
Keep prompts under 128,000 characters
Test with different user contexts

Troubleshooting 🔍

Common Issues

Direct Notifications:

Authentication Errors - Verify API credentials and Bearer token format
Delivery Issues - Validate user ID exists
Rate Limiting - Implement exponential backoff

Proactive Notifications:

Not Appearing - Check proactive_notification capability is enabled
Messages Too Short - Add specific instructions to prompt (min 5 characters)
Not Contextual - Request additional scopes in app configuration

Error Response Codes

Status Code	Meaning	Action
401	Unauthorized	Check API credentials
404	User not found	Verify user ID
429	Too many requests	Implement rate limiting
500	Server error	Retry with backoff

Example Implementations 💡

1. Real-Time Mentor

@app.post("/mentor")
def mentor_notification(data: RealtimeRequest):
    transcript = " ".join([s.text for s in data.segments])
    
    if "what do you think" in transcript.lower():
        return {
            "session_id": data.session_id,
            "notification": {
                "prompt": "You are mentoring {{user_name}}. Based on {{user_facts}}, provide actionable advice in 100 words.",
                "params": ["user_name", "user_facts"]
            }
        }
    return {"session_id": data.session_id}

2. Meeting Insight Generator

@app.post("/insights")
def meeting_insights(data: RealtimeRequest):
    transcript = " ".join([s.text for s in data.segments])
    
    if "action item" in transcript.lower() or "follow up" in transcript.lower():
        return {
            "session_id": data.session_id,
            "notification": {
                "prompt": "Based on {{user_context}}, summarize key action items for {{user_name}} in 75 words.",
                "params": ["user_name", "user_context"]
            }
        }
    return {"session_id": data.session_id}

Need Help? 🤝

Check our API Reference
Join our Discord community
Contact support

Get Started

Developer

Build Apps

Hardware

DIY Guide

Info

Notifications

Types of Notifications 📬

1. 📱 Direct Text Notifications

Example Use Cases

2. 🎯 Proactive Notifications

Example Use Cases

Implementing Notifications 🛠️

Step 1: Set Up Authentication 🔑

Step 2: Configure Your Endpoint 🔌

Base URL and Endpoint

Required Headers

Query Parameters

Step 3: Implement the Code 💻

Step 4: Test Your Implementation 🧪

Best Practices 🎯

Troubleshooting 🔍

Common Issues

Error Response Codes

Example Implementations 💡

1. Task Reminder

2. Service Update

Implementing Proactive Notifications 🔔

Step 1: Create Your OMI App 🔑

Step 2: Set Up Your Webhook Server 🔌

Step 3: Deploy and Publish Your App 💻

Step 4: Test Your Implementation 🧪

Best Practices 🎯

Troubleshooting 🔍

Common Issues

Error Response Codes

Example Implementations 💡

1. Real-Time Mentor

2. Meeting Insight Generator

Need Help? 🤝

Get Started

Developer

Build Apps

Hardware

DIY Guide

Info

​Types of Notifications 📬

​1. 📱 Direct Text Notifications

​Example Use Cases

​2. 🎯 Proactive Notifications

​Example Use Cases

​Implementing Notifications 🛠️

​Step 1: Set Up Authentication 🔑

​Step 2: Configure Your Endpoint 🔌

​Base URL and Endpoint

​Required Headers

​Query Parameters

​Step 3: Implement the Code 💻

​Step 4: Test Your Implementation 🧪

​Best Practices 🎯

​Troubleshooting 🔍

​Common Issues

​Error Response Codes

​Example Implementations 💡

​1. Task Reminder

​2. Service Update

​Implementing Proactive Notifications 🔔

​Step 1: Create Your OMI App 🔑

​Step 2: Set Up Your Webhook Server 🔌

​Step 3: Deploy and Publish Your App 💻

​Step 4: Test Your Implementation 🧪

​Best Practices 🎯

​Troubleshooting 🔍

​Common Issues

​Error Response Codes

​Example Implementations 💡

​1. Real-Time Mentor

​2. Meeting Insight Generator

​Need Help? 🤝

Types of Notifications 📬

1. 📱 Direct Text Notifications

Example Use Cases

2. 🎯 Proactive Notifications

Example Use Cases

Implementing Notifications 🛠️

Step 1: Set Up Authentication 🔑

Step 2: Configure Your Endpoint 🔌

Base URL and Endpoint

Required Headers

Query Parameters

Step 3: Implement the Code 💻

Step 4: Test Your Implementation 🧪

Best Practices 🎯

Troubleshooting 🔍

Common Issues

Error Response Codes

Example Implementations 💡

1. Task Reminder

2. Service Update

Implementing Proactive Notifications 🔔

Step 1: Create Your OMI App 🔑

Step 2: Set Up Your Webhook Server 🔌

Step 3: Deploy and Publish Your App 💻

Step 4: Test Your Implementation 🧪

Best Practices 🎯

Troubleshooting 🔍

Common Issues

Error Response Codes

Example Implementations 💡

1. Real-Time Mentor

2. Meeting Insight Generator

Need Help? 🤝