SDKs - Blujay API

Official Node.js and Python libraries, covering every endpoint in the API reference.

Node.js

npm install blujay

import { BlujayClient } from "blujay";

const client = new BlujayClient(); // reads BLUJAY_API_KEY

const sent = await client.chats.create({
  from: "+15555550100",
  to: ["+15555550123"],
  message: { parts: [{ type: "text", text: "Hi there!" }] },
});

console.log(sent.data.chat_id);

Works with Node.js 20 and later, Bun, Deno, Cloudflare Workers and Vercel Edge, with TypeScript types built in. GitHub

Python

pip install blujay

from blujay import Blujay

client = Blujay()  # reads BLUJAY_API_KEY

sent = client.chats.create(
    from_="+15555550100",
    to=["+15555550123"],
    message={"parts": [{"type": "text", "text": "Hi there!"}]},
)

print(sent.data.chat_id)

Works with Python 3.9 and later. Write from as from_. For async code, use AsyncBlujay. GitHub

What you get

Feature	What it does
Webhooks	Checks the signature and returns a typed event
Safe sends	Never retried on their own; retry with the same idempotency key
Read retries	Reads retry with backoff when a request fails temporarily
Errors	Typed errors with the error code and trace ID
Paging	Loop over a whole list without handling cursors
Types	Autocomplete and type checks for everything you send and receive
API key	Read from your environment, or passed to the client

Client settings

Pass any of these when you create the client:

const client = new BlujayClient({
  apiKey: "blu_your_api_key", // or set BLUJAY_API_KEY
  timeoutInSeconds: 20,       // 60 if not set
  maxRetries: 0,              // reads only; 2 if not set
});

client = Blujay(
    api_key="blu_your_api_key",  # or set BLUJAY_API_KEY
    timeout=20.0,                # seconds; 60 if not set
    max_retries=0,               # reads only; 2 if not set
)

Receive webhooks

Each library checks that a webhook came from Blujay and hands back the event. Give it the request body exactly as it arrived, before any JSON parsing. It rejects a bad signature, a missing header, or a timestamp more than 5 minutes off with WebhookVerificationError.

import { verifyWebhook } from "blujay";

const event = await verifyWebhook(
  rawBody, // the request body exactly as received
  request.headers,
  process.env.BLUJAY_WEBHOOK_SECRET!,
);

if (event.event_type === "message.received") {
  console.log(event.data.chat_id, event.data.text);
}

import os
from blujay import verify_webhook

event = verify_webhook(
    raw_body,  # the request body exactly as received
    request.headers,
    os.environ["BLUJAY_WEBHOOK_SECRET"],
)

if event.event_type == "message.received":
    print(event.data.chat_id, event.data.text)

Verifying Signatures shows how to get the raw body in Express and Flask.

Other languages

The libraries are optional. The API is plain HTTPS with JSON and a bearer token, so any language works, and every guide in these docs shows curl first:

curl https://api.blujay.io/v1/chats \
  -H "Authorization: Bearer $BLUJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15555550100",
    "to": ["+15555550123"],
    "message": {
      "parts": [{ "type": "text", "text": "Hi there!" }]
    }
  }'

Every endpoint is in the API reference, and the OpenAPI file works with code generators for other languages.

​Node.js

​Python

​What you get

​Client settings

​Receive webhooks

​Other languages