TelDev

Endpoints

TelDev /v1 is the live API on teldev.bot for AI voice calls in the browser. Telnyx is the carrier end to end; Twilio-shaped paths are a REST alias only, not a second carrier.

Base host: https://teldev.bot (local: http://127.0.0.1:3000).

Auth: Authorization: Bearer nl_test_… or nl_live_….

GET /health is open.

| Method | Path | Notes |

| --- | --- | --- |

| GET | /health | { "ok": true } |

| POST | /v1/numbers | Provision. Body: { area_code?, campaign? } |

| POST | /v1/calls | { action?, from, to, agent?, campaign?, call?, at? } — to may be { device: "dev_…" } or "device". Trial/Free/Personal e164 is 422 device_only_plan. Optional at is ISO-8601, stored as given (no server rounding), and fires to a Device on that Account (timezone default America/Denver; past or unparseable is 4xx). action is create (default), answer, hangup, mute, unmute, hold, unhold |

| POST | /v1/devices | Register a browser Device (dev_). Returns a session handle so TelDev can ring it. |

| GET | /v1/devices | Bearer dev_. Reachable Device plus incoming call (name, not e164). |

| POST | /v1/trial/otp | { phone } — SMS OTP (mock code 000000 when no Telnyx key) |

| POST | /v1/trial/verify | { phone, code } → trl_ token + remaining seconds |

| GET | /v1/trial | Bearer trl_. Remaining seconds and plan. Minutes are server-side. |

| GET | /v1/plans | Personal $20 (175 included min) / Build $49 / Ship $199 / Scale $599. checkout is null. |

| POST | /v1/billing/subscribe | { plan } mock attach (personal / build / ship / scale). After the 10, TelDev attaches Personal. |

| POST | /v1/webrtc/token | Telnyx WebRTC client token. mock: true on test / no API key |

| GET | /v1/sessions/:id/events | SSE stub of session events (stream_url is events, not audio) |

| POST | /v1/messages | { from, to, body, agent?, campaign? } |

| GET | /v1/calls/:id | |

| GET | /v1/messages/:id | |

| GET | /v1/sessions/:id | |

| GET | /v1/events?after= | Events after evt_… |

| GET | /v1/usage | Usage totals |

| GET/POST | /internal/schedule | Vercel cron. Reads the durable store and fires due Device calls. |

| POST | /internal/telnyx/voice | Telnyx Call Control webhooks (signature required) |

| POST | /internal/telnyx/sms | Telnyx messaging webhooks (signature required) |

Every call and message creates a session. stream_url is present when agent is set.

Internal Telnyx handlers verify telnyx-signature-ed25519 and telnyx-timestamp. Invalid signature is 401 and does not append an Event.

Seed

  • Key: nl_test_…
  • Number: num_demo (+14155550100)
  • Route: rte_default
  • Agents: agt_clinic_front, agt_brief_420
  • Campaigns: cmp_clinic (approved), cmp_12 (T-Mobile not approved)

T-Mobile fixture: +15551201234. AT&T fixture: +15551301234.

Twilio aliases

Only if TELDEV_TWILIO_ALIASES=1:

  • POST /2010-04-01/Accounts/:sid/Messages.json
  • POST /2010-04-01/Accounts/:sid/Calls.json

Still require a TelDev Bearer key. Not linked from the homepage.