Skip to main content
This section covers endpoints inside app/api/phone-numbers, inbound-configurations, sms, and session. All routes require a phone-verified bearer token.

​
Phone numbers

​
Search inventory

  • GET /api/phone-numbers/search → ["twilio"] (provider slugs).
  • GET /api/phone-numbers/search/{provider}/countries → list of countries and supported number types (local, mobile, tollFree, etc.).
  • GET /api/phone-numbers/search/{provider}?country=US&type=local returns available numbers and their pricing. Each entry includes:
    FieldDescription
    name, phoneNumberTwilio metadata for display purposes.
    capabilities.voice/sms/mmsBoolean flags.
    addressRequirements"none", "local", or "foreign" depending on regulations.
    price{ currency, amount, jwt }. The jwt encodes the SKU and is required when purchasing.

​
Purchase & store addresses

  • PUT /api/phone-numbers/address with { street, city, region, postalCode, isoCountry, ... } creates a Twilio address SID you can reuse when buying regulated numbers.
  • PUT /api/phone-numbers expects { jwt: string } (copied from the search response) plus optional description and addressSid. The route:
    1. Verifies that a default payment method exists (Stripe).
    2. Reserves the number via Twilio.
    3. Starts a Stripe subscription so the number stays active.
    4. Returns the new Telentir phone ID.
If the user has no card on file you’ll receive HTTP 409 and a Stripe Checkout URL in the response body.

​
Manage purchased numbers

  • GET /api/phone-numbers → list all numbers (type, friendly name, references, inbound configuration attachment).
  • GET /api/phone-numbers/{id} → single record.
  • PATCH /api/phone-numbers/{id} body { name?: string, description?: string }.
  • DELETE /api/phone-numbers/{id} cancels the Twilio number and its Stripe subscription. Failure to cancel the subscription returns HTTP 502.

​
Inbound configurations

app/api/inbound-configurations lets you map phone numbers to AI or human agents with optional knowledge bases.

​
GET /api/inbound-configurations

Returns all configs for the user, expanding the humanAgents array from the stored metadata.

​
PUT /api/inbound-configurations

Body (all required unless noted):
FieldDescription
nameDisplay label.
agentObject reference { id, type, ... } pointing to an encrypted agent.
sourceCampaign source descriptor (same shape Telentir stores on campaigns).
humanAgentsOptional array of human agent references; duplicates are stripped.
description?Text shown in the UI.
knowledge_base_id?Link to a knowledge base uploaded via /api/knowledge-bases.

​
GET /api/inbound-configurations/{id}

Returns a single config plus de-duplicated humanAgents.

​
PUT /api/inbound-configurations/{id}

Updates name/agent/source/human agents. All new agent IDs are validated against the encrypted object store to ensure they exist.

​
PATCH /api/inbound-configurations/{id}

Partial updates for name, description, source, and humanAgents.

​
DELETE /api/inbound-configurations/{id}

Removes the config entirely.

​
Attach/detach numbers

POST /api/inbound-configurations/{id} body { action: "attach"|"detach", phone_number_id }.
  • "attach" requires the number’s type to be "inbound" or "both".
  • "detach" only succeeds if the number is currently attached to the selected configuration.

​
SMS

​
POST /api/sms/messages

Body: { phoneNumberId: string, to: string, body: string }. The route validates ownership of the phoneNumberId, forwards the SMS through Twilio, and stores Telentir’s webhook URL in statusCallbackUrl so delivery updates feed back into the dashboard. The response mirrors Twilio’s message SID and status.

​
Call sessions

​
POST /api/session/call

This endpoint executes lib/sessions.call with the data embedded in an application-specific JWT. Body:
FieldDescription
jwtSigned payload created by one of your registered servers. It must decrypt to { agent, contact, humanAgents?, pathway? } (see below).
serverServer ID (from /api/servers) used to verify and decrypt the JWT.
The decrypted payload must include:
  • agent: encrypted agent record (AI voice, voice settings, etc.).
  • contact: encrypted contact object for the callee.
  • Optional humanAgents: extra humans who will be conferenced in.
  • Either { type: "pathway", pathway: ConversationalPathway } or { type: "prompt", prompt: string }.
  • Optional knowledgeBase metadata if you attach KB functions inside getPrompt.
Telentir generates the LLM prompt (getPrompt + getContactPrompt), assembles available integration functions, and streams the call through the audio server. The HTTP response is empty (204) – monitor /api/events or your own webhooks for progress.

​
Temporary testing sessions

Routes under /api/session/temporary let you spin up quick test calls without touching encrypted objects. They rely on Twilio and the preconfigured call types stored in lib/call-types.ts.
EndpointDescription
GET /api/session/temporaryReturns the list of available call type definitions (types).
PUT /api/session/temporaryBody { phone: string, type: string }. Sends a verification code via SMS and returns a signed key.
POST /api/session/temporaryBody { key, code, email }. Validates the code, reserves a temporary Telentir phone number, and kicks off a one-off outbound call using the requested call type. The response is the session ID.
Verification keys are single-use and expire after 10 minutes (enforced by the server-side cache in session/temporary/route.ts).