Voice Apps
A Voice App is a configuration object that ties your Teler phone numbers to your application. It tells Teler two things: where to ask for instructions when a call comes in, and where to send lifecycle events.
You attach one or more Teler numbers to a Voice App. When any of those numbers is dialed, Teler hits the Voice App’s Incoming Call URL asking for a Call Flow.
When to use a Voice App
Section titled “When to use a Voice App”| Scenario | Use a Voice App? |
|---|---|
| You bought a Teler number and want it to do something on incoming calls | Yes |
| You want to make outbound calls only | You don’t configure one per call. Instead, pass flow_url directly when initiating. Just note that from_number must still belong to a Voice App, since that app is recorded on the call See Outbound calls still link to a Voice App. |
| You’re routing calls through your own SIP infrastructure (PBX/SBC) | No. Use a SIP Trunk instead |
Outbound calls still link to a Voice App
Section titled “Outbound calls still link to a Voice App”When you initiate an outbound call you pass flow_url directly and never send an
voice_app_id, so there’s no Voice App to configure for the call itself. But the
from_number you dial from must already belong to a Voice App. Teler resolves
that app from the number and records it on the resulting
Call Session and CDR, surfaced in the API as
voice_app_id. The flow_url you pass overrides the app’s configured flow for
that one call; it does not remove the Voice App link.
How it fits
Section titled “How it fits”Properties
Section titled “Properties”| Field | Type | Required | Default | Description |
|---|---|---|---|---|
app_name | string | yes | must be provided | Human-readable identifier shown in the dashboard. |
incoming_call_url | string (HTTPS) | yes | must be provided | Endpoint Teler POST’s to when a call arrives. Must respond within 5 seconds with a Call Flow. Sent on the wire as flow_url. |
call_status_url | string (HTTPS) | yes | must be provided | Endpoint that receives call lifecycle webhooks. Sent on the wire as webhook_url. |
channels | integer | no | null | Maximum number of simultaneous calls this app can handle (wire field channel_limit). If channel_limit is null, the account-level channel limit applies instead. Additional channels can be purchased. |
webhook_api_version | enum | no | 2026-06-01 | Pins the webhook wire format. Set to 2025-08-01 or 2026-06-01. See API versioning. |
Example
Section titled “Example”A Voice App named Support IVR:
| Field | Value |
|---|---|
app_name | Support IVR |
incoming_call_url | https://api.example.com/teler/flow |
call_status_url | https://api.example.com/teler/webhook |
channels | 10 |
Concurrency and channels
Section titled “Concurrency and channels”Teler enforces the channels limit at the Voice App level. If a 11th caller
dials in while 10 calls are already active on a 10-channel app, Teler returns a
busy signal. Plan your channel count for peak: buffer at least 20% headroom
above expected concurrency.
Testing in sandbox mode
Section titled “Testing in sandbox mode”To test a Voice App in sandbox mode, assign your sandbox reference number to it. Each Voice App also gets a 4-digit sandbox PIN when it’s created; callers enter it after dialing your sandbox virtual number to reach this app. See Testing calls.
Manage Voice Apps
Section titled “Manage Voice Apps”Voice Apps are managed through the Teler dashboard or programmatically using the Voice Apps API, the Python SDK, or the Node SDK