openloomi-connectors

Note: If you haven't downloaded or installed openloomi yet, please refer to Getting Started for installation instructions.

OpenLoomi Connectors Skill

OpenLoomi Connectors handle two directions: pulling Signals in from your authorized platforms and pushing approved Actions back out through the same channel. OpenLoomi ships them through two layers:

• Native (this skill) — 7 messaging-platform bots maintained directly by OpenLoomi: Telegram, WhatsApp, iMessage, Lark/Feishu, DingTalk, QQ, and WeChat. The openloomi-connectors CLI covers OAuth / app-credential / QR / interactive setup, list, status, disconnect, contact query, and message send for these.
• Composio (paired composio skill) — a hosted OAuth broker that authorizes ~1000+ apps including Slack, Discord, X, Gmail, Outlook, Google Calendar/Drive/Docs, GitHub, Notion, Linear, HubSpot, LinkedIn, Jira, Asana. Composio handles "is this user authorised?" and stores the tokens; OpenLoomi's Loop channels consume the events as Signals (see Glossary — Composio / Loop channel).

When the user asks "what am I connected to?" or "list my accounts", run both — list-accounts here and the composio connection listing — and present the union. Keep auth, OAuth, and disconnect flows native to each skill.

This skill does not manage Loop channels, custom decision types, or classifier rules — those are openloomi-loop's job.

---

What is openloomi?

OpenLoomi is an open-source AI coworker, driven by an attention agent — a desktop app (Loomi) that connects your authorized tools, builds a local knowledge graph of people / projects / decisions, and surfaces the day's decisions as one-tap bubbles you Approve. It runs locally (local-first, AES-256), supports Skills + Plugins so any Agent Runtime (Claude Code, Codex, OpenCode, Hermes, OpenClaw) can plug into the same resident desktop. See openloomi-feature-guide for the full picture.

Continuous sync

Connectors are the per-platform input that Loop reads on every tick. When you authorize a platform, OpenLoomi continuously syncs (with your permission):

• Raw messages and communications
• Meetings and calendar events
• Emails and tweets
• Voice calls
• Notes, screen captures, and captured ideas

The aggregated stream feeds OpenLoomi's Memory and the Signals Loop polls on every tick — so an unprompted reminder, a contextual reply draft, or a Decision Card arrives with full historical grounding instead of starting from scratch.

---

Supported Platforms (7)

The CLI list-platforms returns these 7 platforms. Other connectable platforms (Slack, Discord, X, Gmail, Outlook, LinkedIn, Google Calendar, Google Drive, Google Docs, HubSpot, Notion, etc.) are managed via the desktop UI or the composio skill — see "Platform Connection Methods" below for details.

ID	Display Name	Aliases
telegram	Telegram	tg
whatsapp	WhatsApp
imessage	iMessage
feishu	Lark/Feishu	lark, 飞书
dingtalk	DingTalk	钉钉
qqbot	QQ	qq, qq_bot
weixin	WeChat	wechat, 微信, wechat_work, wecom, 企业微信

---

Authentication

The CLI auto-reads your token from ~/.openloomi/token (base64 encoded JWT).

Local API Access

The local API server runs on port 3414 (fallback: 3515). If 3414 is unavailable, try 3515.

---

API Endpoints

Integration Accounts

GET /api/integrations/accounts - List Connected Accounts

Returns all connected platform accounts for the authenticated user.

curl http://localhost:3414/api/integrations/accounts \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "accounts": [
    {
      "id": "int_xxx",
      "platform": "gmail",
      "externalId": "[email protected]",
      "displayName": "My Gmail",
      "status": "active",
      "metadata": {},
      "createdAt": "2024-01-01T00:00:00Z",
      "botId": "bot_xxx"
    }
  ]
}

Note: Each account includes a botId field which is used for send-reply and other bot operations.

---

OAuth Start Endpoints

GET /api/integrations/slack/oauth/start?userId=<userId> - Start Slack OAuth

Returns the Slack OAuth authorization URL. The CLI opens this URL in the browser for the user to complete authorization.

curl "http://localhost:3414/api/integrations/slack/oauth/start?userId=<userId>"

Response:

{
  "authorizationUrl": "https://slack.com/oauth/v2/authorize?...",
  "state": "userId:uuid"
}

GET /api/integrations/discord/oauth/start?userId=<userId> - Start Discord OAuth

Returns the Discord OAuth authorization URL.

GET /api/integrations/x/oauth/start?userId=<userId> - Start X OAuth

Returns the X/Twitter OAuth authorization URL.

---

OAuth Exchange Endpoints

GET /api/integrations/slack/oauth/exchange?code=<code>&state=<state> - Exchange Slack Code

Exchange OAuth code for Slack access.

GET /api/integrations/discord/oauth/exchange?code=<code>&state=<state> - Exchange Discord Code

Exchange OAuth code for Discord access.

---

OAuth Callbacks

Platform	Endpoint
Feishu	POST /api/feishu/listener/init
DingTalk	POST /api/dingtalk/listener/init
QQ Bot	POST /api/qqbot/listener/init
WeChat	POST /api/weixin/listener/init
Telegram	POST /api/telegram/user-listener/init
WhatsApp	POST /api/whatsapp/register-socket
iMessage	POST /api/imessage/init-self-listener

---

DELETE /api/integrations/:id - Disconnect Account

Delete a connected integration account.

curl -X DELETE http://localhost:3414/api/integrations/int_xxx \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "success": true,
  "deletedAccountId": "int_xxx",
  "deletedBotIds": ["bot_xxx"]
}

---

GET /api/contacts - Query Contacts

Query user contacts with optional filtering and pagination.

curl "http://localhost:3414/api/contacts?name=John&page=1&pageSize=10" \
  -H "Authorization: Bearer $TOKEN"

Parameters:

• name (string, optional) - Filter contacts by name (partial match)
• page (number, default 1) - Page number
• pageSize (number, default 10) - Items per page (max 100)

Response:

{
  "success": true,
  "contacts": [
    {
      "id": "contact_xxx",
      "name": "John Doe",
      "type": "email",
      "botId": "bot_xxx",
      "platform": "gmail"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalCount": 50,
    "totalPages": 5,
    "hasMore": true,
    "hasPrevious": false
  }
}

---

POST /api/messages - Send Message

Send a message via a connected platform bot.

curl -X POST http://localhost:3414/api/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "bot_xxx",
    "recipients": ["John"],
    "message": "Hello!",
    "subject": "Optional subject"
  }'

Parameters:

• botId (string, required) - The bot ID to send from
• recipients (array, required) - List of recipient names
• message (string, required) - Message content
• subject (string, optional) - Email subject line
• cc (array, optional) - CC recipients
• bcc (array, optional) - BCC recipients

Note: botId is returned by list-accounts in the botId field (different from account id).

---

Platform Aliases Reference

Aliases are case-insensitive and support both English and Chinese:

Alias	Platform
tg	telegram
wechat, 微信	weixin
lark, 飞书	feishu
钉钉	dingtalk
qq, qq_bot	qqbot

---

Desktop UI

Users can also authorize accounts directly through the openloomi desktop application without using CLI commands.

Adding Account Authorization via Desktop UI

1. Open openloomi desktop app on your computer

2. Navigate to Settings (gear icon in the sidebar or top-right menu)

3. Go to Integrations tab/section

4. Click on the platform you want to connect (e.g., Telegram, Slack, Discord, Gmail, etc.)

5. Follow the platform-specific authorization flow:

   • OAuth platforms (Slack, Discord, X/Twitter): Click "Connect" → you'll be redirected to the platform's authorization page in your browser → Approve the permissions → you'll be redirected back
   • App Password platforms (Gmail, Outlook): Enter your email and app password
   • App Credentials platforms (DingTalk, Feishu, QQ): Enter your appId and appSecret
   • QR/Interactive platforms (WhatsApp, Telegram, iMessage): Scan the QR code or follow the in-app instructions

6. Verify connection — once authorized, the platform will show as "Connected" with a green checkmark

Managing Connected Accounts

• List connected accounts: Settings → Integrations → shows all connected platforms with status
• Disconnect account: Settings → Integrations → click on connected platform → "Disconnect" or remove
• Check status: Connected platforms show green "Active" badge; expired/disconnected shows red "Inactive" badge

---

CLI Script

Quick Start

# List all supported platforms
node $SKILL_DIR/scripts/openloomi-connectors.cjs list-platforms

# List all connected accounts (includes botId for send-reply)
node $SKILL_DIR/scripts/openloomi-connectors.cjs list-accounts

# Cross-source audit: openloomi-native + composio-linked accounts (run together, present union)
node $SKILL_DIR/scripts/openloomi-connectors.cjs list-accounts
# In parallel, invoke the `composio` skill (e.g. `composio list-connections` via composio-cli,
# or `mcp__composio__COMPOSIO_MANAGE_CONNECTIONS` with action: "list")

# Check connection status for a platform
node $SKILL_DIR/scripts/openloomi-connectors.cjs status telegram

# Connect a platform (opens browser for OAuth)
node $SKILL_DIR/scripts/openloomi-connectors.cjs connect slack

# Disconnect an account by ID
node $SKILL_DIR/scripts/openloomi-connectors.cjs disconnect int_xxx

# Query contacts
node $SKILL_DIR/scripts/openloomi-connectors.cjs query-contacts --name=John --page=1 --pageSize=10

# Send a message (requires botId from list-accounts)
node $SKILL_DIR/scripts/openloomi-connectors.cjs send-reply --botId=bot_xxx --recipients=John --message="Hello!"

Commands

Command	Description
list-platforms	List all 7 supported platforms with IDs and aliases
list-accounts	List all connected integration accounts (includes botId)
status <platform>	Check if a platform is connected (e.g., telegram, slack)
connect <platform> [options]	Connect a platform (OAuth, App Password, or App Credentials)
disconnect <accountId>	Disconnect a specific account by ID
query-contacts [options]	Query contacts (--name=, --page=, --pageSize=)
send-reply --botId= --recipients= --message=	Send a message via REST API

Platform Connection Methods

Method	Platforms
OAuth (auto-opens browser)	slack, discord, x
App Password	gmail --email=x --password=xxxx, outlook --email=x --password=xxxx
App Credentials	dingtalk --clientId=x --clientSecret=x, feishu --appId=x --appSecret=x, qq --appId=x --appSecret=x
iLink Token	wechat --token=x
Browser Required (QR/interactive)	whatsapp, telegram, imessage

---

AI Agent Workflow

Triggered when the user asks about:

1. Connecting a platform - "connect telegram", "link my slack"
2. Listing integrations - "show my connected accounts", "what platforms am I connected to"
3. Checking status - "is my github connected?", "telegram status"
4. Disconnecting - "disconnect my discord", "remove whatsapp"
5. Querying contacts - "show my contacts", "find John in contacts"
6. Sending messages - "send email to John", "reply to that message"
7. Cross-source account audit - "show everything I'm connected to (openloomi + composio)", "list all linked accounts across both" → run list-accounts here and the composio skill in parallel, then present the union

Execution Flow:

1. Identify intent - connect / list / status / disconnect / query-contacts / send-reply
2. Resolve platform - use alias normalization (e.g., gh -> github)
3. Execute command - use Bash tool
4. Format output - report results naturally in user's language

Note on send-reply: The botId is returned by list-accounts in the botId field.