Go SDK

The Orbit Go SDK wraps the platform’s core API resources — messaging (SMS, WhatsApp, email), voice, contacts, campaigns, verify (OTP), and webhook signature verification — with typed methods. It requires Go 1.22+ and is safe for concurrent use across goroutines.

Pre-publish — source-only. This SDK is not yet mirrored to the public Go module repository — go get github.com/devotel/orbit-go returns 404 today. Until first publish, vendor the source from the monorepo (packages/sdk-go/) or call the REST API directly. See Go: core-scope, not full parity on the SDK index for exactly what is and isn’t wrapped, and the low-level client.Request(ctx, method, path, ...) escape hatch for uncovered routes (worked example below).

Installation

go get github.com/devotel/orbit-go/orbit@latest

Client initialization

The client reads the key straight from your environment — there is no from_env helper in Go; use os.Getenv:

package main

import (
    "context"
    "fmt"
    "os"

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

func main() {
    client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
    if err != nil {
        panic(err)
    }
    _ = client
    _ = context.Background()
    fmt.Println("ready")
}

Tune the transport with functional options:

client, err := orbit.NewClient(
    "dv_live_sk_...",
    orbit.WithBaseURL("https://api.orbit.devotel.io/api/v1"),
    orbit.WithHTTPClient(myCustomHTTP),    // e.g. instrumented http.Client
    orbit.WithMaxRetries(5),
    orbit.WithInitialBackoff(500 * time.Millisecond),
)

Quickstart: send your first SMS

A runnable end-to-end — the key comes from ORBIT_API_KEY, never from source. Copy it into main.go and run it with go run .:

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
if err != nil {
    log.Fatal(err)
}

msg, err := client.Messages().SendSMS(context.Background(), orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "Hello from Orbit!",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println("message id:", msg.Data.ID)       // msg_abc123
fmt.Println("status:", msg.Data.Status)       // "queued" — watch it reach "delivered"
fmt.Println("status URL:", "/api/v1/messages/"+msg.Data.ID)

Set ORBIT_API_KEY to a sandbox key prefixed dv_test_sk_ first — sandbox sends are simulated, free, and never reach a carrier. Swap in your live key (dv_live_sk_...) when you’re ready to send for real; the code does not change. The response shape above comes from the Messages API reference — its language tabs include this exact call.

Messaging

msg, err := client.Messages().SendSMS(context.Background(), orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "Hello from Orbit!",
})
if err != nil {
    panic(err)
}
fmt.Println("queued:", msg.Data.ID)

Sending is only the first half — fetch a message by id to read its delivery state (queued → sent → delivered), which is what a status poller or a support lookup does:

message, err := client.Messages().Get(context.Background(), "msg_abc123")
if err != nil {
    panic(err)
}
fmt.Println("status:", message.Data.Status)   // "delivered"

client.Messages() also exposes SendWhatsApp and SendEmail; Get (above) fetches a message by id.

Voice

A call’s full lifecycle fits in one flow: place it, poll its status, then hang up. Get returns the same call record Create did — read Status off it as it moves (queued → ringing → in-progress → completed):

// 1. Place an outbound call.
call, err := client.Voice().Create(context.Background(), orbit.CreateVoiceCallInput{
    To:     "+14155552671",
    From:   "+18005551234",  // optional — falls back to a tenant default
    Record: true,           // record, subject to two-party-consent rules
})
if err != nil {
    panic(err)
}
fmt.Println("call id:", call.Data.ID)         // call_abc123

// 2. Poll its status until it answers.
detail, err := client.Voice().Get(context.Background(), call.Data.ID)
if err != nil {
    panic(err)
}
fmt.Println("status:", detail.Data.Status)    // "in-progress"

// 3. Hang up.
if _, err := client.Voice().Hangup(context.Background(), call.Data.ID); err != nil {
    panic(err)
}

List past calls with direction/status filters and cursor pagination:

page, err := client.Voice().List(context.Background(), orbit.ListVoiceCallsParams{
    Direction: "outbound",
    Status:    "completed",
    Limit:     50,
})
if err != nil {
    panic(err)
}
for _, c := range page.Data {
    fmt.Println(c.ID, c.Status)
}

All outbound calls route through the Orbit API; the SDK never selects a carrier.

Second example: verify OTP

The send-and-check round trip is the most common first integration on the platform. Two calls — the key is still just ORBIT_API_KEY passed to orbit.NewClient:

// 1. Send an OTP (channel: sms | whatsapp | email).
sent, err := client.Verify().Send(context.Background(), "+14155552671", "sms")
if err != nil {
    log.Fatal(err)
}

// 2. Check the code the user typed in, against the verification id Send returned.
check, err := client.Verify().Check(context.Background(), sent.Data.ID, "482901")
if err != nil {
    log.Fatal(err)
}

fmt.Println("valid:", check.Data.Valid)      // true
fmt.Println("status:", check.Data.Status)    // "approved"

A wrongly-typed or expired code reports check.Data.Valid == false — it never errors for a bad guess (only for transport/auth failures), so branch on the flag. The Verify API reference covers the full contract, and Starter examples includes a complete OTP sign-in starter repo (orbit-otp-nextjs).

Verify (OTP)

sent, err := client.Verify().Send(context.Background(), "+14155552671", "sms")
if err != nil {
    panic(err)
}

check, err := client.Verify().Check(context.Background(), sent.Data.ID, "123456")
_ = check

Two follow-up operations round out the flow — Resend re-dispatches the code for a still-pending verification (same verification id), and GetDetail returns the full verification record (the same payload the dashboard verification drawer renders):

resend, err := client.Verify().Resend(context.Background(), sent.Data.ID)
if err != nil {
    panic(err)
}
fmt.Println("status:", resend.Data.Status)     // "pending" — new code on its way

detail, err := client.Verify().GetDetail(context.Background(), sent.Data.ID)
if err != nil {
    panic(err)
}
fmt.Println("status:", detail.Data["status"])  // "pending" | "approved" | …

Contacts

contact, err := client.Contacts().Create(context.Background(), orbit.ContactCreateInput{
    Phone:     "+14155552671",
    FirstName: "Ada",
})
if err != nil {
    panic(err)
}
fmt.Println("contact id:", contact.Data.ID)    // ctn_abc123

The rest of the contact lifecycle reads off the id Create returned — fetch it, patch it (pointer fields are omitted from the request when nil), and delete it:

contactID := contact.Data.ID

// Fetch one contact.
detail, err := client.Contacts().Get(context.Background(), contactID)
if err != nil {
    panic(err)
}
fmt.Println("phone:", detail.Data.Phone)

// Partial update — only non-nil fields are sent.
firstName := "Grace"
updated, err := client.Contacts().Update(context.Background(), contactID, orbit.ContactUpdateInput{
    FirstName: &firstName,
})
if err != nil {
    panic(err)
}
fmt.Println("first name:", updated.Data.FirstName)    // "Grace"

// Page through the directory with optional search.
page, err := client.Contacts().List(context.Background(), orbit.ListContactsParams{
    Limit:  50,
    Search: "grace",
})
if err != nil {
    panic(err)
}
for _, c := range page.Data {
    fmt.Println(c.ID, c.DisplayName)
}

// Permanently delete.
if err := client.Contacts().Delete(context.Background(), contactID); err != nil {
    panic(err)
}

Campaigns

campaign, err := client.Campaigns().Create(context.Background(), orbit.CampaignCreateInput{
    Name:    "Launch",
    Channel: "sms",
})
if err != nil {
    panic(err)
}

// Trigger the send, then re-fetch to watch its status progress.
if _, err = client.Campaigns().Send(context.Background(), campaign.Data.ID); err != nil {
    panic(err)
}
state, err := client.Campaigns().Get(context.Background(), campaign.Data.ID)
if err != nil {
    panic(err)
}
fmt.Println("status:", state.Data.Status)      // "sending" | "completed" | …

Rename before the send fires, or list every campaign in the organization:

name := "Launch — Q4"
updated, err := client.Campaigns().Update(context.Background(), campaign.Data.ID, orbit.CampaignUpdateInput{
    Name: &name,
})
if err != nil {
    panic(err)
}
fmt.Println("name:", updated.Data.Name)

page, err := client.Campaigns().List(context.Background())
if err != nil {
    panic(err)
}
for _, c := range page.Data {
    fmt.Println(c.ID, c.Name, c.Status)
}

client.Campaigns() also exposes Delete — client.Campaigns().Delete(ctx, id) permanently removes a campaign by id (returns no body).

Paginate a list

List endpoints are cursor-paginated — read meta.pagination.cursor and meta.pagination.has_more off each response and pass the cursor back as a query parameter until has_more is false. Page through SMS messages with the escape hatch:

query := url.Values{"channel": {"sms"}, "limit": {"100"}}
total := 0

for {
    var page map[string]any
    if err := client.Request(context.Background(), "GET", "/messages", query, nil, &page, ""); err != nil {
        log.Fatal(err)
    }

    data := page["data"].([]any)
    total += len(data)

    pagination := page["meta"].(map[string]any)["pagination"].(map[string]any)
    if !pagination["has_more"].(bool) {
        break
    }
    query.Set("cursor", pagination["cursor"].(string))
}

fmt.Printf("Fetched %d messages\n", total)

The full pagination model (cursor vs. offset endpoints, page-size caps, and why cursors are not bookmarkable) is in the Pagination guide.

Error handling

All Orbit-originated errors are *orbit.Error. Inspect them with the helper predicates:

Predicate	Matches
`orbit.IsAuthentication(err)`	401/403 — rotate the API key
`orbit.IsRateLimit(err)`	429 — back off; `err.(*orbit.Error).RetryAfter` is set when the API provides it
`orbit.IsServerError(err)`	5xx — Orbit-side failure, also persistent network errors (`Kind == orbit.KindServer`, `Code == "network_error"`)

resp, err := client.Messages().SendSMS(ctx, in)
switch {
case orbit.IsRateLimit(err):
    // back off; err.(*orbit.Error).RetryAfter is set when the API provides it
case orbit.IsAuthentication(err):
    // rotate the API key
case orbit.IsServerError(err):
    // 5xx — Orbit-side failure
case err != nil:
    // 4xx — caller error
}
_ = resp

Every non-GET request automatically carries an Idempotency-Key header (UUID v4); override it per call via orbit.SendSMSInput{ ..., IdempotencyKey: "job-7a3b9d-attempt-1" } when retrying from your own queue.

Covered route missing? Use the escape hatch

The typed resources wrap 8 core resources; the rest of the API — contact segments, event sinks, frequency caps, and everything else listed as out of scope on the SDK index — is reachable through client.Request(ctx, method, path, ...). It unmarshals the raw JSON body into whatever out you pass (a map[string]any when you have no typed struct). Fetch a segment by id:

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

The escape hatch carries the same auth, retry, and error model as the typed resources — treat it as a first-class client, not a fallback http.Client.

Webhook signature verification

event, err := orbit.VerifyWebhook(
    requestBody,
    request.Header.Get("X-Orbit-Signature"),
    os.Getenv("ORBIT_WEBHOOK_SECRET"),
    0,            // tolerance — 0 = use default 5 minutes
    time.Time{},  // now — zero value = time.Now()
)
if err != nil {
    // Forgery attempt — drop, do NOT 200.
    w.WriteHeader(400)
    return
}
// event is a map[string]any — type-assert event["type"], etc.

Runnable examples

The package’s examples/ directory holds self-contained, runnable end-to-end files (each takes ORBIT_API_KEY / ORBIT_WEBHOOK_SECRET from the environment): first SMS send, cursor pagination over GET /messages, the OTP send+check round trip, a programmable outbound call with an answer_url callback, and webhook signature verification against a signed test payload. Run any of them with go run ./examples/<name>.go. The same shapes are also walked task-by-task in the API recipes cookbook.

SDKs

Go SDK: Orbit quickstart for Go

Go SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Second example: verify OTP

Verify (OTP)

Contacts

Campaigns

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification

Runnable examples

​Go SDK

​Installation

​Client initialization

​Quickstart: send your first SMS

​Messaging

​Voice

​Second example: verify OTP

​Verify (OTP)

​Contacts

​Campaigns

​Paginate a list

​Error handling

​Covered route missing? Use the escape hatch

​Webhook signature verification

​Runnable examples

Go SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Second example: verify OTP

Verify (OTP)

Contacts

Campaigns

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification

Runnable examples