Skip to main content
@custral/sdk is the official server-side client for the /v1 REST API. It wraps every /v1 resource (records, conversations, documents, lists, journeys, quotes, billing and the rest, listed under Resources) and verifies Stripe-style webhook signatures. Zero runtime dependencies (native fetch + node:crypto), ESM + CJS, fully typed.
This is a secret-key SDK. A secret key (sk_…) must never ship to a browser. For usage tracking with a publishable key use @custral/js, and for the chat widget use @custral/widget.

Install

Quickstart

Create a key in Settings → Developers → Applications and grant it the scopes each endpoint needs.

Configuration

Resources

One new Custral({apiKey}) exposes 19 resources. Each method calls one /v1 route, needs that route’s scope, and returns the response’s data. The reference page for each has the request and response shapes. custral.me() needs no scope. It returns the key’s workspace, environment and scopes.
journeys.forRecord currently fails with a not-found error, because its route is matched by the record-retrieve route first. See Customer journeys.

A few more resources

Records

Conversations

View, manage, and ingest conversations: the loop a custom bridge (e.g. an iMessage or WhatsApp middleware) runs.

Objects

Identity & MCP

Errors

Every failure throws a typed CustralError carrying a machine-readable code, an HTTP statusCode, the requestId, and the rateLimit budget.
The exported error classes are CustralAuthenticationError (401), CustralPermissionError (403), CustralNotFoundError (404), CustralInvalidRequestError (400), CustralRateLimitError (429), CustralAPIError (5xx), and CustralConnectionError. maxRetries retries only safe failures, 429s always, and 5xx / connection errors only for idempotent GETs (a failed create is never auto-retried).

Webhooks

Custral delivers events as signed HTTP POSTs (X-Custral-Signature: t=<ts>,v1=<hmac>). Register listeners with on(...) and verify + dispatch with webhooks.express() (mount with a raw body parser so the signed bytes survive):
Or verify a single delivery manually (Stripe-style):
Webhook delivery is at-least-once. Make listeners idempotent. See Webhooks for the event catalog.

Troubleshooting

See also