Channels
Channel Photon
By Photon Beta plugin for OpenClaw
Install
openclaw plugins install npm-pack:/absolute/path/openclaw-plugin-photonbeta-0.1.3.tgzConfiguration Example
{
"plugins": {
"entries": {
"photonbeta": { "enabled": true }
}
},
"channels": {
"photonbeta": {
"enabled": true,
"projectId": "YOUR_PHOTON_PROJECT_ID",
"apiKeyEnv": "PHOTON_API_KEY",
"platforms": ["imessage", "sms", "email", "telegram", "whatsapp", "whatsapp_business"],
"dmPolicy": "pairing",
"groupPolicy": "disabled",
"markRead": true
}
}
}README
# Photon for OpenClaw
Connect [OpenClaw](https://github.com/openclaw/openclaw) to iMessage, SMS/MMS, email, Telegram, WhatsApp, and WhatsApp Business through [Photon Beta](https://photon.codes/docs/beta/get-started/imessage).
The plugin uses Photon's project API and an authenticated outbound event connection. Your gateway does not need a public webhook endpoint.
## Features
- Send and receive text, images, and file attachments.
- Route direct and group conversations to OpenClaw agents, with separate sessions for each account and peer.
- Support email subjects, plain text, HTML, and attachments.
- Send typing indicators and optional read receipts.
- Use reactions, edits, deletion, and polls on supported platforms.
- Control access with pairing, sender allowlists, and group mention rules.
- Connect multiple Photon projects with separate credentials.
- Resume event processing after reconnects and interrupt active replies with `/stop`.
## Supported platforms
| Platform | Text and attachments | Reactions, edits, deletion, polls |
| --- | --- | --- |
| iMessage | Yes | Not exposed by this plugin |
| SMS/MMS | Yes | Not exposed by this plugin |
| Email | Yes | Not exposed by this plugin |
| Telegram | Yes | Not exposed by this plugin |
| WhatsApp | Yes | Yes |
| WhatsApp Business | Yes | Yes |
Availability depends on your Photon project, platform configuration, and sender permissions. Voice calls are not supported.
## Requirements
- OpenClaw **2026.10.5**
- Node.js **24.16.0 or newer**
- A Photon Beta project with the messaging platforms you want to use
- A project API key with `project:read` and `project:write` permissions
## Installation
Clone and package the plugin:
```sh
git clone https://github.com/imrasalghul/openclaw-channel-photon.git
cd openclaw-channel-photon
npm ci
npm pack
```
Install the resulting archive on the machine running OpenClaw:
```sh
openclaw plugins install npm-pack:/absolute/path/openclaw-plugin-photonbeta-0.1.3.tgz --force
```
## Configuration
Make your API key available to the OpenClaw gateway as `PHOTON_API_KEY`, then add the following to your OpenClaw configuration:
```json
{
"plugins": {
"entries": {
"photonbeta": { "enabled": true }
}
},
"channels": {
"photonbeta": {
"enabled": true,
"projectId": "YOUR_PHOTON_PROJECT_ID",
"apiKeyEnv": "PHOTON_API_KEY",
"platforms": ["imessage", "sms", "email", "telegram", "whatsapp", "whatsapp_business"],
"dmPolicy": "pairing",
"groupPolicy": "disabled",
"markRead": true
}
}
}
```
Include only the platforms you have configured in Photon. If OpenClaw runs as a service, set the environment variable in the service environment. Alternatively, replace `apiKeyEnv` with `apiKeyFile`, using an absolute path to a private file containing the key.
Apply the configuration:
```sh
openclaw config validate
openclaw gateway restart
openclaw channels status --probe
```
### Pairing
Send a message to your Photon identity. New direct-message senders receive a pairing code. Approve the sender, then send another message:
```sh
openclaw pairing list photonbeta --account default
openclaw pairing approve photonbeta CODE --account default
```
To use a fixed allowlist, set `dmPolicy` to `allowlist` and add `allowFrom` entries such as `imessage:+15551234567`, `email:person@example.com`, or a Photon User ID.
### Groups
Groups are disabled by default. To enable selected groups, add these settings to the channel configuration:
```json
{
"groupPolicy": "allowlist",
"groups": ["imessage:YOUR_SPACE_ID"],
"groupAllowFrom": ["imessage:YOUR_USER_ID"],
"requireMention": true,
"mentionPatterns": ["\\bAssistant\\b"]
}
```
Use Photon Space and User IDs. Mention patterns are case-insensitive regular expressions; OpenClaw's agent mention patterns are also supported.
### Proactive messages
Replies automatically use the receiving agent's identity. To initiate a conversation, configure the relevant Photon agent User ID:
```json
{
"senderIds": {
"sms": "YOUR_SMS_AGENT_USER_ID",
"email": "YOUR_EMAIL_AGENT_USER_ID"
}
}
```
Then send through OpenClaw:
```sh
openclaw message send --channel photonbeta --target 'sms:+15551234567' --message 'Hello'
```
Targets use `platform:handle` or `platform:SPACE_ID:AGENT_USER_ID`. Use `whatsapp_business` for WhatsApp Business. Photon controls whether a sender can initiate a conversation; shared iMessage lines require the assigned peer to message first.
### Multiple accounts
Define an account for each Photon project:
```json
{
"channels": {
"photonbeta": {
"defaultAccount": "personal",
"dmPolicy": "pairing",
"accounts": {
"personal": {
"projectId": "YOUR_PERSONAL_PROJECT_ID",
"apiKeyEnv": "PHOTON_PERSONAL_API_KEY",
"platforms": ["imessage", "sms"]
},
"work": {
"projectId": "YOUR_WORK_PROJECT_ID",
"apiKeyEnv": "PHOTON_WORK_API_KEY",
"platforms": ["email", "telegram"]
}
}
}
}
}
```
Each account needs its own project, credential reference, and any proactive sender mappings. Use OpenClaw bindings with channel `photonbeta` and the account ID to select an agent.
## Media and iMessage
Image understanding requires an image-capable model configured in OpenClaw. Audio-file understanding requires OpenClaw transcription support. Native recordings made inside Apple Messages may not be exposed by Photon Beta.
Shared iMessage Spaces can reject threaded replies. For ordinary text and files, the plugin falls back to an unthreaded send when Photon explicitly rejects threading.
This plugin uses the Photon Beta API. iMessage effects, conversation backgrounds, rich text effects, App cards, and other features of the separate Advanced iMessage SDK are not supported.
## Options
| Setting | Default | Purpose |
| --- | --- | --- |
| `markRead` | `false` | Send read receipts for accepted incoming messages |
| `mediaMaxMb` | `20` | Maximum attachment size in MB, up to 100 |
| `requestTimeoutMs` | `30000` | HTTP request timeout |
| `maxPending` | `128` | Maximum pending ordinary events |
| `requireMention` | `true` | Require a mention in group conversations |
Keep the plugin's `photonbeta/` directory under OpenClaw's state directory across upgrades. Run only one consumer against each account's state. Version 0.1.3 can read older state formats; older plugin versions cannot read state written by 0.1.3.
## Contributing
Issues and pull requests are welcome. Run `npm run check` before submitting changes.
## License
[MIT](LICENSE)
channels
Comments
Sign in to leave a comment