Sending Notifications

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

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>`

Query Parameters:

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.

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

Node.js
Python

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);

import os
import requests

def send_notification(user_id: str, message: str) -> dict:
    app_id = os.environ['OMI_APP_ID']
    app_secret = os.environ['OMI_APP_SECRET']

    response = requests.post(
        f'https://api.omi.me/v2/integrations/{app_id}/notification',
        params={'uid': user_id, 'message': message},
        headers={'Authorization': f'Bearer {app_secret}'}
    )
    response.raise_for_status()
    return response.json()

# Usage
send_notification('user123', 'Your task is due in 1 hour!')

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

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

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:

{
  "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

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:

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

Python (FastAPI)
Node.js (Express)

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}

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const { session_id, segments } = req.body;

  // Combine segments into transcript
  const transcript = segments
    .map(s => s.text)
    .join(' ')
    .toLowerCase();

  // Detect trigger phrases
  if (transcript.includes('what do you think') || transcript.includes('any advice')) {
    return res.json({
      session_id,
      notification: {
        prompt: `You are a helpful mentor for {{user_name}}.
          Based on their goals ({{user_facts}}) and the discussion ({{user_context}}),
          provide specific advice in under 100 words.`,
        params: ['user_name', 'user_facts', 'user_context']
      }
    });
  }

  // No notification needed
  res.json({ 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

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

Check these:

API credentials are correct
User ID is valid
Bearer token is properly formatted
Request includes required headers

Proactive Notifications Not Appearing

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

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

Integration Apps

Build webhook-based integrations

OAuth Setup

Add authentication to your apps

Chat Tools

Add custom tools to Omi chat

Submit Your App

Publish your app to the store

​Overview

Direct Notifications

Proactive Notifications

​Direct Flow

​Proactive Flow

​Direct Notifications

​API Reference

​Implementation

​Code Examples

​Proactive Notifications

​App Configuration

​Available Scopes

​Webhook Implementation

​Complete Example

​Testing

​Best Practices

Rate Limiting

Content Quality

Error Handling

Security

​Troubleshooting

​Error Codes

​Related Documentation

Integration Apps

OAuth Setup

Chat Tools

Submit Your App

Overview

Direct Flow

Proactive Flow

Direct Notifications

API Reference

Implementation

Code Examples

Proactive Notifications

App Configuration

Available Scopes

Webhook Implementation

Complete Example

Testing

Best Practices

Troubleshooting

Error Codes

Related Documentation