TextConvo SDK for Java

Official Java SDK for the TextConvo API.

Website  ·  Developer Docs  ·  API Reference  ·  Support

---

Not released yet. This repository is the public home of the official Java SDK. It holds the intended surface and the roadmap; nothing is published to Maven Central yet. That is deliberate.

Use today: textconvo-api-examples has a dependency-free java.net.http client with retries, idempotency, and HMAC signing. Or generate one from textconvo-openapi.

Watch this repository to hear about the first release.

Planned installation

<dependency>
  <groupId>ai.textconvo</groupId>
  <artifactId>textconvo-java</artifactId>
  <version>0.1.0</version>
</dependency>

implementation("ai.textconvo:textconvo-java:0.1.0")

Planned usage

A design sketch, not a contract, until 1.0.

var client = TextConvoClient.builder()
    .apiKey(System.getenv("TEXTCONVO_API_KEY"))
    .sourceKey(System.getenv("TEXTCONVO_SOURCE_KEY"))
    .hmacSecret(System.getenv("TEXTCONVO_HMAC_SECRET"))  // optional
    .timeout(Duration.ofSeconds(10))
    .build();

// Idempotency, retries, and backoff handled for you.
try {
    var accepted = client.leads().ingest(Lead.builder()
        .phone("+15035551234")
        .firstName("Jane")
        .lastName("Doe")
        .customField("roof_age_years", "12")
        .build());

    log.info("queued {} duplicate={}", accepted.ingestionRequestId(), accepted.duplicate());
} catch (RateLimitException e) {
    log.warn("rate limited, retry after {}", e.retryAfter());
} catch (TextConvoException e) {
    log.error("[{} {}] {}", e.status(), e.code(), e.getMessage());
}

// Webhook verification, framework agnostic
var verifier = new WebhookVerifier(System.getenv("TEXTCONVO_WEBHOOK_SECRET"));

@PostMapping("/webhooks/textconvo")
public ResponseEntity<Void> receive(@RequestBody byte[] rawBody, @RequestHeader HttpHeaders headers) {
    var event = verifier.verify(rawBody, headers.getFirst("X-TextConvo-Signature"),
                                         headers.getFirst("X-TextConvo-Timestamp"));
    queue.send(event);                       // work later
    return ResponseEntity.ok().build();      // answer fast
}

Planned structure

textconvo-java-sdk/
├─ src/main/java/ai/textconvo/
│  ├─ TextConvoClient.java     # builder, transport, retries
│  ├─ model/                   # Lead, IngestAccepted, events (records)
│  ├─ resource/LeadsResource.java
│  ├─ error/                   # exception hierarchy
│  └─ webhook/WebhookVerifier.java
├─ src/test/java/
├─ examples/
└─ pom.xml

Design commitments

Java 17+, records, no reflection tricks. Immutable models and builders that read cleanly.

java.net.http, no HTTP framework. Minimal dependency footprint; Jackson only for JSON.

Checked where it matters. TextConvoException with RateLimitException, AuthenticationException, and ValidationException beneath it, so you can branch precisely.

Safe by default. Automatic idempotency keys, retries only for 429 and 5xx, exponential backoff with jitter, constant-time signature comparison.

Thread-safe client. Build once, share everywhere.

Roadmap

Milestone	Contents	Status
0.1.0 — Alpha	Client builder, auth, leads().ingest(), exceptions, retries, HMAC signing	Planned
0.2.0 — Webhooks	WebhookVerifier, typed events, Spring and Jakarta samples	Planned
0.3.0 — Async	CompletableFuture variants of every call	Planned
0.4.0 — Beta	Test suite, javadoc, Spring Boot starter	Planned
1.0.0 — GA	Stable surface, published to Maven Central	Planned
Post-1.0	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

Do you want a Spring Boot starter on day one? Jackson, or a pluggable JSON layer? Checked or unchecked exceptions? Open an issue.

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