Configure Telegram Notifications
Set up Telegram notifications so OMX can message you when sessions end, need input, or complete background tasks.
How This Skill Works
This is an interactive, natural-language configuration skill. Walk the user through setup by asking questions with AskUserQuestion. Write the result to ~/.codex/.omx-config.json.
Step 1: Detect Existing Configuration
CONFIG_FILE="$HOME/.codex/.omx-config.json"
if [ -f "$CONFIG_FILE" ]; then
HAS_TELEGRAM=$(jq -r '.notifications.telegram.enabled // false' "$CONFIG_FILE" 2>/dev/null)
CHAT_ID=$(jq -r '.notifications.telegram.chatId // empty' "$CONFIG_FILE" 2>/dev/null)
PARSE_MODE=$(jq -r '.notifications.telegram.parseMode // "Markdown"' "$CONFIG_FILE" 2>/dev/null)
if [ "$HAS_TELEGRAM" = "true" ]; then
echo "EXISTING_CONFIG=true"
echo "CHAT_ID=$CHAT_ID"
echo "PARSE_MODE=$PARSE_MODE"
else
echo "EXISTING_CONFIG=false"
fi
else
echo "NO_CONFIG_FILE"
fiIf existing config is found, show the user what's currently configured and ask if they want to update or reconfigure.
Step 2: Create a Telegram Bot
Guide the user through creating a bot if they don't have one:
To set up Telegram notifications, you need a Telegram bot token and your chat ID.
CREATE A BOT (if you don't have one):
1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a name (e.g., "My OMX Notifier")
4. Choose a username (e.g., "my_omc_bot")
5. BotFather will give you a token like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
GET YOUR CHAT ID:
1. Start a chat with your new bot (send /start)
2. Visit: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
3. Look for "chat":{"id":YOUR_CHAT_ID}
- Personal chat IDs are positive numbers (e.g., 123456789)
- Group chat IDs are negative numbers (e.g., -1001234567890)Step 3: Collect Bot Token
Use AskUserQuestion:
Question: "Paste your Telegram bot token (from @BotFather)"
The user will type their token in the "Other" field.
Validate the token:
- Must match pattern:
digits:alphanumeric(e.g.,123456789:ABCdefGHI...) - If invalid, explain the format and ask again
Step 4: Collect Chat ID
Use AskUserQuestion:
Question: "Paste your Telegram chat ID (the number from getUpdates API)"
The user will type their chat ID in the "Other" field.
Validate the chat ID:
- Must be a number (positive for personal, negative for groups)
- If invalid, offer to help them find it:
# Help user find their chat ID
BOT_TOKEN="USER_PROVIDED_TOKEN"
echo "Fetching recent messages to find your chat ID..."
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getUpdates" | jq '.result[-1].message.chat.id // .result[-1].message.from.id // "No messages found - send /start to your bot first"'Step 5: Choose Parse Mode
Use AskUserQuestion:
Question: "Which message format do you prefer?"
Options:
- Markdown (Recommended) - Bold, italic, code blocks with Markdown syntax
- HTML - Bold, italic, code with HTML tags
Step 6: Configure Events
Use AskUserQuestion with multiSelect:
Question: "Which events should trigger Telegram notifications?"
Options (multiSelect: true):
- Session end (Recommended) - When a Codex session finishes
- Input needed - When Codex is waiting for your response (great for long-running tasks)
- Session start - When a new session begins
- Session continuing - When a persistent mode keeps the session alive
Default selection: session-end + ask-user-question.
Step 7: Write Configuration
Read the existing config, merge the new Telegram settings, and write back:
CONFIG_FILE="$HOME/.codex/.omx-config.json"
mkdir -p "$(dirname "$CONFIG_FILE")"
if [ -f "$CONFIG_FILE" ]; then
EXISTING=$(cat "$CONFIG_FILE")
else
EXISTING='{}'
fi
# BOT_TOKEN, CHAT_ID, PARSE_MODE are collected from user
echo "$EXISTING" | jq \
--arg token "$BOT_TOKEN" \
--arg chatId "$CHAT_ID" \
--arg parseMode "$PARSE_MODE" \
'.notifications = (.notifications // {enabled: true}) |
.notifications.enabled = true |
.notifications.telegram = {
enabled: true,
botToken: $token,
chatId: $chatId,
parseMode: $parseMode
}' > "$CONFIG_FILE"Add event-specific config if user didn't select all events:
For each event NOT selected, disable it:
# Example: disable session-start if not selected
echo "$(cat "$CONFIG_FILE")" | jq \
'.notifications.events = (.notifications.events // {}) |
.notifications.events["session-start"] = {enabled: false}' > "$CONFIG_FILE"Step 8: Test the Configuration
After writing config, offer to send a test notification:
Use AskUserQuestion:
Question: "Send a test notification to verify the setup?"
Options:
- Yes, test now (Recommended) - Send a test message to your Telegram chat
- No, I'll test later - Skip testing
If testing:
BOT_TOKEN="USER_PROVIDED_TOKEN"
CHAT_ID="USER_PROVIDED_CHAT_ID"
PARSE_MODE="Markdown"
RESPONSE=$(curl -s -w "\n%{http_code}" \
"https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
-d "chat_id=${CHAT_ID}" \
-d "parse_mode=${PARSE_MODE}" \
-d "text=OMX test notification - Telegram is configured!")
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | head -1)
if [ "$HTTP_CODE" = "200" ]; then
echo "Test notification sent successfully!"
else
echo "Failed (HTTP $HTTP_CODE):"
echo "$BODY" | jq -r '.description // "Unknown error"' 2>/dev/null || echo "$BODY"
fiReport success or failure. Common issues:
- 401 Unauthorized: Bot token is invalid
- 400 Bad Request: chat not found: Chat ID is wrong, or user hasn't sent
/startto the bot - Network error: Check connectivity to api.telegram.org
Step 9: Confirm
Display the final configuration summary:
Telegram Notifications Configured!
Bot: @your_bot_username
Chat ID: 123456789
Format: Markdown
Events: session-end, ask-user-question
Config saved to: ~/.codex/.omx-config.json
You can also set these via environment variables:
OMX_TELEGRAM_BOT_TOKEN=123456789:ABCdefGHI...
OMX_TELEGRAM_CHAT_ID=123456789
To reconfigure: /configure-telegram
To configure Discord: /configure-discordEnvironment Variable Alternative
Users can skip this wizard entirely by setting env vars in their shell profile:
export OMX_TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
export OMX_TELEGRAM_CHAT_ID="123456789"Env vars are auto-detected by the notification system without needing .omx-config.json.