TypeScript SDK

Any other language: generate a client from the OpenAPI document below, or call the REST API directly.

import { Blueticked } from "@blueticked/sdk";

const apiKey = process.env.BLUETICKED_API_KEY;
if (!apiKey) throw new Error("Set BLUETICKED_API_KEY to your test key");

// baseUrl is the client's default, shown so you know where requests go.
const bt = new Blueticked({
  apiKey,
  baseUrl: "https://app.blueticked.com/api",
});

// to.create makes the recipient a contact in the same call if they are not one yet.

// 202 means QUEUED. Delivery arrives on a webhook, or poll bt.messages.get(id).
const { message_id, status } = await bt.messages.send({
  channel: "whatsapp",
  to: { phone: "+27800000001", create: true, first_name: "Sam" },
  body: "Hello from the Blueticked sandbox.",
});
console.log(message_id, status); // "763c4dc3-d46b-4c10-8bd4-3f233a933ea0" "queued"

// Cursor pagination, walked for you.
for await (const contact of bt.contacts.listAll({ limit: 100 })) {
  console.log(contact.phone); // "+27800000001"
}

Requests go to https://app.blueticked.com/api/v1/…. The client adds /v1 itself, so a baseUrl you pass ends at /api.

Branch on its code, never on the message.

import { Blueticked, BluetickedError } from "@blueticked/sdk";

const apiKey = process.env.BLUETICKED_API_KEY;
if (!apiKey) throw new Error("Set BLUETICKED_API_KEY to your test key");
const bt = new Blueticked({ apiKey });

try {
  // Nobody has created this contact, so the send is refused.
  await bt.messages.send({
    channel: "whatsapp",
    to: { phone: "+27800000099" },
    body: "Hello from the Blueticked sandbox.",
  });
} catch (err) {
  if (!(err instanceof BluetickedError)) throw err;
  console.log(err.status, err.code); // 404 "not_found"
  console.log(err.message);          // names the phone and the fix
  console.log(err.requestId);        // "req_b2e3d610e10f1b07468721ee98f0e1d2": quote it to support
  console.log(err.nextSteps);        // [{ action, by: "caller" | "human" | "waiting" }]
  if (err.needsHuman) {
    // A person has to act (connect a channel, top up); retrying cannot help.
  }
}

code and status

The machine-readable code from the Errors page, and the HTTP status. Status 0 means no answer came back, and the code is the client's own: timeout, network_error, invalid_api_key, browser_context_refused or auto_pagination_limit. retry_unsafe comes either way: a POST that cannot deduplicate failed mid-flight (status 0) or answered a 500, 502, 503 or 504, and it may have gone through, so check before retrying.

requestId

The request's id. Quote it to support and we can find the call.

nextSteps

What to do about it, each step marked by who acts: caller, human or waiting. needsHuman is true when a person must act, so no retry can succeed; isTransient when the remedy is time.

details

Extra context some codes carry, such as what still uses a resource you tried to delete.

The 7 below are newer than the package: call them over REST until the next release.

Typed requests and responses

The types are written by hand and checked against the OpenAPI document as it stood when 0.8.0 was released. Endpoints added since are in the table above; for any language, generate types from the live document below.

Pagination you do not write

listAll() walks the cursor for you. Cursors stay opaque: the SDK never constructs one.

Retries and idempotency

GET, PATCH, PUT and DELETE, and the POSTs that deduplicate (the client adds their Idempotency-Key itself), are retried up to twice by default (maxRetries) on 429, 500, 502, 503 and 504. A POST that cannot deduplicate is retried only on 429, and a refusal a person must clear is never retried, so a retry never sends twice.

Server-side only

Your API key is a bearer secret, so the client refuses to start in a browser. Call Blueticked from your server.

MIT licensed; the README on npm lists every method.

import { Blueticked } from "@blueticked/sdk";

const bt = new Blueticked({
  apiKey: process.env.BLUETICKED_API_KEY!,
  timeoutMs: 15000, // default 30000
  maxRetries: 0, // default 2; 0 turns retries off
});

// Your own Idempotency-Key for one call:
await bt.contacts.upsert({ phone: "+27821234567" }, { idempotencyKey: "crm-sync-1001" });

// An endpoint newer than your package, with the same auth, retries and errors:
const res = await bt.request<{ ok: boolean }>("GET", "/v1/readiness");

// Verify and parse a webhook delivery in one call (throws on a bad signature):
const event = await bt.webhooks.constructEvent(rawBody, req.headers, process.env.BLUETICKED_WEBHOOK_SECRET!);

timeoutMs

How long one request may take, in milliseconds. The default is 30000.

maxRetries

How many times a retryable failure is tried again. The default is 2; 0 turns retries off.

idempotencyKey

A per-call option: your own Idempotency-Key, always sent when you give one (the client otherwise makes one for the POSTs that deduplicate).

bt.request()

Calls any endpoint, including one newer than the package, with the same auth, retries and error type. Declare the response type yourself.

bt.isTestMode

True when the client holds a blu_test_ key.

bt.webhooks.constructEvent()

Verifies a delivery and parses it in one call. Pass the raw body and the whole header set; it throws on a bad or stale signature, so answer 401 from your catch.

The document is public and needs no key.

npx openapi-typescript https://app.blueticked.com/api/v1/openapi.json \
  -o ./src/blueticked.d.ts

Prefer to let an agent write the integration? Hand it the whole API in one fetch.