Get started

SDKs and tools

Libraries for Node.js, Python, PHP, Go, Java, C# and Ruby, the API as an OpenAPI spec, and a Postman collection.

SDKs#

Small libraries with no dependencies that cover the whole API: messages and batches, OTP codes, templates, sender IDs, webhooks, balance and prices, and checking webhook signatures. They retry what's safe to retry: a send carries an Idempotency-Key of its own, so a retry after a timeout never sends twice, and errors carry the API's error code.

Language	Install	Needs
Node.js	`npm install @siellabs/siel`	Node 18 or later
Python	`pip install siel`	Python 3.9 or later
PHP	`composer require siellabs/siel`	PHP 8.1 or later, with the curl and json extensions
Go	`go get siellabs.com/go/siel`	Go 1.22 or later
Java	`com.siellabs:siel:0.1.0`	Java 11 or later, from Maven Central
C#	`dotnet add package SielLabs.Siel`	.NET 8 or later, from our package source: C#
Ruby	`gem install siel`	Ruby 3.0 or later

Java#

Maven, pom.xml

<dependency>
  <groupId>com.siellabs</groupId>
  <artifactId>siel</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle, build.gradle.kts

implementation("com.siellabs:siel:0.1.0")

C##

The C# package comes from our own package source, not nuget.org. Add the source once, then install:

Install

dotnet nuget add source https://siellabs.com/nuget/index.json --name siellabs
dotnet add package SielLabs.Siel

In a project that also uses nuget.org, map SielLabs.* to our source in nuget.config, so no package of the same name from another source can stand in for it:

nuget.config

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="siellabs" value="https://siellabs.com/nuget/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="siellabs">
      <package pattern="SielLabs.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Send a message#

In Python the sender is from_, since from is a keyword.

Send a message

import { Siel, SielError } from "@siellabs/siel";

const siel = new Siel(process.env.SIEL_API_KEY, { baseUrl: "https://api.siellabs.com" });

try {
  const message = await siel.messages.send({
    to: "+447700900123",
    from: "YourBrand",
    body: "Your order #4821 has shipped",
    client_reference: "order-4821",
  });
  console.log(message.id, message.status); // "01a1…", "queued"
} catch (e) {
  if (e instanceof SielError) console.error(e.status, e.code, e.message);
  else throw e;
}

Without npm or PyPI#

The Node.js and Python packages also download from these docs:

Install

npm install https://docs.siellabs.com/sdk/siel-node-0.1.0.tgz
pip install https://docs.siellabs.com/sdk/siel-0.1.0-py3-none-any.whl

Checking webhooks#

Every library checks a webhook against your webhook secret, from the raw body and two headers:

Check a webhook

import express from "express";
import { verifyWebhook } from "@siellabs/siel";

const app = express();
// The raw body: verifying JSON parsed and written again fails.
app.post("/hooks/sms", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyWebhook(process.env.SIEL_WEBHOOK_SECRET, {
    timestamp: req.get("X-Smsgw-Timestamp"),
    signature: req.get("X-Smsgw-Signature"),
    body: req.body,
  });
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  console.log(event.message_id, event.status, event.client_reference);
  res.sendStatus(204);
});

OpenAPI spec#

The whole API as OpenAPI 3.1, kept in step with the gateway by its tests: every endpoint, its fields, errors and the permission a limited key needs for it (x-permission), and both webhook events. Generate a client in another language from it, or load it into your API tool.

File
openapi.yaml	YAML
openapi.json	The same, as JSON

Postman#

Every endpoint, a folder per section, with example bodies. In Postman: Import, pick the file, then set the collection's apiKey variable to one of your keys. baseUrl is set already.

File
siel.postman_collection.json	Postman collection v2.1