> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw-simplex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Methods

> API reference for OpenClaw SimpleX gateway RPC methods used for runtime status, invites, addresses, verification, contact requests, groups, files, and operator-controlled SimpleX onboarding.

The plugin registers these gateway RPC methods for runtime diagnostics, one-time invite and SimpleX address automation, runtime user visibility, verification, contact-request review, group-link lifecycle, moderation, file transfer controls, and operator-controlled SimpleX link onboarding.

<Info>
  For day-to-day one-time invite and SimpleX address workflows, prefer the plugin CLI commands in [Example Commands](/reference/example-commands). Use these gateway methods when another system needs programmatic access to runtime status, runtime users, verification, contact-request review, group-link lifecycle, moderation, file controls, or link onboarding.
</Info>

## Prerequisites and behavior

* The target SimpleX account must be enabled and configured under <code>channels.openclaw-simplex</code>.
* The <code>simplex-chat</code> WebSocket runtime must be reachable for that account.
* If <code>accountId</code> is omitted or blank, the plugin uses the channel's default account.
* If the channel is not running, these methods ask OpenClaw to start <code>openclaw-simplex</code> for the target account and retry the SimpleX command.

## `simplex.invite.create`

Create a one-time connect link or return/create the account's reusable SimpleX address.

Request params:

```json theme={null}
{
  "mode": "connect",
  "accountId": "default"
}
```

`mode` supports:

* `connect` -> creates a one-time invitation link
* `address` -> returns or creates the account's reusable SimpleX address

Response highlights:

* `link`: the generated SimpleX link
* `qrDataUrl`: PNG QR image as a `data:` URL for the same link

Example response shape:

```json theme={null}
{
  "accountId": "default",
  "operation": "create-link",
  "mode": "connect",
  "link": "simplex:/contact#...",
  "qrDataUrl": "data:image/png;base64,..."
}
```

## `simplex.invite.list`

List the current SimpleX address and related contact state through the SimpleX runtime APIs.

Request params:

```json theme={null}
{
  "accountId": "default"
}
```

Response highlights:

* `addressLink`: current SimpleX address link if available
* `links`: extracted SimpleX address links seen in the responses
* `pendingHints`: pending contact hints, if exposed by the runtime
* `addressQrDataUrl`: PNG QR image as a `data:` URL for `addressLink`

Example response shape:

```json theme={null}
{
  "accountId": "default",
  "addressLink": "simplex:/contact#...",
  "links": ["simplex:/contact#..."],
  "pendingHints": [],
  "addressQrDataUrl": "data:image/png;base64,..."
}
```

## `simplex.invite.revoke`

Revoke the active SimpleX address through the SimpleX runtime API.

Request params:

```json theme={null}
{
  "accountId": "default"
}
```

Example response shape:

```json theme={null}
{
  "accountId": "default",
  "revoked": true
}
```

## `simplex.runtime.status`

Return runtime and account state for automation and Control UI surfaces.

Response highlights:

* `activeUser`: active SimpleX user profile, if available
* `address`: current SimpleX address metadata, if available
* `counts`: contact, group, and user counts
* `capabilities`: advisory runtime probe states for active user visibility, users, contacts, groups, live messages, TTL, moderation, verification, file controls, and experimental channel posture
* `filePolicy`: configured file auto-accept and size policy visibility
* `security`: WebSocket endpoint warnings and blocking posture
* `runtime`: active client, connection state, and latest runtime error
* `runtimeVersion`: SimpleX runtime version when the runtime exposes it through a probe response
* `wsUrl`: configured WebSocket URL

Example response shape:

```json theme={null}
{
  "accountId": "default",
  "configured": true,
  "mode": "external",
  "wsUrl": "ws://127.0.0.1:5225",
  "runtimeVersion": null,
  "runtime": {
    "activeClient": true,
    "connected": true,
    "lastError": null
  },
  "counts": {
    "contacts": 1,
    "groups": 0,
    "users": 1
  },
  "capabilities": {
    "version": {
      "state": "unknown",
      "command": "/version",
      "detail": "Runtime accepted /version but did not expose a version field.",
      "runtimeVersion": null,
      "value": null
    },
    "activeUser": {
      "state": "supported",
      "command": "/user",
      "runtimeVersion": null,
      "value": {
        "userId": 1
      }
    },
    "users": {
      "state": "supported",
      "command": "/users",
      "runtimeVersion": null,
      "count": 1
    },
    "contacts": {
      "state": "supported",
      "command": "/_contacts 1",
      "runtimeVersion": null,
      "count": 1
    },
    "groups": {
      "state": "supported",
      "command": "/_groups 1",
      "runtimeVersion": null,
      "count": 0
    },
    "liveMessages": {
      "state": "unknown",
      "detail": "Live replies are disabled in account config.",
      "runtimeVersion": null
    },
    "ttl": {
      "state": "unknown",
      "detail": "Message TTL is not configured.",
      "runtimeVersion": null
    },
    "moderation": {
      "state": "unknown",
      "detail": "Moderation support requires a real group/member target, so the advisory probe did not run it.",
      "runtimeVersion": null
    },
    "verification": {
      "state": "unknown",
      "detail": "Verification support requires a real contact target, so the advisory probe did not run it.",
      "runtimeVersion": null
    }
  }
}
```

## `simplex.runtime.doctor`

Return the same runtime status plus `ok` and `issues` fields for operator diagnostics.

Run `openclaw simplex runtime doctor` after enabling `streaming.nativeTransport` or message TTL. Capability probes are advisory WebSocket checks; they do not spawn, supervise, or manage the `simplex-chat` process, and they avoid destructive sends/deletes unless a caller explicitly supplies a real target through a higher-level operation.

## `simplex.runtime.users`

List SimpleX runtime users for the selected account.

Request params:

```json theme={null}
{
  "accountId": "default"
}
```

Response shape:

```json theme={null}
{
  "accountId": "default",
  "users": []
}
```

## `simplex.runtime.activeUser`

Return the active SimpleX runtime user for the selected account.

## `simplex.verification.*`

Expose contact verification commands when the connected <code>simplex-chat</code> runtime supports them. Older runtimes can return an <code>unsupported</code> response with the runtime error text.

* `simplex.verification.show`: show verification metadata for `contactId`
* `simplex.verification.check`: check verification metadata or a provided `code` for `contactId`

Example request:

```json theme={null}
{
  "accountId": "default",
  "contactId": 123,
  "code": "optional-code"
}
```

## `simplex.requests.*`

Manage pending SimpleX contact requests observed from runtime events.

* `simplex.requests.list`: list stored pending requests for an account
* `simplex.requests.accept`: accept a request by `contactRequestId`
* `simplex.requests.reject`: reject a request by `contactRequestId`

Example request:

```json theme={null}
{
  "accountId": "default",
  "contactRequestId": 123
}
```

## `simplex.groups.*`

Create SimpleX groups and manage group invite links through the configured SimpleX WebSocket runtime.

* `simplex.groups.create`: create a group from `displayName`, optional `fullName`, and optional `description`
* `simplex.groups.link.create`: create a group link for `groupId` and optional `role`
* `simplex.groups.link.list`: return the current group link plus QR data URL
* `simplex.groups.link.revoke`: delete the current group link
* `simplex.groups.member.block`: block or remove a member when the runtime supports it
* `simplex.groups.member.deleteMessages`: remove a member's group messages when the runtime supports it

Example group link request:

```json theme={null}
{
  "accountId": "default",
  "groupId": 42,
  "role": "member"
}
```

Example response shape:

```json theme={null}
{
  "accountId": "default",
  "groupId": 42,
  "role": "member",
  "link": "https://smp18.simplex.im/g#...",
  "qrDataUrl": "data:image/png;base64,..."
}
```

Example moderation request:

```json theme={null}
{
  "accountId": "default",
  "groupId": 42,
  "memberId": 77
}
```

## `simplex.files.*`

Control SimpleX file transfers through the active WebSocket runtime.

* `simplex.files.receive`: receive a pending file by `fileId`
* `simplex.files.cancel`: cancel a pending or active file transfer by `fileId`

Example request:

```json theme={null}
{
  "accountId": "default",
  "fileId": 123
}
```

## `simplex.connect.*`

Let an operator connect the SimpleX runtime identity to a SimpleX contact/address/group link.

* `simplex.connect.plan`: inspect what connecting to `link` would do
* `simplex.connect`: connect the active SimpleX user to `link`

`link` may be a native SimpleX link such as `simplex:/contact#...` or a short web link such as `https://smp18.simplex.im/g#...`.

Example request:

```json theme={null}
{
  "accountId": "default",
  "link": "https://smp18.simplex.im/g#..."
}
```

Example response shape:

```json theme={null}
{
  "accountId": "default",
  "connected": true,
  "result": {
    "type": "sentConfirmation"
  }
}
```

## Errors

| Code              | Meaning                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `INVALID_REQUEST` | The request params are invalid. For example, <code>simplex.invite.create</code> received an unsupported <code>mode</code>.                                                     |
| `UNAVAILABLE`     | The account is disabled/unconfigured, the channel runtime is unavailable, or the underlying SimpleX runtime API call failed. The response message includes the failure reason. |

## Related agent tools

The plugin also exposes these agent/tool-surface operations. They are not gateway RPC methods, but they cover the same invite and group administration flows from inside an agent run.

* `simplex_invite_create`
* `simplex_invite_list`
* `simplex_invite_revoke`
* `simplex_group_add_participant`
* `simplex_group_remove_participant`
* `simplex_group_leave`

These destructive tools require approval before execution:

* `simplex_invite_revoke`
* `simplex_group_remove_participant`
* `simplex_group_leave`