Skip to main content

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.
  • Task reminders and event notifications
  • Service updates or changes
  • Real-time alerts and warnings
  • Responses to user queries
  • New feature announcements

API Reference

SettingValue
MethodPOST
URLhttps://api.omi.me/v2/integrations/{app_id}/notification
AuthBearer <YOUR_APP_SECRET>
Query Parameters:
ParameterRequiredDescription
uidYesTarget user’s Omi ID
messageYesNotification text

Implementation

Get Credentials

You’ll need your App ID and App Secret from the Omi developer portal.
export OMI_APP_ID="your_app_id"
export OMI_APP_SECRET="your_app_secret"
Store credentials securely - never commit them to version control.

Send Notification

Make a POST request with the user ID and message:
curl -X POST "https://api.omi.me/v2/integrations/${OMI_APP_ID}/notification?uid=USER_ID&message=Hello!" \
  -H "Authorization: Bearer ${OMI_APP_SECRET}" \
  -H "Content-Type: application/json"

Handle Response

Check the response status code to confirm delivery.

Code Examples

const https = require('https');

async function sendNotification(userId, message) {
  const appId = process.env.OMI_APP_ID;
  const appSecret = process.env.OMI_APP_SECRET;

  const url = new URL(`https://api.omi.me/v2/integrations/${appId}/notification`);
  url.searchParams.set('uid', userId);
  url.searchParams.set('message', message);

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${appSecret}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }

  return response.json();
}

// Usage
sendNotification('user123', 'Your task is due in 1 hour!')
  .then(console.log)
  .catch(console.error);

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.
  • 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
  1. User installs your app and grants permissions
  2. During conversations, Omi sends transcripts to your webhook
  3. Your webhook analyzes the transcript and returns a prompt template
  4. Omi fills in user context (name, facts, etc.) and generates the notification
  5. User receives a personalized, contextual notification

App Configuration

Your app needs these capabilities:
{
  "name": "Your App Name",
  "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

ScopeTemplate VariableDescription
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:
POST /your-webhook?session_id=abc123&uid=user123
Request Body:
{
  "session_id": "abc123",
  "segments": [
    {"text": "What do you think about this approach?", "speaker": "SPEAKER_01", "is_user": false}
  ]
}
Response (when you want to send a notification):
{
  "session_id": "abc123",
  "notification": {
    "prompt": "You are mentoring {{user_name}}. Based on {{user_facts}} and {{user_context}}, provide brief actionable advice in 50 words.",
    "params": ["user_name", "user_facts", "user_context"]
  }
}
Response (when no notification needed):
{
  "session_id": "abc123"
}

Complete Example

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

app = FastAPI()

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

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

@app.post("/webhook")
def handle_transcript(data: WebhookRequest, uid: str, session_id: str):
    # Combine all segments into transcript
    transcript = " ".join([s.text for s in data.segments]).lower()

    # Detect trigger phrases
    if "what do you think" in transcript or "any advice" in transcript:
        return {
            "session_id": data.session_id,
            "notification": {
                "prompt": """You are a helpful mentor for {{user_name}}.
                Based on their goals ({{user_facts}}) and the current discussion ({{user_context}}),
                provide specific, actionable advice in under 100 words.""",
                "params": ["user_name", "user_facts", "user_context"]
            }
        }

    # No notification needed
    return {"session_id": data.session_id}

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

CodeMeaningSolution
401UnauthorizedVerify API credentials and Bearer token format
404User not foundCheck that user ID exists and has your app installed
429Rate limitedImplement rate limiting with exponential backoff
500Server errorRetry with backoff, check Omi status page
Check these:
  • API credentials are correct
  • User ID is valid
  • Bearer token is properly formatted
  • Request includes required headers
Check these:
  • App has proactive_notification capability enabled
  • User has installed your app
  • User has granted requested scopes
  • Webhook is returning proper response format
  • Prompt is at least 5 characters
Solutions:
  • Request additional scopes in app configuration
  • Include more template variables in your prompt
  • Make prompts more specific about using the context