TextConvo SDK for Go

Official Go SDK for the TextConvo API.

Website  ·  Developer Docs  ·  API Reference  ·  Support

---

Not released yet. This repository is the public home of the official Go SDK. It holds the intended surface and the roadmap; there is no importable package yet. That is deliberate.

Use today: textconvo-api-examples has a dependency-free Go client with context timeouts, retries, idempotency, and HMAC signing. Copy it into your project.

Watch this repository to hear about the first release.

Planned installation

go get github.com/textconvo/textconvo-go-sdk

Planned usage

A design sketch, not a contract, until v1.

package main

import (
	"context"
	"errors"
	"log"
	"os"
	"time"

	"github.com/textconvo/textconvo-go-sdk/textconvo"
)

func main() {
	client, err := textconvo.NewClient(
		textconvo.WithAPIKey(os.Getenv("TEXTCONVO_API_KEY")),
		textconvo.WithSourceKey(os.Getenv("TEXTCONVO_SOURCE_KEY")),
		textconvo.WithHMACSecret(os.Getenv("TEXTCONVO_HMAC_SECRET")), // optional
		textconvo.WithTimeout(10*time.Second),
	)
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	// Idempotency, retries, and backoff handled for you.
	accepted, err := client.Leads.Ingest(ctx, textconvo.Lead{
		Phone:     "+15035551234",
		FirstName: "Jane",
		LastName:  "Doe",
		CustomFields: map[string]any{"roof_age_years": "12"},
	})

	var rateLimited *textconvo.RateLimitError
	switch {
	case err == nil:
		log.Printf("queued: %s duplicate=%v", accepted.IngestionRequestID, accepted.Duplicate)
	case errors.As(err, &rateLimited):
		log.Printf("rate limited, retry after %s", rateLimited.RetryAfter)
	default:
		log.Fatalf("ingest failed: %v", err)
	}
}

// Webhook verification as standard middleware
http.Handle("/webhooks/textconvo", textconvo.VerifyWebhook(
	os.Getenv("TEXTCONVO_WEBHOOK_SECRET"),
	http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		event := textconvo.EventFromContext(r.Context())
		w.WriteHeader(http.StatusOK) // answer fast
		go process(event)            // work later
	}),
))

Planned structure

textconvo-go-sdk/
├─ textconvo/
│  ├─ client.go           # NewClient, functional options, transport
│  ├─ errors.go           # typed errors, retryable vs terminal
│  ├─ leads.go            # LeadsService.Ingest
│  ├─ retry.go            # backoff with jitter
│  └─ webhooks.go         # VerifyWebhook middleware, event types
├─ internal/
├─ examples/
└─ go.mod

Design commitments

Standard library only. No transitive dependencies. Go has everything this SDK needs.

Contexts everywhere. Every call takes a context.Context and honours cancellation.

Errors that work with errors.As. Typed errors rather than sentinel string matching.

Safe by default. Idempotency keys generated automatically, retries only for 429 and 5xx, exponential backoff with jitter, hmac.Equal for signatures.

Functional options. Additive configuration that never breaks compilation.

Go 1.21+ and semantic import versioning. v0 while the surface moves, v1 when it stops.

Roadmap

Milestone	Contents	Status
v0.1.0 — Alpha	Client, options, Leads.Ingest, typed errors, retries, HMAC signing	Planned
v0.2.0 — Webhooks	VerifyWebhook middleware and typed event structs	Planned
v0.3.0 — Observability	slog hooks, request tracing, custom transports	Planned
v0.4.0 — Beta	Full test suite, godoc examples, chi and gin samples	Planned
v1.0.0 — GA	Stable API, compatibility promise	Planned
Post-v1	Channel-send operations, contact retrieval, message status as those endpoints ship	Planned

See coverage for what the API supports today.

See it live

Submit the contact form and you get a direct line to Ria, the TextConvo AI orchestrator — call her for a live voice demo, or text her and watch the SMS AI reply in real time. A human follows up within one business day, and the same form is how API credentials, a source key, and a webhook secret are issued.

Handed a TextConvo QR code at an event or in a demo? Scanning it opens the same conversation. The form is simply the path that works for everyone.

Feedback wanted, before the code exists

Functional options or a config struct? any or generics for custom fields? Middleware or a plain verify function for webhooks? Open an issue — opinions now are worth more than pull requests later.

Contributing

Design feedback and documentation fixes welcome; implementation pull requests are on hold until the alpha surface is agreed. See CONTRIBUTING.md.

Security

SECURITY.md — never open a public issue for a vulnerability.

License

MIT © TextConvo