TextConvo SDK for Python

Official Python SDK for the TextConvo API.

Website  ·  Developer Docs  ·  API Reference  ·  Support

---

Not released yet. This repository is the public home of the official Python SDK. It currently holds the intended surface and the roadmap. There is no package on PyPI and no implementation in src/ — deliberately, not by omission.

Use today: textconvo-api-examples has a production-shaped Python client with retries, idempotency, and HMAC signing. Or generate one from textconvo-openapi.

Watch this repository to hear about the first release.

Planned installation

pip install textconvo

Planned usage

A design sketch, not a contract, until 1.0.

from textconvo import TextConvo

client = TextConvo(
    api_key=os.environ["TEXTCONVO_API_KEY"],
    source_key=os.environ["TEXTCONVO_SOURCE_KEY"],
    hmac_secret=os.environ.get("TEXTCONVO_HMAC_SECRET"),  # optional
)

# Idempotency, retries, and backoff handled for you.
accepted = client.leads.ingest(
    phone="+15035551234",
    first_name="Jane",
    last_name="Doe",
    email="jane.doe@example.com",
    custom_fields={"roof_age_years": "12"},
)

print(accepted.ingestion_request_id, accepted.duplicate)

# Async, same surface
from textconvo import AsyncTextConvo

async with AsyncTextConvo(api_key=..., source_key=...) as client:
    await client.leads.ingest(phone="+15035551234")

# Webhook verification, framework agnostic
from textconvo.webhooks import verify_webhook, InvalidSignature

@app.post("/webhooks/textconvo")
async def receive(request):
    try:
        event = verify_webhook(
            raw_body=await request.body(),
            signature=request.headers.get("X-TextConvo-Signature"),
            timestamp=request.headers.get("X-TextConvo-Timestamp"),
            secret=os.environ["TEXTCONVO_WEBHOOK_SECRET"],
        )
    except InvalidSignature:
        return Response(status_code=401)

    queue.put(event)      # answer fast, work later
    return Response(status_code=200)

Planned structure

textconvo-python-sdk/
├─ src/textconvo/
│  ├─ __init__.py         # TextConvo, AsyncTextConvo
│  ├─ _client.py          # transport: auth, timeouts, retries, backoff
│  ├─ _errors.py          # exception hierarchy, retryable vs terminal
│  ├─ resources/
│  │  └─ leads.py         # client.leads.ingest()
│  ├─ webhooks/
│  │  ├─ verify.py        # signature and timestamp verification
│  │  └─ events.py        # typed event models
│  └─ types.py            # generated from textconvo-openapi
├─ tests/
├─ examples/
└─ pyproject.toml

Design commitments

Typed and inspectable. Full type hints, py.typed, and models that print usefully in a REPL.

Sync and async, one surface. TextConvo and AsyncTextConvo with identical methods.

Minimal dependencies. httpx for transport and nothing else that is not required.

Safe by default. Automatic idempotency keys, retries only for 429 and 5xx, exponential backoff with jitter, hmac.compare_digest for signatures, secrets from the environment.

Exceptions you can catch precisely. TextConvoError at the root, with RateLimitError, AuthenticationError, and ValidationError beneath it.

Python 3.9+ and semantic versioning. 0.x while the surface moves, 1.0 when it stops.

Roadmap

Milestone	Contents	Status
0.1.0 — Alpha	Sync client, auth, leads.ingest, exception hierarchy, retries, HMAC signing	Planned
0.2.0 — Async	AsyncTextConvo with the same surface	Planned
0.3.0 — Webhooks	Verification helper, typed events, Flask, FastAPI, and Django adapters	Planned
0.4.0 — Beta	Test suite, docs, examples, Pydantic-optional models	Planned
1.0.0 — GA	Stable surface, published on PyPI	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

This is the cheapest moment to change the design. Do the method names read well? Do you want Pydantic models or plain dataclasses? Which web framework adapter first? Open an issue.

Contributing

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

Security

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

License

MIT © TextConvo