Receive Incoming Voice Calls

Configure your Project

You must configure the following for the inbound voice service for your project through the EnableX portal. Follow the detailed guidelines given in Getting Started with Voice page to configure:

  • A Phone Number: To receive an inbound voice call.
  • A Voice Prompt (Optional): If not configured, default prompts are played.
  • A Webhook: To process the inbound voice call.

Shared vs. Dedicated Phone Number

If you have chosen a shared incoming call, a PIN will be displayed along with the assigned phone number. This PIN is used for receiving a call and once the caller dials the PIN, the call is routed to your application.

If the incoming number is a dedicated number, the prompt configured for the incoming number is played and the control is handed over to the program using the configured webhook event.

Welcome Voice Prompt

If a greeting is configured, the greeting is played by the system. Once the play is complete, a webhook is invoked for further processing.

Incoming Event on Webhook

Below is a sample of an incoming event JSON posted to Webhook:

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"state": "incomingcall",
	"from": "CLI number",
	"to": "Destination number",
	"timestamp: "2020-02-16T10:52:00Z"
}

** Explanation of JSON

KeyDescription
voice_idvoice_id of the incoming call. This identification shall be used for all further requests to the server.
stateThe webhook notification is set to call as soon as an incoming call is received. The call can be rejected through the API. This state is invoked if there no greeting configured by default.
fromThe originating number (typically the configured number) used as the CLI.
toThe number to which the call is dialed in. This is the phone number which is assigned to the voice service for the project.
timestampThe timestamp at which the call is received.

Accept Call to Process

If the application developer wants to take control of the call before it is auto-answered, the default greeting must be removed and a webhook implemented for sending the notification of the incoming call. When the application receives the webhook event, the accept API can be used to accept the call. If this API is not called, the call is not answered and is dropped.

Sample Accept Request:

POST https://api.enablex.io/voice/v1/call/{{$voice_id}}/accept
Authorization: Basic xxxxx

Note that the API Endpoint URL has embeded Voice ID. This Voice ID is received with the Incoming Event.

Sample Response:

HTTPS 200 Success 


{
    "voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81"
    "status": "success"
    "timestamp":"2023-01-10T13:47:59.667Z"
}

** Explanation of JSON

KeyDescription
voice_idVoice instance of the voice service call
statusStatus of the accept call request

Sample Webhook Event: Webhook event, once the call is accepted

{ 
	"voice_id": a8e3607c-46a1-43f6-b0be-f3ead722a6b1",
	"from": "CLI number", 
	"to" : "Destination number", 
    "state" : "connected | disconnected",
	"recording_url": "https://domain/path/sample.wav", // if recording started
    "recording_duration": 50,                           // In seconds.
	"timestamp": "2020-02-16T10:52:00Z" 
}
Programmable Voice API | Error HandlingProgrammable Voice API | API Routes