Getting started

SDKs & libraries

Official Node SDK + ready-to-paste snippets for every other language. The REST API works equally well with whatever HTTP client you prefer.

Official Node.js SDK

Maintained in this repo. Zero runtime dependencies. Full TypeScript types.

npm install blueapi

Hello world:

hello.js

import { BlueReplies } from 'blueapi';

const client = new BlueReplies({ apiKey: process.env.BLUEREPLIES_KEY });

const msg = await client.messages.send({
  to: '+15551234567',
  body: 'Hello!',
});

console.log(msg.id, msg.status);

Available namespaces (1:1 with the REST resources):

client.messages           // send, list, get, edit, unsend, react, typing
client.conversations      // list, get, archive
client.calls              // initiate, list, get, end, voicemail
client.contacts           // list, get, create, bulk, search, bulk-tag, export
client.groups             // create, list, get, addMember, removeMember, leave
client.webhooks           // create, list, update, delete, replay
client.lookup             // lookup, bulk
client.media              // upload, get
client.optOuts            // list, create, bulk, delete
client.lines              // list, get

Webhook signature verification:

webhook.js

import { verifyWebhook } from 'blueapi';

app.post('/webhooks/bluereplies', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyWebhook(req.body, req.headers['x-bluereplies-signature'], process.env.WEBHOOK_SECRET);
  if (!ok) return res.status(400).end();

  const evt = JSON.parse(req.body.toString('utf8'));
  // ... handle evt.event + evt.data ...
  res.json({ ok: true });
});

Other languages

No official SDK exists for Python, Ruby, Go, PHP, or Elixir yet. Until then, the REST API works directly. Below are minimal HTTP clients for each.

bluereplies.py

import os
import httpx

class BlueReplies:
    def __init__(self, api_key: str | None = None):
        self.client = httpx.Client(
            base_url='https://api.bluereplies.com/v1',
            headers={'x-api-key': api_key or os.environ['BLUEREPLIES_KEY']},
            timeout=30,
        )

    def send_message(self, **kwargs):
        r = self.client.post('/messages', json=kwargs)
        r.raise_for_status()
        return r.json()

    def create_webhook(self, url: str, events: list[str]):
        r = self.client.post('/webhooks', json={'url': url, 'events': events})
        r.raise_for_status()
        return r.json()

# Usage
br = BlueReplies()
msg = br.send_message(to='+15551234567', body='Hello!')
print(msg)

Want an official SDK in your language?

Tell us at [email protected] — we prioritize based on demand. Community SDKs welcome too.