Identity
key, name, version, sdk and vendor — what each is used for, the patterns they must match, and the SDK constraint syntax the registry understands.
The five top-level scalars name the connector. All five are required.
{
"key": "example",
"name": "Example",
"version": "1.0.0",
"sdk": "^1.0",
"vendor": "Acme"
}key
The connector's machine name: lower case, matching ^[a-z][a-z0-9_-]*$, unique across every connector installed on an application. It is reused everywhere the connector has to be addressed, so choose it once and never change it:
| Where | Form | Example |
|---|---|---|
| The connector's tables | prefix <key>_ | example_bots |
| Its configuration file | config/connector-<key>.php | config('connector-example.…') |
| Its Blade views | namespace connector-<key>:: | connector-example::install |
| A resource kind as stored | <key>:<kind> | example:room |
| A native payment provider | <key>:<provider> | example:coins |
| The send rate limiter | connector:<key> | connector:example |
| The inbound middleware | connector.inbound:<key> | applied to routes/inbound.php |
| Availability and pausing | Subscriby's own switches, by key | example |
| Public pages | /connectors/<key> | /connectors/example |
The kit's manifest.key_matches rule fails a package whose registered key differs from the file's, and migrations.own_tables_only reads the prefix from it.
name
The display name, exactly as the marketplace card, the connector's page, the dashboard's Connectors tab and the API show it. It also fills the marketing site's :platform token when the connector is available, so write it as the platform is spelt ("Telegram", not "telegram bot").
version
The package's own semantic version, matching ^\d+\.\d+\.\d+. Shown on the connector's page under Version and compared with the file by manifest.file_is_the_source. Bump it with every release of the package; it has nothing to do with the SDK's version.
sdk
The constraint on subscriby/connector-sdk the package was built against. The registry checks it at boot against the SDK the application runs (Subscriby\Connector\Sdk::VERSION, currently 1.0.0) and refuses an incompatible package before a single call, rather than at the first method that no longer exists. The kit repeats the check as manifest.sdk_constraint.
The syntax is the small subset of Composer's the SDK evaluates itself, so no Composer library is needed at runtime:
| Constraint | Admits |
|---|---|
^1.0 | >= 1.0.0 and < 2.0.0 (below 1.0, a caret stops at the next minor: ^0.4 is < 0.5.0). |
~1.2 | >= 1.2.0 and < 2.0.0; ~1.2.3 is >= 1.2.3 and < 1.3.0. |
>=1.1, >1.1, <=1.4, <2.0 | The comparison, on the version given. |
1.2 | 1.2.*; a bare 1 is 1.*. |
1.2.3 | Exactly that version. |
| `a |
Write ^1.0 unless the package needs something a later minor introduced, in which case name that minor (^1.2). The CHANGELOG lists what each SDK version added.
vendor
Who publishes the connector, as the connector's page shows it under Made by. Free text; write the organisation's name as it appears on its own site.
Vendor is not Official
The Official badge, the availability of the connector and its place on the marketplace are set by Subscriby's configuration, never by the file. A package whose vendor reads "Subscriby" is still a Community connector until Subscriby configures it as official, and native_payments stays refused for it.
How is this guide?
connector.json
The one file that says what a connector is, what it can do, how it talks and how the marketplace presents it — where it lives, how it is read, and a complete example.
install
How a creator connects the connector — the install mode, the scopes, and the field specification the install and settings forms are declared with.