TypeScript SDK

npm install @usebluebot/sdk

import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

const message = await client.messages.send({
  to: '+15555550123',
  text: 'Hi Maria, the showing at 412 Oak St is confirmed for 3 PM.',
  metadata: { crm_id: '48213' },
});

console.log(message.id, message.state); // msg_1Hq2LxW9cVbN3mKpRtYs0a queued
if (message.hold) console.log(`Waiting: ${message.hold.description}`);

// Schedule one. It stays a draft you can change until it's due.
const reminder = await client.messages.send({
  to: '+15555550123',
  text: 'Reminder: your cleaning is tomorrow at 10 AM. Reply C to confirm.',
  sendAt: new Date('2026-11-20T15:00:00Z'),
  metadata: { appointment_id: 'apt_9921' },
});

// Move it, or change the words, before it goes.
await client.messages.update(reminder.id, { sendAt: '2026-11-21T15:00:00Z' });

// Or cancel it. A text the Mac already took can't be called back: that's a ConflictError.
await client.messages.cancel(reminder.id);

// Text an existing group chat instead of one person.
await client.messages.send({ chatId: 'chat_1Hq2LxW9cVbN3mKpRtYs0a', text: 'Running 10 minutes late.' });

// Insist on iMessage (no SMS fallback), and give up if it hasn't gone in an hour.
await client.messages.send({
  to: 'maria@example.com',
  text: 'Here is the link you asked for.',
  service: 'imessage',
  expiresAt: new Date(Date.now() + 60 * 60 * 1000),
});

// Read one.
const sent = await client.messages.get('msg_1Hq2LxW9cVbN3mKpRtYs0a');

// Settle a text the Mac couldn't confirm: you checked and it went, or send it again.
await client.messages.resolve('msg_1Hq2LxW9cVbN3mKpRtYs0a', { action: 'mark_sent' });

import { openAsBlob } from 'node:fs'; // Node 20 and newer

const photo = await client.files.upload(await openAsBlob('house.jpg'), { filename: 'house.jpg' });
await client.messages.send({ to: '+15555550123', text: 'Here is the front of the house.', files: [photo.id] });

import { readFile } from 'node:fs/promises';

const bytes = await readFile('menu.pdf');
const menu = await client.files.upload(new Blob([bytes], { type: 'application/pdf' }), { filename: 'menu.pdf' });

const response = await fetch('https://example.com/flyer.png');
const flyer = await client.files.upload(await response.blob(), { filename: 'flyer.png' });

// One page.
const page = await client.messages.list({ direction: 'in', limit: 50 });
console.log(page.data.length, page.hasMore, page.nextCursor);

// Every item, page after page.
for await (const message of client.messages.list({ state: 'failed', since: '2026-11-01T00:00:00Z' })) {
  console.log(message.to, message.failure?.reason);
}

// By hand.
let current = await client.chats.list({ isGroup: true });
while (current) {
  for (const chat of current.data) console.log(chat.name);
  current = current.hasNextPage() ? await current.getNextPage() : null;
}

// What did the newest chat with this number use? Reads your own history through your Mac.
const lookup = await client.lookup('+15555550123');
console.log(lookup.service, lookup.basis); // 'imessage' 'history'

// Is the Mac there, and does it need you?
const device = await client.device.get();
if (device.status !== 'online') console.log(`Offline since ${device.offlineSince}`);
for (const [name, check] of Object.entries(device.checks)) {
  if (check.state === 'needs_you') console.log(`${name}: ${check.detail}`);
}
console.log(`${device.today.newPeople} of ${device.today.newPeopleLimit} new people today`);

// BlueBot's own status, and who this key is.
const status = await client.status();
const me = await client.me();
console.log(status.sending, me.account.email, me.key?.scopes);

const settings = await client.settings.update({
  timeZone: 'America/Chicago',
  paceSeconds: 30,
  quietHours: { enabled: true, start: '20:00', end: '08:00' },
});
console.log(settings.warnings);

// Pause all sending for two hours, then resume.
await client.settings.update({ pausedUntil: new Date(Date.now() + 2 * 60 * 60 * 1000) });
await client.settings.update({ pausedUntil: null });

// The stop list.
await client.stops.add({ person: '+15555550144' });
for await (const stop of client.stops.list()) console.log(stop.handle, stop.source);
await client.stops.remove('+15555550144'); // the SDK encodes the + for the path

for await (const event of client.events.list({ type: ['message.received', 'message.failed'], since: '2026-11-12T00:00:00Z' })) {
  console.log(event.type, event.timestamp);
}
const event = await client.events.get('evt_1Hq2LxW9cVbN3mKpRtYs0a');

const webhook = await client.webhooks.create({
  url: 'https://example.com/bluebot/webhooks',
  events: ['message.received', 'message.failed'],
  description: 'Replies into the CRM',
});
// The secret is shown now and when you rotate it, never again. Store it.
console.log(webhook.secret);

await client.webhooks.test(webhook.id, { type: 'message.received' });
await client.webhooks.update(webhook.id, { paused: true });

// A new secret; the old one keeps signing beside it for 24 hours.
const { secret } = await client.webhooks.rotateSecret(webhook.id);

// Send again everything that gave up.
for await (const delivery of client.webhooks.deliveries.list(webhook.id, { state: 'gave_up' })) {
  await client.webhooks.deliveries.replay(webhook.id, delivery.id);
}

await client.webhooks.delete(webhook.id);

import BlueBot, { WebhookVerificationError } from '@usebluebot/sdk';

const client = new BlueBot();

export async function POST(request: Request) {
  const payload = await request.text();
  let event;
  try {
    event = client.webhooks.verify(payload, request.headers, process.env.BLUEBOT_WEBHOOK_SECRET);
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response('Bad signature', { status: 400 });
    throw error;
  }

  switch (event.type) {
    case 'message.received':
      // event.data is the message.
      console.log(`${event.data.from}: ${event.data.text ?? '(a picture)'}`);
      break;
    case 'message.failed':
      console.log(`${event.data.id} failed: ${event.data.failure?.reason}`);
      break;
  }
  return new Response(null, { status: 204 });
}

import express from 'express';
import BlueBot, { WebhookVerificationError } from '@usebluebot/sdk';

const app = express();
const client = new BlueBot();

// express.raw keeps the body as bytes; express.json() would break the signature.
app.post('/bluebot/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = client.webhooks.verify(req.body, req.headers, process.env.BLUEBOT_WEBHOOK_SECRET);
    if (event.type === 'contact.stopped') console.log(`${event.data.handle} stopped`);
    res.sendStatus(204);
  } catch (error) {
    if (error instanceof WebhookVerificationError) return res.sendStatus(400);
    throw error;
  }
});

await client.messages.send(
  { to: lead.phone, text: `Hi ${lead.firstName}, thanks for your interest.` },
  { idempotencyKey: `welcome-${lead.id}` },
);

const { data: message, response, requestId } = await client.messages
  .send({ to: '+15555550123', text: 'Hello again.' }, { idempotencyKey: 'hello-again-1' })
  .withResponse();

console.log(requestId, response.headers.get('Idempotent-Replayed')); // 'true' when BlueBot answered an earlier send
console.log(response.headers.get('RateLimit-Remaining'));

import BlueBot, { APIError, BadRequestError, RateLimitError, APIConnectionError } from '@usebluebot/sdk';

try {
  await client.messages.send({ to: '555', text: 'Hi' });
} catch (error) {
  if (error instanceof BadRequestError) {
    for (const { field, message } of error.details ?? []) console.log(`${field}: ${message}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Slow down; try again in ${error.retryAfter} seconds`);
  } else if (error instanceof APIError) {
    console.error(`${error.code}: ${error.message} ${error.hint} (${error.requestId})`);
  } else if (error instanceof APIConnectionError) {
    console.error('BlueBot could not be reached');
  } else {
    throw error;
  }
}

import type {
  Message, MessageState, Hold, HoldReason, FileObject, Chat, Contact, Stop, Lookup, Device, Status, Me, Settings,
  Webhook, WebhookWithSecret, WebhookDelivery, WebhookEvent, MessageReceivedEvent, ContactStoppedEvent,
  MessageSendParams, MessageListParams, Page, RequestOptions,
} from '@usebluebot/sdk';

import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({
  apiKey: 'bb_test_unused',
  maxRetries: 0,
  fetch: async (url, init) =>
    Response.json({ id: 'msg_1Hq2LxW9cVbN3mKpRtYs0a', object: 'message', state: 'queued' /* … */ }, { status: 201 }),
});