📘 Chat Exchange Developer Docs

Version: 0.1 • Status: Draft for Public Review • Last updated: 2025-10-06

🚀 Quick Start

Choose your intents
Decide which chat purposes you want to expose —
support, sales, info, hr, or your own x-* custom intents.

Create DNS TXT records
Publish CX Entries under _cx.yourdomain.com (or subdomain for regional/business-unit scopes).

_cx.yourdomain.com. IN TXT "v=CX1; app=whatsapp; id=+14155550101; intent=support"
_cx.yourdomain.com. IN TXT "v=CX1; app=rcs; id=rcs:yourbrand; intent=sales"

Verify ownership
Visit https://chatexchange.net/verify to confirm DNS control.
You'll receive an attestation signature recorded in the public trust log.

(Optional) Publish a JSON file
If you prefer HTTP discovery, you may host a structured index:

{
  "version": "CX1",
  "entries": [
    { "app": "whatsapp", "id": "+14155550101", "intent": "support" },
    { "app": "rcs", "id": "rcs:yourbrand", "intent": "sales" }
  ]
}

Save as /.well-known/cx.json.

🧩 Client Behavior

Resolver Lookup
- Fetch TXT records from _cx.<domain>
- Optionally fetch /.well-known/cx.json
- Merge entries; prefer JSON fields when conflicts occur
Verification
- Prefer verified/attested results (see RFC-02: Verification & Attestation)
- Reject expired or unverified responses when possible
Open Chat
- Use deep links to open native apps
- Fallback to a web redirect if unsupported on device

App	Deep-Link Format
WhatsApp	`https://wa.me/<E164>`
RCS	`rcs:<handle>`
Apple Business Chat	`abm:<business-id>`
Telegram	`https://t.me/<handle>`

⚙️ API Reference (Preview)

Developers may use the public Resolver API to query verified CX Entries:

GET https://api.chatexchange.net/resolve?domain=example.com

Response

{
  "verified": true,
  "entries": [
    {
      "app": "whatsapp",
      "id": "+14155550101",
      "intent": "support",
      "meta": { "locale": "en-IN" }
    }
  ]
}

Rate Limits: 1000 requests / day (free tier)
Authentication: None required for public data.
Schema: /.well-known/openapi.json

🧠 Example Workflows

For Businesses
Add a single TXT record once and be discoverable by all chat clients and AI systems.

For Developers
Use the resolver to display verified chat buttons or to build CRM integrations.

For AI Platforms
Safely locate real business endpoints before sending a message.

🔐 Verification Overview

Ownership proven via DNS control
Attestations cryptographically signed
Transparency log ensures immutability
Clients verify signature before accepting entry

Learn more in RFC-02: Verification & Attestation (Draft).

❓ FAQ

Q: Is CX Entry a replacement for MX?
A: No. CX handles chat endpoint discovery and intents; MX handles mail routing.

Q: Can I use multiple chat apps per domain?
A: Yes. Add one record per app/intent pair.

Q: How do I handle multiple regions or brands?
A: Use subdomains — e.g., _cx.apac.example.com, _cx.shop.example.com.

Q: Is JSON required?
A: No. TXT records are canonical. JSON is optional for machine-readability.

Q: What about privacy?
A: CX only exposes business endpoints, never personal identifiers. Use short TTLs if needed.

🧱 Tools & SDKs (Coming Soon)

cx-cli — command-line tool to create & validate records
@chatexchange/sdk — Node.js package for resolvers
cx-python — lightweight Python client
resolver API — public REST endpoint (preview live)

💬 Contributing

Feedback, issues, or pull requests welcome at
👉 github.com/himanshu-sukhwani/chatexchange

Contact the editors at discuss@chatexchange.net