docs/doc/developer/apps/Notifications.mdx
Omi supports two types of notifications you can send to users:
<CardGroup cols={2}> <Card title="Direct Notifications" icon="message"> Send immediate, exact-text messages to specific users </Card> <Card title="Proactive Notifications" icon="robot"> AI-generated contextual messages based on real-time conversations </Card> </CardGroup>flowchart LR
A[Your Server] -->|POST /notification| O[Omi API]
O -->|Push| U[User]
flowchart LR
T[Real-time Transcript] -->|Webhook| W[Your Server]
W -->|Prompt Template| O[Omi API]
O -->|AI Generated| U[User]
Send immediate messages to specific users. Perfect for alerts, updates, and responses to user actions.
<AccordionGroup> <Accordion title="Use Cases" icon="lightbulb"> - Task reminders and event notifications - Service updates or changes - Real-time alerts and warnings - Responses to user queries - New feature announcements </Accordion> </AccordionGroup>| 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 |
```bash
export OMI_APP_ID="your_app_id"
export OMI_APP_SECRET="your_app_secret"
```
<Warning>
Store credentials securely - never commit them to version control.
</Warning>
```bash
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"
```
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);
```
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!')
```
Context-aware, AI-generated notifications that leverage user data during real-time conversations. You provide a prompt template, Omi generates the personalized message.
<Info> Unlike direct notifications, proactive notifications require an app with specific capabilities and user-granted permissions. </Info> <AccordionGroup> <Accordion title="Use Cases" icon="lightbulb"> - 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 </Accordion> <Accordion title="How It Works" icon="gear"> 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 </Accordion> </AccordionGroup>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"]
}
}
| 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 |
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"
}
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}
```
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 });
});
```
| 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 |