> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blujay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Send your first text from Node.js or Python in a few lines.

Official Node.js and Python libraries, covering every endpoint in the [API reference](https://docs.blujay.io/api-reference/introduction.md).

## Node.js

```bash theme={null}
npm install blujay
```

```typescript theme={null}
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](https://github.com/blujayhq/blujay-node)

## Python

```bash theme={null}
pip install blujay
```

```python theme={null}
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](https://github.com/blujayhq/blujay-python)

## 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:

```typescript theme={null}
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
});
```

```python theme={null}
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`.

```typescript theme={null}
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);
}
```

```python theme={null}
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](https://docs.blujay.io/webhooks/verify-signatures.md) 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:

```bash theme={null}
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](https://docs.blujay.io/api-reference/introduction.md), and the [OpenAPI file](https://docs.blujay.io/build-with-ai.md#machine-readable-docs) works with code generators for other languages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.