Happy Scribe plugin

• Credit-spending creates. transcriptions.create, translations.createTask and meetings.create spend Happy Scribe credits. orders.create stays incomplete (unpaid) until orders.confirm or an explicit confirm: true; human orders are then irreversible.
• Four async lifecycles. Transcriptions report state until automatic_done; exports state until ready with a download_link; translation tasks state until done; meetings report status (a different field) until completed. The plugin declares jobs for all four, so the agent’s get_job follows them.
• Rate limits. The transcription-creation endpoint allows about 200 requests per user per hour; a 429 carries retry_in_seconds in the body and the plugin waits exactly that before retrying.
• Pagination is inconsistent. transcriptions.list pages from 0 with perPage default 5; companies.list and people.list page from 1 with perPage up to 100; memberships.list pages from 1, 25 at a time. All return nextPageUrl when another page exists.
• Deleting. transcriptions.delete moves the file to the Trash; pass permanent: true to delete it for good.
• Intelligence API is enrollment-gated. companies, people and the person/company filters on transcriptions.list answer 404 until the organization is enrolled; contact Happy Scribe support to enroll.
• Local files. uploads.getSignedUrl returns a pre-signed S3 URL; upload the file bytes there yourself, then pass a tmpUrl to transcriptions.create.
• Webhooks. Configure a meeting webhook in Settings, Webhooks and set its signing secret (whsec_...) as the plugin’s webhookSecret. Deliveries are HMAC-signed twice; unsigned or stale deliveries are rejected. If your own route receives them, pass the raw body (await request.text()) to processWebhook, not request.json(): transcripts carry numbers like 0.0 that change when re-serialized, and the signature check then fails. The payload does not name the organization, so with multi-tenancy pass the tenant as query.tenantId (for example from ?tenantId= on the endpoint URL).
• Languages. Language codes are BCP-47 (en-GB, es); human services are available only for some of them.

• 28 typed API operations
• 7 incoming webhook event types

​

Setup

npm install corsair @corsair-dev/happyscribe better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/happyscribe better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/happyscribe better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/happyscribe better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { happyscribe } from '@corsair-dev/happyscribe';

export const corsair = createCorsair({
	plugins: [
		happyscribe(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

happyscribe()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'happyscribe',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.happyscribe.api.transcriptions.list({ organizationId: 123, perPage: 25 });

const tenant = corsair.withTenant('acme');
await tenant.happyscribe.api.transcriptions.create({
	organizationId: 123,
	name: 'My Interview',
	language: 'en-GB',
	tmpUrl: 'https://example.com/my_media.mp3',
});

​

Webhooks

​

What’s next