key option or store it on the account; the plugin sends it as the X-API-KEY header.
Things to know before you write:
- The API path carries
v1.0, notv1. A request to/v1/contactsanswers 405 Method Not Allowed, which reads like a routing bug rather than a wrong path. The plugin usesv1.0, as Superchat’s own examples do. - A missing key is 401 and a wrong key is 403. The 403 does not mean a scope is missing, so the plugin treats both as an auth failure.
- Sending reaches a real person.
messages.senddelivers on WhatsApp, SMS, Instagram, Messenger, Telegram or email, depending on thefromchannel and the recipient’s handle. The content has to suit that channel: a channel that only accepts templates will reject a plain text body. - One recipient per message. The spec caps
toat one entry, and the schema enforces it. - A contact needs a handle. A handle is the email address or phone number that identifies a contact on a channel, and at least one is required. Creating a contact with none would leave Superchat nothing to reach them on.
- The contact update route requires three fields.
contacts.updateis a PATCH, but it listsfirst_name,last_nameandgenderas required, so a caller changing one sends the other two back. Their values may be null; the keys may not be absent. - Snoozing needs two fields. Set
status: 'snoozed'together with asnoozed_untiltime, or leave snoozing alone. The schema rejects the mismatch. - Paging is by cursor.
aftertakes the last id of the previous page andbeforereads backwards. Only one may be set, andlimitis 1 to 100, defaulting to 50. - Rate limits. Each workspace gets 2500 requests per 5-minute window, shared across its API keys, and a trial workspace is capped at 10000 calls for its whole lifetime. Both answer 429, and the plugin retries three times with backoff.
- 22 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Superchat API key before the first call: More: API Key
pnpm corsair setup --plugin=superchat --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Read the messages in a conversationWhat’s next
API reference
Every
superchat.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.