Skip to content

INTEGRATIONS.md

Latest commit

 

History

History
165 lines (136 loc) · 8.82 KB

INTEGRATIONS.md

File metadata and controls

165 lines (136 loc) · 8.82 KB
Raw

MESH-API Integrations

Setup guides for the AI providers and communication integrations that MESH-API can drive. For the project overview see README.md; for core settings see CONFIGURATION.md; for the full per-extension reference see EXTENSIONS.md.

Home Assistant Integration

Home Assistant is now an extension. Configure it in extensions/home_assistant/config.json or via the WebUI Extensions Manager. See EXTENSIONS.md for details.

  • Enable: Set "enabled": true in extensions/home_assistant/config.json.
  • Configure: Set the url, token, channel_index, and timeout fields in the extension config.
  • Security (Optional): Enable "enable_pin": true and set "secure_pin" in the extension config.
  • Routing: Messages on the designated channel are forwarded to Home Assistant. When PIN mode is enabled, include your PIN in the format PIN=XXXX your message.

LLM API Integration

Set "ai_provider" in config.json to one of the 12 supported providers, then fill in the corresponding API key / URL / model fields:

  • LM Studio: "ai_provider": "lmstudio" — configure lmstudio_url, and optionally set lmstudio_chat_model / lmstudio_embedding_model if using multiple models.
  • OpenAI: "ai_provider": "openai" — provide openai_api_key and choose a model (default gpt-4.1-mini).
  • Ollama: "ai_provider": "ollama" — configure URL, model, and optional generation overrides via ollama_options.
  • Claude: "ai_provider": "claude" — provide claude_api_key (default model claude-sonnet-4-20250514).
  • Gemini: "ai_provider": "gemini" — provide gemini_api_key (default model gemini-2.0-flash).
  • Grok: "ai_provider": "grok" — provide grok_api_key (default model grok-3).
  • OpenRouter: "ai_provider": "openrouter" — provide openrouter_api_key (default model openai/gpt-4.1-mini).
  • Groq: "ai_provider": "groq" — provide groq_api_key (default model llama-3.3-70b-versatile).
  • DeepSeek: "ai_provider": "deepseek" — provide deepseek_api_key (default model deepseek-chat).
  • Mistral: "ai_provider": "mistral" — provide mistral_api_key (default model mistral-small-latest).
  • OpenAI-Compatible: "ai_provider": "openai_compatible" — provide openai_compatible_url, openai_compatible_api_key, and openai_compatible_model for any provider with an OpenAI-compatible API.

All providers have a configurable _timeout (default 60 seconds).

Tip: You can also define multiple named AI endpoints and assign a different one per channel from the 🔌 Manage AI Endpoints panel inside the 🤖 Channel Agents modal. Each endpoint has a live heartbeat status dot (token-free /models ping). See the v0.7.3.1 and v0.7.3.6 entries in the CHANGELOG.

Email Integration

  • Enable Email Alerts:
    • Set "enable_smtp": true in config.json.
  • Configure SMTP:
    • Provide the following settings in config.json:
      • "smtp_host" (e.g., smtp.gmail.com)
      • "smtp_port" (use 465 for SSL or another port for TLS)
      • "smtp_user" (your email address)
      • "smtp_pass" (your email password or app-specific password)
      • "alert_email_to" (recipient email address or list of addresses)
  • Behavior:
    • Emergency emails include a clickable Google Maps link (generated from available GPS data) so recipients can quickly view the sender's location.
  • Note:
    • Ensure your SMTP settings are allowed by your email provider (for example, Gmail may require an app password and proper security settings).

Discord Integration: Detailed Setup & Permissions

Discord is now an extension. Configure it in extensions/discord/config.json or via the WebUI Extensions Manager. The setup steps below for creating a Discord bot and permissions still apply.

483177250_1671387500130340_6790017825443843758_n

1. Create a Discord Bot

  • Access the Developer Portal: Go to the Discord Developer Portal and sign in with your Discord account.
  • Create a New Application: Click on "New Application," give it a name (e.g., MESH-API Bot), and confirm.
  • Add a Bot to Your Application:
    • Select your application, then navigate to the Bot tab on the left sidebar.
    • Click on "Add Bot" and confirm by clicking "Yes, do it!"
    • Customize your bot's username and icon if desired.

2. Set Up Bot Permissions

  • Required Permissions: Your bot needs a few basic permissions to function correctly:
    • View Channels: So it can see messages in the designated channels.
    • Send Messages: To post responses and emergency alerts.
    • Read Message History: For polling messages from a channel (if polling is enabled).
    • Manage Messages (Optional): If you want the bot to delete or manage messages.
  • Permission Calculator: Use a tool like Discord Permissions Calculator to generate the correct permission integer. For minimal functionality, a permission integer of 3072 (which covers "Send Messages," "View Channels," and "Read Message History") is often sufficient.

3. Invite the Bot to Your Server

  • Generate an Invite Link: Replace YOUR_CLIENT_ID with your bot's client ID (found in the General Information tab) in the following URL: 
    https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=3072&scope=bot
  • Invite the Bot: Open the link in your browser, select the server where you want to add the bot, and authorize it. Make sure you have the "Manage Server" permission in that server.

4. Configure Bot Credentials in Extension Config

Update extensions/discord/config.json with the following keys (or use the WebUI Extensions Manager):

{
  "enabled": true,
  "webhook_url": "YOUR_DISCORD_WEBHOOK_URL",
  "receive_enabled": true,
  "bot_token": "YOUR_BOT_TOKEN",
  "channel_id": "YOUR_CHANNEL_ID",
  "inbound_channel_index": 1,
  "send_ai": true,
  "send_emergency": true
}
  • webhook_url: Create a webhook in your desired Discord channel (Channel Settings → Integrations → Webhooks) and copy its URL.
  • bot_token & channel_id: Copy your bot's token from the Developer Portal and enable message polling by specifying the channel ID where the bot should read messages. To get a channel ID, enable Developer Mode in Discord (User Settings → Advanced → Developer Mode) then right-click the channel and select "Copy ID."

5. Polling Integration (Optional)

  • Enable Message Polling: Set "receive_enabled": true in the extension config to allow the bot to poll for new messages.
  • Routing: The "inbound_channel_index" key determines the mesh channel used by MESH-API for routing incoming Discord messages.

6. Testing Your Discord Setup

  • Restart MESH-API (or hot-reload via the WebUI Extensions Manager).
  • Check Bot Activity: Verify that the bot is present in your server, that it can see messages in the designated channel, and that it can send responses.
  • Emergency Alerts & AI Responses: Confirm that emergency alerts and AI responses are being posted in Discord as per your extension configuration.

7. Troubleshooting Tips

  • Permissions Issues: If the bot isn't responding or reading messages, double-check that its role on your server has the required permissions.
  • Channel IDs & Webhook URLs: Verify that you've copied the correct channel IDs and webhook URLs (ensure no extra spaces or formatting issues).
  • Bot Token Security: Keep your bot token secure. If it gets compromised, regenerate it immediately from the Developer Portal.

Twilio Integration

  • Enable Twilio:
    • Set "enable_twilio": true in config.json.
  • Configure Twilio Credentials:
    • Provide your Twilio settings in config.json:
      • "twilio_sid": "YOUR_TWILIO_SID"
      • "twilio_auth_token": "YOUR_TWILIO_AUTH_TOKEN"
      • "twilio_from_number": "YOUR_TWILIO_PHONE_NUMBER"
      • "alert_phone_number": "DESTINATION_PHONE_NUMBER" (the number to receive emergency SMS)
  • Usage:
    • When an emergency is triggered, the bot sends an SMS containing the alert message (with a Google Maps link if GPS data is available).
  • Tip:
    • Follow Twilio's setup guide to obtain your SID and Auth Token, and ensure that your phone numbers are verified.