The machine-readable contract for the TextConvo API.
Website · Developer Docs · API Reference · Support
This repository contains one file that matters: openapi.yaml. Point a generator, a linter, or a documentation viewer at it and you have a typed client in minutes.
It describes the public surface only — lead ingestion and the webhook events TextConvo sends you. There is no backend implementation here, and there never will be.
Prose documentation, CRM guides, and worked examples live at textconvo.ai/docs. This specification is the contract; the website is the manual.
| Area | Detail |
|---|---|
| Server | https://api.textconvo.ai |
| Security | X-API-Key and X-Source-Key header schemes, plus optional HMAC request signing headers |
| Operation | POST /functions/v1/ingest-lead — ingest a lead and queue a journey |
| Idempotency | X-Request-Id documented as the idempotency key, with a duplicate response example |
| Schemas | Lead, IngestAccepted, Error, RateLimitError, and four webhook event payloads |
| Responses | 202, 400, 401, 403, 429 (with retry guidance), 500 |
| Webhooks | lead.accepted, lead.delivered, lead.reply, lead.opt_out as OpenAPI 3.1 webhooks |
| Examples | Minimal, typical, and CRM-integrated request bodies |
The full event catalogue, signature verification, and sample receivers live in textconvo-webhooks.
npx @redocly/cli lint openapi.yaml
npx @stoplight/spectral-cli lint openapi.yamlnpx @redocly/cli preview-docs openapi.yaml # local reference docs
npx @scalar/cli document serve openapi.yaml # alternative viewerOr paste it into editor.swagger.io.
Until the official SDKs reach general availability, generating from this specification is the fastest route to a typed client.
# TypeScript types
npx openapi-typescript openapi.yaml -o textconvo.d.ts
# TypeScript fetch client
npx @hey-api/openapi-ts -i openapi.yaml -o src/textconvo
# Python
openapi-python-client generate --path openapi.yaml
# Go, Java, C#, PHP and more
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g go -o ./clientGenerated code is a starting point, not a finished integration. Add retries, timeouts, and idempotency handling deliberately — see textconvo-api-examples for how we do it.
The info.version field uses a date-based release identifier, and every change is recorded in CHANGELOG.md. Additive changes ship without notice; anything breaking is announced first on the blog and flagged in the changelog.
Pin a commit or tag if you generate clients in CI.
If the specification and the API disagree, the API is right and we have a bug. Open an issue with the request, the response, and the field in question — with secrets redacted.
| Repository | Purpose |
|---|---|
| textconvo-api-examples | Working examples in nine languages |
| textconvo-postman | Click-through collection generated from this contract |
| textconvo-webhooks | Payloads, verification, and receivers |
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.
Specification fixes are very welcome: a wrong type, a missing example, a description that reads badly. See CONTRIBUTING.md.
Report vulnerabilities privately — SECURITY.md.
MIT © TextConvo