@pilot-status/sdk

Official TypeScript SDK for the Pilot Status public API.

Installation

npm i @pilot-status/sdk

Quickstart (Node.js / TypeScript)

Create an API key in the dashboard and use it only on the backend.

import { PilotStatusClient } from "@pilot-status/sdk";

const client = new PilotStatusClient({
  apiKey: process.env.PILOT_STATUS_API_KEY!,
});

const accepted = await client.messages.send({
  templateId: "onboarding-test",
  destinationNumber: "+5511999999999",
  variables: { name: "John" },
});

const message = await client.messages.get(accepted.id);
console.log(message.status);

Management (projects, API keys, numbers)

These endpoints create resources within the scope (project + environment) of the current apiKey.

Projects

const project = await client.projects.create({
  name: "My Project",
  description: "Optional description",
});

const projects = await client.projects.list();

API keys

const key = await client.apiKeys.create({
  name: "Backend Key",
  retentionDays: 30,
});

const keys = await client.apiKeys.list();

Numbers (WhatsApp)

const created = await client.numbers.create({
  name: "My WhatsApp",
  number: "+5511999999999",
});
// created.qrcodeBase64 — QR image; created.pairingCode — letter code when available (else null)

const refreshed = await client.numbers.connect(created.instance.id);
// refreshed.qrcodeBase64, refreshed.pairingCode

const status = await client.numbers.getStatus(created.instance.id);

Opt-in check (destination authorization)

In LIVE, sending may require opt-in when using the Pilot Status WhatsApp number. You can check whether a destination is already authorized for your project:

const optIn = await client.messages.checkOptIn("+5511999999");

if (!optIn.authorized) {
  throw new Error(`Missing opt-in: ${optIn.reason}`);
}

Analytics

const stats = await client.analytics.getDashboardStats({ tz: "America/Sao_Paulo" });
console.log(stats.totalSent, stats.failureRate);

Webhooks (parse / validation)

import { parseCustomerWebhook } from "@pilot-status/sdk";

export async function handler(req: Request) {
  const payload = await req.json();
  const event = parseCustomerWebhook(payload);

  if (event.event === "message.failed") {
    console.log(event.data.errorMessage);
  }

  return new Response("ok");
}

Notes:

• Customer webhook payloads do not include: projectSlug, lastMessageId. Optional correlationId (same as HTTP 202 when present) may appear on outbound status events and on message.reply / message.received when correlated to a prior send.
• For outbound status events (message.sent, message.delivered, message.read, message.failed), messageId is the WhatsApp provider message id (key.id) and internalMessageId is the Pilot Status message id.
• message.received includes fromMe (boolean).
• message.group is delivered for inbound group messages (includes groupName).
• message.newsletter is delivered for inbound WhatsApp channel / newsletter messages (@newsletter, includes newsletterId).
• Supported events in the parser: message.sent, message.delivered, message.read, message.failed, message.reply, message.received, message.group, message.newsletter, optin.created.

Errors

For non-2xx responses, the SDK throws an HTTP error with status and, when available, body.

import { PilotStatusHttpError } from "@pilot-status/sdk";

try {
  await client.messages.send({
    templateId: "x",
    destinationNumber: "+5511999999999",
    variables: {},
  });
} catch (err) {
  if (err instanceof PilotStatusHttpError) {
    console.log(err.status, err.body);
  }
}