openloomi-connectors

> **Note:** If OpenLoomi readiness is unknown, use `openloomi-setup` first. If OpenLoomi Desktop is not installed, follow [Getting Started](https://openloomi.ai/docs/getting-started).

# 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](https://openloomi.ai/docs/glossary)).

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.

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

**Response:**
```json
{
  "accounts": [
    {
      "id": "int_xxx",
      "platform": "gmail",
      "externalId": "user@gmail.com",
      "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.

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

**Response:**
```json
{
  "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.

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

**Response:**
```json
{
  "success": true,
  "deletedAccountId": "int_xxx",
  "deletedBotIds": ["bot_xxx"]
}
```

---

### GET `/api/contacts` - Query Contacts