​

SDKs

​

Map the SDK surface

​

Quick start: same call in six languages

curl "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: me } = await orbit.me.get();
console.log(me);

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

me = client.request("GET", "/me")
print(me["data"])

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client := orbit.NewClientFromAPIKey(os.Getenv("ORBIT_API_KEY"))

	var me map[string]any
	if err := client.Request(context.Background(), "GET", "/me", nil, nil, &me, ""); err != nil {
		panic(err)
	}
	fmt.Println(me["data"])
}

require 'orbit_sdk'

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

me = client.request('GET', '/me')
puts me['data']

<?php
require __DIR__.'/vendor/autoload.php';

use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  // reads ORBIT_API_KEY

$me = $client->request('GET', '/me');
print_r($me['data']);

​

Start with…

• Node if you need the full feature surface — it is the only feature-complete SDK today (/sdks/node).
• Web if you are embedding chat or an inbox widget in a browser (/sdks/web).
• Python if you want a published, core-scope server SDK on PyPI (/sdks/python).
• Go / .NET / Java / PHP / Ruby if you are on one of those stacks and the 8 core resources (messaging, voice, contacts, campaigns, verify, webhooks, numbers, lookup) cover your needs — vendor the source until each lands on its registry.
• Swift / Android / Flutter / React Native if you are building a native client app that shows inbox chat, owned messages, or video rooms — never for backend calls that need a secret key.

​

Mobile parity

​

Published SDKs

​

In workspace source (unpublished)

​

Go: core-scope, not full parity

​

.NET: core-scope, not full parity

​

Java: core-scope, not full parity

​

Python: core-scope, not full parity

​

PHP: core-scope, not full parity

​

Ruby: core-scope, not full parity

​

Client / mobile SDKs (different scope, by design)

​

Client / mobile SDK sources

• Source: packages/sdk-web/ — Web (browser, TypeScript, npm). README documents the deliberate scope as a “Scope — this is a client SDK, not a full API client” heading.
• Source: packages/sdk-swift/ — iOS (Swift, SPM). README documents the deliberate scope as a “Scope — this is a client SDK, not a full API client” heading.
• Source: packages/sdk-android/ — Android (Kotlin/Gradle). Same deliberate scope heading in its README.
• Source: packages/sdk-flutter/ — Flutter (Dart, pub). Same deliberate scope heading in its README.
• Source: packages/sdk-react-native/ — React Native (TypeScript). Same deliberate scope heading in its README.

​

Registry coordinates

​

Vendoring Java and C#

import io.devotel.orbit.OrbitClient;

import java.util.Map;

OrbitClient client = OrbitClient.fromEnv();  // reads ORBIT_API_KEY

// Any route the typed clients don't wrap — inventory owned numbers.
Map<String, Object> numbers = client.request("GET", "/api/v1/numbers", null, null, null);
Map<?, ?> first = (Map<?, ?>) ((java.util.List<?>) numbers.get("data")).get(0);
System.out.println("first number: " + first.get("phone_number"));

// First SMS via the typed client, then poll its delivery status.
Map<String, Object> sent = client.messages.sendSms("+14155552671", "Hello from Orbit!");
String messageId = (String) ((Map<?, ?>) sent.get("data")).get("id");

Map<String, Object> state = client.messages.get(messageId);
Map<?, ?> stateData = (Map<?, ?>) state.get("data");
System.out.println("status: " + stateData.get("status"));   // "queued"

using Orbit.Sdk;

var client = OrbitClient.FromEnv();  // reads ORBIT_API_KEY

// Any route the typed clients don't wrap — inventory owned numbers.
var numbers = await client.RequestAsync("GET", "/api/v1/numbers");
var first = numbers.GetProperty("data")[0];
Console.WriteLine($"first number: {first.GetProperty("phone_number").GetString()}");

// First SMS via the typed client, then poll its delivery status.
var sent = await client.Messages.SendSmsAsync("+14155552671", "Hello from Orbit!");
var messageId = sent.GetProperty("data").GetProperty("id").GetString();

var state = await client.Messages.GetAsync(messageId!);
Console.WriteLine($"status: {state.GetProperty("data").GetProperty("status").GetString()}");  // "queued"

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <!-- Vendor the SDK sources until first NuGet publish. -->
    <Compile Include="vendor/orbit-sdk-csharp/src/**/*.cs" />
  </ItemGroup>

</Project>

​

Common patterns across languages

​

Authentication

​

Webhook verification

• Node (GA): Orbit.webhooks.constructEvent(body, signature, secret)
• Python (core-scope, published): verify_webhook(payload=..., signature=..., secret=...)
• Go (core-scope, unpublished): orbit.VerifyWebhook(body, header, secret, 0, time.Time{})
• PHP (core-scope, unpublished): Webhooks::verify(payload: ..., signature: ..., secret: ...)
• Ruby (core-scope, unpublished): OrbitSdk::Webhooks.verify(payload:, signature:, secret:)
• Java (core-scope, unpublished): Webhooks.verify(body, signature, secret)
• C# (core-scope, unpublished): Webhooks.Verify(payload, signature, secret)

​

Worked example

import { Orbit, OrbitRateLimitError, OrbitValidationError } from '@devotel-orbit/node';

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const message = await orbit.messages.send({
  channel: 'sms',
  to: '+14155552671',
  body: 'Hello from Orbit!',
});

const event = Orbit.webhooks.constructEvent(rawBody, signatureHeader, webhookSecret);

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

msg = client.messages.send_sms(to="+14155552671", body="Hello from Orbit!")

from orbit_sdk import verify_webhook

event = verify_webhook(payload=payload_bytes, signature=header, secret=webhook_secret)

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))

msg, err := client.Messages().SendSMS(ctx, orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "Hello from Orbit!",
})

event, err := orbit.VerifyWebhook(body, signatureHeader, webhookSecret, 0, time.Time{})

import { OrbitRateLimitError, OrbitValidationError } from '@devotel-orbit/node';

try {
  await orbit.messages.send({ channel: 'sms', to, body });
} catch (e) {
  if (e instanceof OrbitRateLimitError) {
    // 429 — respect the Retry-After hint (surfaced in `details`) before retrying.
  } else if (e instanceof OrbitValidationError) {
    // 400/422 — the request body failed validation; fix it, don't retry.
  } else {
    throw e;
  }
}

​

Error hierarchy

• OrbitApiError (base) → catch this to handle any non-2xx API response. Carries code, statusCode (aliased as status), details, docsUrl, and requestId, plus isRateLimited / isClientError / isServerError getters.
• OrbitAuthError — 401/403 (bad API key or missing scope).
• OrbitNotFoundError — 404 (resource doesn’t exist or isn’t visible).
• OrbitRateLimitError — 429. Check the Retry-After header (also surfaced in details) to decide when to retry.
• OrbitValidationError — 400/422 (request body failed server-side validation).
• OrbitServerError — 5xx after retries exhausted, or persistent network failure.
• OrbitWebhookSignatureError — webhook verification failed. Carries a code of 'bad_signature' | 'expired' | 'malformed'. Extends Error, not OrbitApiError, so a broad catch (OrbitApiError) block can’t accidentally swallow + retry forgeries.

​

Operator: publishing checklist