How a call flows#
- The caller hears the route's greeting and, if the route has a menu, picks a service with a digit. No digit within 8 seconds selects the default service.
- AckNexa opens an incident on the chosen service with the route's severity. Its escalation policy starts as for any alert, so other channels page in parallel with the phone ringing.
- AckNexa rings, in order, whoever is on call for the service's owning team by schedule tier, then the team's admins. Only people with a phone number on their profile are rung, each for the route's ring timeout (default 25 seconds).
- Before the call is bridged, the responder hears a short whisper and must press a key, so a personal voicemail box cannot take the call.
- Answered: the incident is acknowledged by that responder. Nobody answered: the caller can leave a voicemail if the route allows it, the recording link is added to the incident, and the incident stays open and escalating.
Recent calls, on the Call Routing page under Configure, lists every call, who was tried and the outcome. Routes and the call log are for organization administrators.
Choose how the number connects#
| Provider | How it works | Connectivity |
|---|---|---|
| Twilio number | Twilio sends the call to the route's inbound URL and AckNexa drives the greeting, menu, ringing and voicemail. Requests are verified with Twilio's signature. | Twilio must reach PROVIDER_CALLBACK_BASE_URL, the API's public HTTPS origin. Twilio charges per minute and stores voicemail recordings. |
| My own PBX (gateway API) | Your PBX asks AckNexa who to ring and reports how the call ended, authenticated with the route's bearer token. | The PBX must reach the API; no internet access is needed. |
| Cisco CUCM | The bundled gateway takes the hotline over a SIP trunk from CUCM and uses the gateway API for you. | SIP and RTP between CUCM and the gateway; responders' mobiles are called back out through CUCM. |
Connect your own PBX#
Create the route with provider My own PBX. AckNexa shows a bearer token (cr_…) once; rotate it from the route card. For each call, the PBX first asks who should ring:
POST /v1/voice/route/ROUTE_ID
Authorization: Bearer YOUR_ROUTE_TOKEN
Content-Type: application/json
{"from": "+13035550199", "digit": "1", "provider_call_id": "pbx-call-id"}The response names the service and incident, the ring timeout, whether voicemail is on, and the ordered list of people with their phone numbers. The incident already exists at that point. When the call ends, the PBX posts the result to /v1/voice/route/ROUTE_ID/result with status connected, missed or voicemail; connected acknowledges the incident for the user who answered, while missed and voicemail leave it open and note the outcome. A PBX that plays the menu itself can read the route configuration with GET on the same path.
Cisco CUCM gateway#
The gateway has two parts: the acknexa-voice-asterisk image, an Asterisk with one SIP trunk to CUCM that accepts SIP only from the CUCM addresses you list and has no phones, registrations or management interfaces; and the voicegateway command in the backend image, which asks AckNexa who to ring, tells Asterisk what to do and reports the result. Deploy it with the deploy/onprem/voice-gateway.compose.yml overlay or the Helm voiceGateway values. Plain CUCM is enough; no UCCX, CUBE scripting or IVR licence is involved.
- CUCM 12.5, 14 or 15, with administrator access.
- A host or Kubernetes node with a fixed IP that CUCM can reach on SIP 5060 (UDP and TCP), plus the RTP range (UDP 10000-10099 by default) from phones, PSTN gateways and media resources.
- PSTN access from CUCM. Responders are called on the numbers on their AckNexa profile, in international format.
- G.711 between the gateway and the phones or PSTN gateways; the gateway does not transcode G.729.
- A call route with provider My own PBX, its ID and its token.
Run voicegateway check after deployment to confirm the route. If AckNexa cannot be reached, the caller hears that the on-call team could not be reached and can be put through to a fallback number (VOICEGW_FALLBACK_NUMBER). Calls in progress are dropped when the gateway restarts.
Call routing is not voice paging#
Call routing answers inbound hotline calls. Voice notifications from escalation policies are separate: they use Twilio or the internal voice gateway contract, which still needs a customer-supplied bridge to CUCM, SIP or the PBX.