---
title: Plugin Setup Guide
description: Comprehensive setup instructions for Eliza connector, AI provider, and streaming plugins.
---

# Plugin Setup Guide — Eliza AI

Comprehensive setup instructions for all connector, AI provider, and streaming plugins.
When users ask how to set up a plugin, use this guide: give them the exact env var names,
where to get the credentials, minimum required fields, and tips for optional fields.

---

## AI Providers

### OpenAI
**Get credentials:** https://platform.openai.com/api-keys
**Minimum required:** `OPENAI_API_KEY` (starts with `sk-`)
**Variables:**
- `OPENAI_API_KEY` — Your secret API key from platform.openai.com
- `OPENAI_BASE_URL` — Leave blank for OpenAI default; set to a proxy URL if using a custom endpoint
- `OPENAI_SMALL_MODEL` — e.g. `gpt-5-mini` (used for fast/cheap tasks)
- `OPENAI_LARGE_MODEL` — e.g. `gpt-5` (used for complex reasoning)
- `OPENAI_EMBEDDING_MODEL` — e.g. `text-embedding-3-small` (for semantic search)
- `OPENAI_TTS_MODEL` / `OPENAI_TTS_VOICE` — e.g. `tts-1` / `alloy` (for voice synthesis)
- `OPENAI_IMAGE_DESCRIPTION_MODEL` — e.g. `gpt-5` (for image understanding)
**Tips:** OpenAI is the default fallback for most features. If you have credits, set this first. Use `gpt-5-mini` as small model to save costs.

### Anthropic
**Get credentials:** https://console.anthropic.com/settings/keys
**Minimum required:** `ANTHROPIC_API_KEY` (starts with `sk-ant-`) or `CLAUDE_API_KEY`
**Variables:**
- `ANTHROPIC_API_KEY` / `CLAUDE_API_KEY` — Your secret key from console.anthropic.com (either works for auto-enable)
- `ANTHROPIC_SMALL_MODEL` — e.g. `claude-haiku-4-5-20251001`
- `ANTHROPIC_LARGE_MODEL` — e.g. `claude-sonnet-4-6`
- `ANTHROPIC_BROWSER_BASE_URL` — (Advanced) Proxy URL for browser-side requests
**Tips:** Best for complex reasoning and long context. Claude Haiku is very fast for the small model slot.

### Google Gemini
**Get credentials:** https://aistudio.google.com/app/apikey
**Minimum required:** `GOOGLE_GENERATIVE_AI_API_KEY` or `GOOGLE_API_KEY`
**Variables:**
- `GOOGLE_GENERATIVE_AI_API_KEY` / `GOOGLE_API_KEY` — From AI Studio or Google Cloud (either works for auto-enable)
- `GOOGLE_SMALL_MODEL` — e.g. `gemini-2.5-flash`
- `GOOGLE_LARGE_MODEL` — e.g. `gemini-2.5-pro`
- `GOOGLE_EMBEDDING_MODEL` — e.g. `text-embedding-004`
- `GOOGLE_IMAGE_MODEL` — e.g. `gemini-2.0-flash-001`
**Tips:** Gemini Flash is fast and cheap; great for small model. The free tier is generous.

### Groq
**Get credentials:** https://console.groq.com/keys
**Minimum required:** `GROQ_API_KEY`
**Variables:**
- `GROQ_API_KEY` — From console.groq.com
- `GROQ_SMALL_MODEL` — e.g. `openai/gpt-oss-120b`
- `GROQ_LARGE_MODEL` — e.g. `openai/gpt-oss-120b`
- `GROQ_TTS_MODEL` / `GROQ_TTS_VOICE` — e.g. `canopylabs/orpheus-v1-english` / `troy`
- `GROQ_TTS_RESPONSE_FORMAT` — Audio response format (default: `wav`)
**Tips:** Groq is extremely fast inference — great for latency-sensitive use cases. Free tier available.

### OpenRouter
**Get credentials:** https://openrouter.ai/keys
**Minimum required:** `OPENROUTER_API_KEY`
**Variables:**
- `OPENROUTER_API_KEY` — From openrouter.ai/keys
- `OPENROUTER_SMALL_MODEL` — e.g. `openai/gpt-5-mini` or `openai/gpt-oss-120b`
- `OPENROUTER_LARGE_MODEL` — e.g. `anthropic/claude-sonnet-4-6`
- `OPENROUTER_IMAGE_MODEL` — e.g. `openai/gpt-5` (for vision tasks)
- `OPENROUTER_IMAGE_GENERATION_MODEL` — e.g. `openai/dall-e-3`
- `OPENROUTER_EMBEDDING_MODEL` — e.g. `openai/text-embedding-3-small`
- `OPENROUTER_TOOL_EXECUTION_MAX_STEPS` — Max tool call steps per turn (default: 15)
**Tips:** OpenRouter gives you access to 200+ models through one API key. Great if you want to switch models without managing multiple accounts. Use model IDs in `provider/model-name` format.

### xAI (Grok)
**Get credentials:** https://console.x.ai/
**Minimum required:** `XAI_API_KEY` or `GROK_API_KEY`
**Variables:**
- `XAI_API_KEY` / `GROK_API_KEY` — From console.x.ai (either works for auto-enable)
- `XAI_MODEL` — e.g. `grok-3` (overrides small/large)
- `XAI_SMALL_MODEL` / `XAI_LARGE_MODEL` — Specific model slots
- `XAI_EMBEDDING_MODEL` — e.g. `grok-embedding`
- `X_AUTH_MODE` — `env` (default) or `oauth`
- `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET` — Twitter OAuth keys (for the X connector side of xAI)
- `X_ENABLE_POST`, `X_ENABLE_REPLIES`, `X_ENABLE_ACTIONS` — Toggle X/Twitter behaviors
**Tips:** xAI = Grok models. The `X_*` vars are for the Twitter integration bundled with xAI. Keep auth mode as `api_key` unless you need OAuth. For a standalone Twitter connector (without Grok), see the [Twitter/X connector](#twitter--x) section below — it uses `TWITTER_*` env vars and `connectors.twitter` config instead.

### Ollama (Local Models)
**Get credentials:** No API key needed — install Ollama locally
**Setup:** https://ollama.com — create the Eliza-1 Ollama models from `packages/training/cloud/ollama/`
**Minimum required:** `OLLAMA_BASE_URL` = `http://localhost:11434` (auto-enable trigger) or `OLLAMA_API_ENDPOINT` = `http://localhost:11434/api`
**Variables:**
- `OLLAMA_BASE_URL` — Auto-enable trigger. Default: `http://localhost:11434`
- `OLLAMA_API_ENDPOINT` — Plugin endpoint. Default: `http://localhost:11434/api`
- `OLLAMA_SMALL_MODEL` — e.g. `eliza-1-2b`
- `OLLAMA_MEDIUM_MODEL` — e.g. `eliza-1-9b`
- `OLLAMA_LARGE_MODEL` — e.g. `eliza-1-9b`
- `OLLAMA_EMBEDDING_MODEL` — e.g. `nomic-embed-text`
**Tips:** Completely free and private. Requires Ollama running on your machine or a server. Build Eliza-1 models with `ollama create eliza-1-9b -f packages/training/cloud/ollama/Modelfile.eliza-1-9b-q4_k_m`.

### Local AI
**Get credentials:** No API key — uses local model files
**Variables:**
- `MODELS_DIR` — Path to your local model files (e.g. `/Users/you/models`)
- `CACHE_DIR` — Path for caching (e.g. `/tmp/ai-cache`)
- `LOCAL_SMALL_MODEL` / `LOCAL_LARGE_MODEL` — Model filenames in MODELS_DIR
- `LOCAL_EMBEDDING_MODEL` / `LOCAL_EMBEDDING_DIMENSIONS` — Embedding model and its dimension count
- `CUDA_VISIBLE_DEVICES` — GPU selection, e.g. `0` for first GPU
**Tips:** Use when you have .gguf or similar model files and want full offline operation.

### Vercel AI Gateway
**Get credentials:** https://vercel.com/docs/ai/ai-gateway
**Minimum required:** `AI_GATEWAY_API_KEY` and `AI_GATEWAY_BASE_URL`
**Variables:**
- `AI_GATEWAY_API_KEY` / `AIGATEWAY_API_KEY` — Your gateway key (either works)
- `VERCEL_OIDC_TOKEN` — For Vercel-hosted deployments only
- `AI_GATEWAY_BASE_URL` — Your gateway endpoint URL
- `AI_GATEWAY_SMALL_MODEL` / `AI_GATEWAY_LARGE_MODEL` / `AI_GATEWAY_EMBEDDING_MODEL` — Model IDs
- `AI_GATEWAY_IMAGE_MODEL` — For image generation
- `AI_GATEWAY_TIMEOUT_MS` — Request timeout, default 60000ms
**Tips:** Routes model calls through Vercel's AI gateway for caching, rate limiting, and observability. Useful if you're already on Vercel.

### Eliza Cloud
**Get credentials:** From the elizaOS Cloud service
**Minimum required:** `ELIZAOS_CLOUD_API_KEY` or `ELIZAOS_CLOUD_ENABLED=true`
**Variables:**
- `ELIZAOS_CLOUD_API_KEY` — Your Eliza Cloud API key
- `ELIZAOS_CLOUD_ENABLED` — Set to `true` to enable cloud features
**Tips:** Eliza Cloud provides hosted infrastructure for running Eliza agents with managed scaling and monitoring.

---

## Connectors

### Discord
**Get credentials:** https://discord.com/developers/applications → New Application → Bot → Reset Token
**Minimum required:** `DISCORD_API_TOKEN`
**Variables:**
- `DISCORD_API_TOKEN` — Bot token (from Bot section, click Reset Token)
- `DISCORD_APPLICATION_ID` — Application ID (from General Information, optional if runtime auto-resolve succeeds)
- `CHANNEL_IDS` — Comma-separated channel IDs to listen in
- `DISCORD_VOICE_CHANNEL_ID` — For voice channel support
- `DISCORD_SHOULD_IGNORE_BOT_MESSAGES` — `true` to prevent bot-to-bot loops
- `DISCORD_SHOULD_IGNORE_DIRECT_MESSAGES` — `true` to disable DM responses
- `DISCORD_SHOULD_RESPOND_ONLY_TO_MENTIONS` — `true` to only respond when @mentioned
- `DISCORD_LISTEN_CHANNEL_IDS` — Channel IDs to listen but not post unsolicited
**Setup steps:**
1. Create app at discord.com/developers/applications
2. Go to Bot tab → Reset Token (copy immediately)
3. Get Application ID from General Information tab
4. Under OAuth2 → URL Generator → Bot → select permissions: Send Messages, Read Messages, Use Slash Commands
5. Invite bot using generated URL
6. Enable Message Content Intent under Bot → Privileged Gateway Intents
**Tips:** You need BOTH the Bot Token AND Application ID — without Application ID slash commands won't register. Right-click a channel and Copy ID to get channel IDs (enable Developer Mode in Discord settings first).

### Telegram
**Get credentials:** Message @BotFather on Telegram
**Minimum required:** `TELEGRAM_BOT_TOKEN`
**Variables:**
- `TELEGRAM_BOT_TOKEN` — From @BotFather after `/newbot`
- `TELEGRAM_ALLOWED_CHATS` — JSON array of allowed chat IDs, e.g. `["123456789", "-100987654321"]`
- `TELEGRAM_API_ROOT` — Leave blank for default; set if using a Telegram proxy
- `TELEGRAM_TEST_CHAT_ID` — For testing (advanced)
**Setup steps:**
1. Message @BotFather: `/newbot`
2. Give it a name and username
3. Copy the token it gives you
4. To get your chat ID: message @userinfobot
**Tips:** Use negative IDs for groups (they start with -100). Use `TELEGRAM_ALLOWED_CHATS` to restrict who can talk to the bot for safety.

### Twitter / X
Twitter/X integration is bundled with the **xAI** provider plugin (`@elizaos/plugin-xai`). There is no separate `@elizaos/plugin-x`.

**Get credentials:** https://developer.twitter.com/en/portal/dashboard
**Minimum required:** xAI plugin enabled + Twitter OAuth keys in connector config or env vars.
**Variables (xAI plugin `X_*` convention):**
- `X_API_KEY` — Twitter API consumer key
- `X_API_SECRET` — Twitter API consumer secret
- `X_ACCESS_TOKEN` — OAuth access token
- `X_ACCESS_TOKEN_SECRET` — OAuth access token secret
- `X_AUTH_MODE` — `api_key` (default) or `oauth`
- `X_ENABLE_POST` — `true` to enable autonomous posting
- `X_ENABLE_REPLIES` — `true` to reply to @mentions
- `X_ENABLE_ACTIONS` — `true` to enable like/retweet/quote actions

**Connector config alternative** — set these under `connectors.twitter` in `eliza.json`:
- `apiKey`, `apiSecretKey`, `accessToken`, `accessTokenSecret` — OAuth credentials
- `postEnable`, `postIntervalMin`, `postIntervalMax`, `dryRun` — posting behavior
- `searchEnable`, `autoRespondMentions`, `pollInterval` — engagement settings

**Setup steps:**
1. Apply for developer account at developer.twitter.com (instant for basic tier)
2. Create a Project and App
3. Generate all 4 keys from "Keys and Tokens" tab
4. Set app permissions to Read and Write
5. Regenerate tokens AFTER setting permissions
**Tips:** Start with `TWITTER_DRY_RUN=true` to verify without posting. Free API tier has very limited write access — check [X developer docs](https://developer.twitter.com/en/docs/twitter-api/rate-limits) for current limits. You need ALL 4 OAuth keys — missing any one will cause auth failure.

### Slack
**Get credentials:** https://api.slack.com/apps → Create New App
**Minimum required:** `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`
**Variables:**
- `SLACK_BOT_TOKEN` — Starts with `xoxb-` (from OAuth & Permissions → Bot Token)
- `SLACK_APP_TOKEN` — Starts with `xapp-` (from Basic Information → App-Level Tokens; scope: `connections:write`)
- `SLACK_SIGNING_SECRET` — From Basic Information (for webhook verification)
- `SLACK_USER_TOKEN` — Starts with `xoxp-` (optional, for user-level actions)
- `SLACK_CHANNEL_IDS` — Comma-separated channel IDs, e.g. `C01ABCDEF,C02GHIJKL`
- `SLACK_SHOULD_IGNORE_BOT_MESSAGES` — Prevent bot loops
- `SLACK_SHOULD_RESPOND_ONLY_TO_MENTIONS` — Only reply when @mentioned
**Setup steps:**
1. Create app at api.slack.com/apps (From Scratch → choose workspace)
2. Socket Mode: Enable Socket Mode → generate App-Level Token with `connections:write` scope
3. Bot Token Scopes (OAuth & Permissions): `chat:write`, `channels:read`, `channels:history`, `groups:history`, `im:history`, `app_mentions:read`
4. Install app to workspace → copy Bot Token
5. Enable Event Subscriptions → Subscribe to bot events: `message.channels`, `message.im`, `app_mention`
**Tips:** Socket Mode means you DON'T need a public webhook URL. Both Bot Token (xoxb-) AND App Token (xapp-) are required for Socket Mode. To get channel IDs: right-click channel in Slack → Copy link, the ID is in the URL.

### WhatsApp
**Two modes — choose one:**

**Mode 1: Cloud API (Business, recommended)**
**Get credentials:** https://developers.facebook.com/apps → WhatsApp → API Setup
- `WHATSAPP_ACCESS_TOKEN` — Permanent system user token from Meta Business
- `WHATSAPP_PHONE_NUMBER_ID` — From WhatsApp → API Setup
- `WHATSAPP_BUSINESS_ACCOUNT_ID` — From WhatsApp Business settings
- `WHATSAPP_WEBHOOK_VERIFY_TOKEN` — Any string you choose (used to verify webhook)
- `WHATSAPP_API_VERSION` — e.g. `v18.0` (use latest)
**Setup:** Need Meta Business account, verified phone number, approved WhatsApp Business App

**Mode 2: Baileys (Personal, QR code)**
- `WHATSAPP_AUTH_DIR` — Directory to store session files, e.g. `/data/whatsapp-auth`
- No other credentials needed — it scans a QR code on first run
**Tips:** Baileys mode works with your personal WhatsApp number but violates ToS. Use Cloud API for production. Cloud API requires a real business and Meta app approval.

### Instagram
**Get credentials:** Use your Instagram account credentials
**Minimum required:** `INSTAGRAM_USERNAME` + `INSTAGRAM_PASSWORD`
**Variables:**
- `INSTAGRAM_USERNAME` — Your Instagram username
- `INSTAGRAM_PASSWORD` — Your Instagram password
- `INSTAGRAM_VERIFICATION_CODE` — Your 2FA code if enabled
- `INSTAGRAM_PROXY` — Proxy URL if rate limited or blocked
**Tips:** ⚠️ Uses unofficial API. Instagram frequently blocks automated access. Use a dedicated account, not your personal one. A proxy reduces bans. 2FA users must supply the code on startup.

### Bluesky
**Get credentials:** https://bsky.app → Settings → App Passwords
**Minimum required:** `BLUESKY_HANDLE` + `BLUESKY_PASSWORD` (app password, not your real password)
**Variables:**
- `BLUESKY_HANDLE` — Your handle e.g. `yourname.bsky.social`
- `BLUESKY_PASSWORD` — App password (not your login password — create one in Settings)
- `BLUESKY_ENABLED` — `true` to enable
- `BLUESKY_SERVICE` — Default: `https://bsky.social` (only change for self-hosted PDS)
- `BLUESKY_ENABLE_POSTING` — `true` for autonomous posts
- `BLUESKY_POST_INTERVAL_MIN` / `BLUESKY_POST_INTERVAL_MAX` — Seconds between posts
- `BLUESKY_MAX_POST_LENGTH` — Max characters per post (default: 300)
- `BLUESKY_POLL_INTERVAL` — Seconds between checking mentions/DMs
- `BLUESKY_ENABLE_DMS` — `true` to respond to direct messages
**Tips:** Create an App Password at bsky.app → Settings → App Passwords. Never use your main login password.

### Farcaster
**Get credentials:** https://warpcast.com → Settings, then https://neynar.com for API
**Minimum required:** `FARCASTER_FID` + `FARCASTER_SIGNER_UUID` + `FARCASTER_NEYNAR_API_KEY`
**Variables:**
- `FARCASTER_FID` — Your Farcaster ID (number shown in profile URL)
- `FARCASTER_SIGNER_UUID` — Signer UUID from Neynar dashboard
- `FARCASTER_NEYNAR_API_KEY` — From neynar.com (needed for read/write)
- `ENABLE_CAST` — `true` to enable autonomous casting
- `CAST_INTERVAL_MIN` / `CAST_INTERVAL_MAX` — Minutes between casts
- `MAX_CAST_LENGTH` — Default 320 characters
- `FARCASTER_POLL_INTERVAL` — Seconds between notification checks
- `FARCASTER_HUB_URL` — Custom Farcaster hub (advanced, leave blank for default)
**Setup steps:**
1. Create Warpcast account, get your FID from your profile URL
2. Sign up at neynar.com, create a signer for your FID
3. Get your API key from Neynar dashboard
**Tips:** Neynar is required — it's the indexer that makes Farcaster data accessible via API.

### WeChat

> **Not yet available:** The `@elizaos/plugin-wechat` package is not currently in the plugin registry. The configuration below is for reference when the plugin becomes available.

**Get credentials:** From your WeChat proxy service provider
**Minimum required:** `WECHAT_API_KEY` + proxy URL in config
**Variables:**
- `WECHAT_API_KEY` — Proxy service API key
**Config-only fields** (set in `connectors.wechat`, not env vars):
- `proxyUrl` — **Required** — Your WeChat proxy service URL
- `webhookPort` — Webhook listener port (default: 18790)
- `deviceType` — Device emulation: `ipad` (default) or `mac`
- `features.images` — Enable image send/receive (default: false)
- `features.groups` — Enable group chat support (default: false)
**Setup steps:**
1. Get API key from your WeChat proxy service
2. Configure `connectors.wechat` in eliza.json with `apiKey` and `proxyUrl`
3. Start Eliza — scan the QR code displayed in terminal with WeChat
**Tips:** WeChat uses a third-party proxy service, not an official API. Only use a proxy you trust — it sees all message traffic. Multi-account supported via `accounts` map. Package: `@elizaos/plugin-wechat`.

### GitHub
**Get credentials:** https://github.com/settings/tokens → Fine-grained or Classic
**Minimum required:** `GITHUB_API_TOKEN`
**Variables:**
- `GITHUB_API_TOKEN` — Personal access token or GitHub App token
- `GITHUB_OWNER` — Repository owner (username or org)
- `GITHUB_REPO` — Repository name
- `GITHUB_BRANCH` — Default branch (e.g. `main`)
- `GITHUB_WEBHOOK_SECRET` — For GitHub App webhook verification
- `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_INSTALLATION_ID` — For GitHub Apps
**Tips:** Fine-grained tokens are more secure — scope only to the repos you need. For org repos, you may need to request access from the org.

### Twitch
**Get credentials:** https://dev.twitch.tv/console/apps → Register Your Application
**Minimum required:** `TWITCH_USERNAME` + `TWITCH_CLIENT_ID` + `TWITCH_ACCESS_TOKEN` + `TWITCH_CLIENT_SECRET`
**Variables:**
- `TWITCH_USERNAME` — Your Twitch bot username
- `TWITCH_CLIENT_ID` — From Twitch Developer Console
- `TWITCH_CLIENT_SECRET` — From Twitch Developer Console
- `TWITCH_ACCESS_TOKEN` — OAuth token (get via https://twitchapps.com/tmi/ or Twitch OAuth flow)
- `TWITCH_REFRESH_TOKEN` — For long-lived sessions
- `TWITCH_CHANNEL` — Primary channel to join (e.g. `mychannel`)
- `TWITCH_CHANNELS` — Additional channels (comma-separated)
- `TWITCH_REQUIRE_MENTION` — `true` to only respond when bot username is mentioned
- `TWITCH_ALLOWED_ROLES` — `broadcaster`, `moderator`, `vip`, `subscriber`, `viewer`
**Tips:** Create a separate Twitch account for the bot. Use https://twitchapps.com/tmi/ to get an access token for chat bots quickly.

### Twilio (SMS + Voice)
**Get credentials:** https://console.twilio.com
**Minimum required:** `TWILIO_ACCOUNT_SID` + `TWILIO_AUTH_TOKEN` + `TWILIO_PHONE_NUMBER`
**Variables:**
- `TWILIO_ACCOUNT_SID` — From Twilio Console dashboard (starts with `AC`)
- `TWILIO_AUTH_TOKEN` — From Twilio Console dashboard
- `TWILIO_PHONE_NUMBER` — Your Twilio number in E.164 format (e.g. `+15551234567`)
- `TWILIO_WEBHOOK_URL` — Your publicly accessible URL for incoming messages
- `TWILIO_WEBHOOK_PORT` — Port to listen on (if self-hosting, default 3000)
- `VOICE_CALL_PROVIDER` — e.g. `twilio`
- `VOICE_CALL_FROM_NUMBER` — Outbound caller ID
- `VOICE_CALL_TO_NUMBER` — Default number to call
- `VOICE_CALL_PUBLIC_URL` — Publicly accessible URL for voice webhooks
- `VOICE_CALL_MAX_DURATION_SECONDS` — Max call length (default 3600)
- `VOICE_CALL_INBOUND_POLICY` — `allow-all`, `allow-from`, or `deny-all`
- `VOICE_CALL_INBOUND_GREETING` — Text spoken when call is answered
**Tips:** For webhooks to work, Twilio needs a public URL. Use ngrok during development. Get a phone number in Console → Phone Numbers → Buy a Number. Free trial gives ~$15 credit.

### Matrix
**Get credentials:** Your Matrix homeserver account
**Minimum required:** `MATRIX_HOMESERVER` + `MATRIX_USER_ID` + `MATRIX_ACCESS_TOKEN`
**Variables:**
- `MATRIX_HOMESERVER` — e.g. `https://matrix.org` or your own homeserver
- `MATRIX_USER_ID` — e.g. `@yourbot:matrix.org`
- `MATRIX_ACCESS_TOKEN` — From Element: Settings → Help & About → Advanced → Access Token
- `MATRIX_DEVICE_ID` — Leave blank to auto-assign
- `MATRIX_ROOMS` — Comma-separated room IDs (e.g. `!abc123:matrix.org`)
- `MATRIX_AUTO_JOIN` — `true` to auto-join invite rooms
- `MATRIX_ENCRYPTION` — `true` to enable E2E encryption (requires more setup)
- `MATRIX_REQUIRE_MENTION` — `true` to only respond when @mentioned
**Tips:** Get your access token in Element → Settings → Help & About → Advanced. Matrix IDs use format `@user:server`.

### Microsoft Teams
**Get credentials:** https://portal.azure.com → Azure Active Directory → App Registrations
**Minimum required:** `MSTEAMS_APP_ID` + `MSTEAMS_APP_PASSWORD` + `MSTEAMS_TENANT_ID`
**Variables:**
- `MSTEAMS_APP_ID` — Application (client) ID from Azure portal
- `MSTEAMS_APP_PASSWORD` — Client secret value from Azure portal
- `MSTEAMS_TENANT_ID` — Your Azure AD tenant ID
- `MSTEAMS_WEBHOOK_PORT` / `MSTEAMS_WEBHOOK_PATH` — Where Bot Framework sends messages
- `MSTEAMS_ALLOWED_TENANTS` — Restrict to specific tenants (comma-separated)
- `MSTEAMS_SHAREPOINT_SITE_ID` — For SharePoint integration (advanced)
- `MSTEAMS_MEDIA_MAX_MB` — Max file upload size (default 25MB)
**Setup steps:**
1. Register app in Azure portal → App Registrations → New Registration
2. Add a client secret under Certificates & Secrets
3. Register bot via https://dev.botframework.com → Create a bot
4. Connect bot to Microsoft Teams channel in Bot Framework portal
**Tips:** Requires Microsoft 365 admin access or an org that allows app registrations.

### Google Chat
**Get credentials:** https://console.cloud.google.com → APIs → Google Chat API
**Minimum required:** Service account JSON or `GOOGLE_APPLICATION_CREDENTIALS` path
**Variables:**
- `GOOGLE_CHAT_SERVICE_ACCOUNT_KEY` — Full service account JSON (paste the entire JSON)
- `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE` — Alternative: path to service account JSON file
- `GOOGLE_APPLICATION_CREDENTIALS` — Alternative: path to credentials file
- `GOOGLE_CHAT_SPACES` — Comma-separated space names (e.g. `spaces/AAAA_space_id`)
- `GOOGLE_CHAT_AUDIENCE_TYPE` — `PUBLISHED` or `DOMAIN_INSTALL`
- `GOOGLE_CHAT_AUDIENCE` — Your app's audience URL
- `GOOGLE_CHAT_WEBHOOK_PATH` — Webhook path for incoming messages
- `GOOGLE_CHAT_REQUIRE_MENTION` — `true` to require @mention
- `GOOGLE_CHAT_BOT_USER` — Bot user ID
**Tips:** Enable Google Chat API in Cloud Console. Create a service account with Chat-scope permissions. Workspace admin must approve the Chat app.

### Signal
**Get credentials:** Your own phone number + signal-cli or signal-api-rest-api
**Minimum required:** `SIGNAL_ACCOUNT_NUMBER` + `SIGNAL_HTTP_URL`
**Variables:**
- `SIGNAL_ACCOUNT_NUMBER` — Your phone number in E.164 format (e.g. `+15551234567`)
- `SIGNAL_HTTP_URL` — REST API URL, e.g. `http://localhost:8080`
- `SIGNAL_CLI_PATH` — Path to signal-cli binary (optional, for direct CLI mode)
- `SIGNAL_SHOULD_IGNORE_GROUP_MESSAGES` — `true` to ignore group chats
**Setup:** Run signal-api-rest-api server: https://github.com/bbernhard/signal-cli-rest-api
**Tips:** Signal doesn't have an official API. Use bbernhard/signal-cli-rest-api Docker image — it handles the signal-cli connection and exposes a REST API.

### iMessage (macOS only)
**Get credentials:** macOS only — no credentials needed, uses local Messages.app
**Variables:**
- `IMESSAGE_CLI_PATH` — Path to imessage-reader CLI (install from GitHub)
- `IMESSAGE_DB_PATH` — Path to Messages chat.db (default: `~/Library/Messages/chat.db`)
- `IMESSAGE_POLL_INTERVAL_MS` — How often to check for new messages (default: 5000ms)
- `IMESSAGE_DM_POLICY` — `allow-all` or `allow-from`
- `IMESSAGE_GROUP_POLICY` — `allow-all`, `allow-from`, or `deny-all`
- `IMESSAGE_ALLOW_FROM` — Comma-separated allowed senders
- `IMESSAGE_ENABLED` — `true` to enable
**Tips:** macOS only. Requires Full Disk Access permission for the app to read the Messages database. Only works on the machine that has iMessage configured.

### BlueBubbles (iMessage via local server)
**Get credentials:** Install [BlueBubbles server](https://bluebubbles.app) on a Mac with iMessage
**Minimum required:** `BLUEBUBBLES_PASSWORD`
**Variables:**
- `BLUEBUBBLES_PASSWORD` — Password set in the BlueBubbles server app
- `BLUEBUBBLES_SERVER_URL` — BlueBubbles server URL (e.g. `http://192.168.1.50:1234`)
- `BLUEBUBBLES_WEBHOOK_PATH` — Custom webhook endpoint path
- `BLUEBUBBLES_DM_POLICY` — `allow`, `deny`, or `allowlist`
- `BLUEBUBBLES_ALLOW_FROM` — Comma-separated allowed senders
- `BLUEBUBBLES_GROUP_POLICY` — Group message policy
- `BLUEBUBBLES_GROUP_ALLOW_FROM` — Comma-separated allowed groups
- `BLUEBUBBLES_SEND_READ_RECEIPTS` — `true` to send read receipts
- `BLUEBUBBLES_ENABLED` — `true` to enable
**Tips:** Unlike direct iMessage, BlueBubbles works over the network — the agent doesn't need to run on the same Mac. Supports rich actions: tapbacks, edit/unsend, effects, attachments, and group management.

### Blooio (SMS via API)
**Get credentials:** https://bloo.io
**Minimum required:** `BLOOIO_API_KEY`
**Variables:**
- `BLOOIO_API_KEY` — From bloo.io dashboard
- `BLOOIO_WEBHOOK_URL` — Your public URL for incoming SMS webhooks
- `BLOOIO_WEBHOOK_SECRET` — Secret for webhook signature verification
- `BLOOIO_BASE_URL` — bloo.io API base URL (leave as default)
- `BLOOIO_FROM_NUMBER` — Phone number to send from
- `BLOOIO_WEBHOOK_PORT` — Port for webhook listener
**Tips:** Blooio bridges iMessage/SMS. Requires a Mac running the Blooio app.

### Nostr
**Get credentials:** Generate your own keypair using any Nostr client
**Minimum required:** `NOSTR_PRIVATE_KEY`
**Variables:**
- `NOSTR_PRIVATE_KEY` — Your nsec private key (hex format)
- `NOSTR_RELAYS` — Comma-separated relay URLs, e.g. `wss://relay.damus.io,wss://relay.nostr.band`
- `NOSTR_DM_POLICY` — `allow-all` or `allow-from`
- `NOSTR_ALLOW_FROM` — Allowed public keys (npub format)
- `NOSTR_ENABLED` — `true` to enable
**Tips:** Generate keys with any Nostr app (Damus, Primal, Amethyst). Keep private key secret — it's your identity. Use multiple relays for reliability.

### LINE
**Get credentials:** https://developers.line.biz/console
**Minimum required:** `LINE_CHANNEL_ACCESS_TOKEN` + `LINE_CHANNEL_SECRET`
**Variables:**
- `LINE_CHANNEL_ACCESS_TOKEN` — From LINE Developers console → Messaging API → Channel Access Token
- `LINE_CHANNEL_SECRET` — From Basic Settings tab
- `LINE_WEBHOOK_PATH` — Webhook URL path (configure in LINE console too)
- `LINE_DM_POLICY` / `LINE_GROUP_POLICY` — `allow-all` or `allow-from`
- `LINE_ALLOW_FROM` — Allowed user IDs
- `LINE_ENABLED` — `true` to enable
**Setup steps:**
1. Create a channel at developers.line.biz
2. Issue a channel access token (long-lived, in Messaging API tab)
3. Set your webhook URL in the console
**Tips:** LINE requires your webhook to be HTTPS with a valid certificate. Use ngrok or deploy to a server for development.

### Feishu (Lark)
**Get credentials:** https://open.feishu.cn (or open.larksuite.com for Lark)
**Minimum required:** `FEISHU_APP_ID` + `FEISHU_APP_SECRET`
**Variables:**
- `FEISHU_APP_ID` — From Feishu/Lark Developer Console → App Credentials
- `FEISHU_APP_SECRET` — From App Credentials section
- `FEISHU_DOMAIN` — `feishu.cn` (default) or `larksuite.com`
- `FEISHU_ALLOWED_CHATS` — Allowed chat IDs (comma-separated)
- `FEISHU_TEST_CHAT_ID` — For testing

### Mattermost
**Get credentials:** Your Mattermost instance → System Console → Integrations → Bot Accounts
**Minimum required:** `MATTERMOST_SERVER_URL` + `MATTERMOST_BOT_TOKEN`
**Variables:**
- `MATTERMOST_SERVER_URL` — e.g. `https://mattermost.yourcompany.com`
- `MATTERMOST_BOT_TOKEN` — From System Console → Bot Accounts → Add Bot Account
- `MATTERMOST_TEAM_ID` — Your team ID (from team URL or API)
- `MATTERMOST_DM_POLICY` / `MATTERMOST_GROUP_POLICY` — `allow-all` or `allow-from`
- `MATTERMOST_ALLOWED_USERS` / `MATTERMOST_ALLOWED_CHANNELS` — Restrict access
- `MATTERMOST_REQUIRE_MENTION` — `true` to require @mention
**Tips:** Enable Bot Accounts in System Console → Authentication → Bot Accounts. Self-hosted Mattermost is free.

### Nextcloud Talk
**Get credentials:** Your Nextcloud instance → Settings → Security → App Passwords
**Minimum required:** `NEXTCLOUD_URL` + `NEXTCLOUD_BOT_SECRET`
**Variables:**
- `NEXTCLOUD_URL` — Your Nextcloud URL (e.g. `https://cloud.yourserver.com`)
- `NEXTCLOUD_BOT_SECRET` — Set when registering bot via Nextcloud Talk API
- `NEXTCLOUD_WEBHOOK_PUBLIC_URL` — Publicly accessible URL for Talk webhooks
- `NEXTCLOUD_WEBHOOK_PORT` / `NEXTCLOUD_WEBHOOK_PATH` — Webhook server settings
- `NEXTCLOUD_ALLOWED_ROOMS` — Room tokens to allow

### Tlon (Urbit)
**Get credentials:** Your Urbit ship access
**Minimum required:** `TLON_SHIP` + `TLON_URL` + `TLON_CODE`
**Variables:**
- `TLON_SHIP` — Your ship name (e.g. `~sampel-palnet`)
- `TLON_URL` — URL to your ship (e.g. `http://localhost:8080`)
- `TLON_CODE` — Your ship's access code (from `+code` in Dojo)
- `TLON_GROUP_CHANNELS` — Channels to listen in (group path format)
- `TLON_DM_ALLOWLIST` — Allowed DM senders
- `TLON_AUTO_DISCOVER_CHANNELS` — Auto-join channels

### Zalo (Vietnam messaging)
**Get credentials:** https://developers.zalo.me
**Minimum required:** `ZALO_APP_ID` + `ZALO_SECRET_KEY` + `ZALO_ACCESS_TOKEN`
**Variables:**
- `ZALO_APP_ID` / `ZALO_SECRET_KEY` — From Zalo Developer portal
- `ZALO_ACCESS_TOKEN` / `ZALO_REFRESH_TOKEN` — OAuth tokens from Zalo
- `ZALO_WEBHOOK_URL` / `ZALO_WEBHOOK_PATH` / `ZALO_WEBHOOK_PORT` — Webhook config

### Zalo User (Personal)
Personal Zalo account connector (unofficial, no API key needed).
**Variables:**
- `ZALOUSER_COOKIE_PATH` — Path to exported Zalo session cookies
- `ZALOUSER_IMEI` — Device IMEI for session (from official Zalo app)
- `ZALOUSER_USER_AGENT` — Browser user agent string
- `ZALOUSER_PROFILES` — Multiple account profiles (JSON)
- `ZALOUSER_ALLOWED_THREADS` — Allowed conversation threads
- `ZALOUSER_DM_POLICY` / `ZALOUSER_GROUP_POLICY` — Message policies

### ACP (Agent Communication Protocol)
Internal agent-to-agent protocol for connecting multiple AI agents.
**Variables:**
- `ACP_GATEWAY_URL` — Gateway URL for the ACP hub
- `ACP_GATEWAY_TOKEN` / `ACP_GATEWAY_PASSWORD` — Authentication credentials
- `ACP_DEFAULT_SESSION_KEY` / `ACP_DEFAULT_SESSION_LABEL` — Session identification
- `ACP_CLIENT_NAME` / `ACP_CLIENT_DISPLAY_NAME` — This agent's identity
- `ACP_AGENT_ID` — Unique agent ID
- `ACP_PERSIST_SESSIONS` — `true` to save sessions across restarts
- `ACP_SESSION_STORE_PATH` — Where to save sessions

### MCP (Model Context Protocol)
Connect to any MCP server for extended tool capabilities.
**Variables:**
- `mcp` — JSON configuration object for MCP servers
**Tips:** MCP servers can provide tools (web search, code execution, file access, databases, etc.) directly to the AI. See https://modelcontextprotocol.io for available servers.

### IQ (Solana On-chain)
> **Note:** The IQ plugin is an upstream elizaOS connector not included in the bundled `plugins.json` registry. Install from the remote registry if needed.

On-chain chat via Solana blockchain.
**Minimum required:** `SOLANA_PRIVATE_KEY` + `IQ_GATEWAY_URL`
**Variables:**
- `SOLANA_PRIVATE_KEY` — Solana wallet private key (base58 encoded)
- `SOLANA_KEYPAIR_PATH` — Alternative: path to keypair JSON file
- `SOLANA_RPC_URL` — e.g. `https://api.mainnet-beta.solana.com`
- `IQ_GATEWAY_URL` — IQ protocol gateway URL
- `IQ_AGENT_NAME` — Display name for your agent
- `IQ_DEFAULT_CHATROOM` — Default chatroom to join
- `IQ_CHATROOMS` — Additional chatrooms (comma-separated)

### Gmail Watch
Monitors Gmail via Google Pub/Sub push notifications.
**Setup:** Requires Google Cloud service account with Gmail API access.
**Tips:** Uses `gog gmail watch serve` internally. Requires Google Cloud project with Gmail API enabled and Pub/Sub configured.

---

<div id="streaming"></div>

## Streaming (Live Broadcasting)

Enable **`@elizaos/plugin-streaming`** once. It covers Twitch, YouTube, X, pump.fun, custom RTMP, and optional multiple named ingests via `streaming.rtmpSources` in config.

### Stream tab (`streaming`)
Adds the Stream tab to the UI with RTMP destination management when the plugin is enabled.

### Twitch
**Get credentials:** https://dashboard.twitch.tv → Settings → Stream
**Variable:** `TWITCH_STREAM_KEY` — Your stream key (keep secret!)
**Tips:** Never share your stream key — it lets anyone stream to your channel. Regenerate if leaked.

### YouTube
**Get credentials:** https://studio.youtube.com → Go Live → Stream settings
**Variables:**
- `YOUTUBE_STREAM_KEY` — From YouTube Studio → Stream key
- `YOUTUBE_RTMP_URL` — Default: `rtmp://a.rtmp.youtube.com/live2` (rarely needs changing)
**Tips:** You need a YouTube channel with Live streaming enabled (may require phone verification).

### X (Twitter)
Live stream to X using RTMP credentials generated for the active broadcast.
**Get credentials:** From X Live Producer / Media Studio when you create a live stream
**Variables:**
- `X_STREAM_KEY` — Stream key for the broadcast
- `X_RTMP_URL` — RTMP ingest URL for the broadcast session
**Tips:** X RTMP credentials are often per-broadcast. Create the stream first, then copy both values directly into the plugin.

### pump.fun
Stream to pump.fun using the platform's RTMP ingest credentials.
**Get credentials:** From the pump.fun live streaming flow when you create a stream
**Variables:**
- `PUMPFUN_STREAM_KEY` — Stream key for pump.fun ingest
- `PUMPFUN_RTMP_URL` — RTMP ingest URL for the current stream
**Tips:** Treat both values as session credentials. If the stream refuses to start, re-create the broadcast and paste fresh values.

### Custom RTMP
Stream to any platform (Facebook, TikTok, Kick, self-hosted RTMP, etc.)
**Variables:**
- `CUSTOM_RTMP_URL` — RTMP endpoint URL, e.g. `rtmp://live.kick.com/app`
- `CUSTOM_RTMP_KEY` — Stream key from the platform
**Common RTMP URLs:**
- Facebook Live: `rtmps://live-api-s.facebook.com:443/rtmp/`
- TikTok: `rtmp://push.tiktokcdn.com/third/` (need TikTok Live access)
- Kick: `rtmp://ingest.global-contribute.live-video.net/app`

---

## General Tips

**Required vs Optional:** Every plugin has minimum required fields. Start with just those — you can add optional settings later.

**Testing before going live:** Most connectors have a "dry run" mode (e.g. `TWITTER_DRY_RUN=true`, `FARCASTER_DRY_RUN=true`, `BLUESKY_DRY_RUN=true`) — use this to verify setup without posting.

**Policy fields:** Most connectors have `DM_POLICY` and `GROUP_POLICY` fields:
- `allow-all` — respond to everyone
- `allow-from` — only respond to accounts in the `ALLOW_FROM` list
- `deny-all` — never respond (effectively disables that channel type)

**Webhook vs Polling:** Connectors like LINE, Twilio, WhatsApp Cloud API, and Google Chat use webhooks (they push messages to your server). You need a publicly accessible URL. Use ngrok for local development: `ngrok http 3000`.

**Rate limits:** Most platforms enforce rate limits. For Twitter especially, use conservative post intervals (90-180 minutes minimum).