Create & Configure an API Dialplan

This section explains how to create and configure an API Dialplan using the Acefone Portal. Once configured, Acefone invokes your API whenever a call is received on a DID associated with the API Dialplan. Based on your application's response, Acefone dynamically routes the call to the appropriate destination.

Prerequisites

Before creating an API Dialplan, ensure that:

• You have Administrator access to the Acefone Portal.
• Your application exposes a publicly accessible HTTPS endpoint.
• Your API supports either GET or POST requests over HTTPS.
• Your application returns a valid Acefone API Dialplan response or uses Custom Mapping to transform its existing response format.
• The routing destinations (Agents, IVRs, Departments, Voice Bots, Queues, etc.) are already configured in your Acefone account.

Step 1: Navigate to the API Dialplan Page

Log in to the Acefone Portal and navigate to:

API Connect / Flows → API Dialplan

The API Dialplan page displays all the API Dialplans configured for your account along with details such as the Name, Description, Endpoint URL, and HTTP Method. From this page, you can:

• View all existing API Dialplans.
• Search for a specific API Dialplan.
• Edit or delete an existing configuration.
• Create a new API Dialplan.

Step 2: Create a New API Dialplan

Click + Add API Dialplan.

This opens the API Dialplan configuration page, where you can define your API endpoint and configure how Acefone communicates with your application.

Provide the following details:

Note: Only HTTPS endpoints are supported. Ensure that your endpoint is publicly accessible and capable of responding within the configured timeout.

Step 3: Configure API Request Settings

The Configurations tab allows you to configure how Acefone communicates with your API and how it handles failures.

Failover Destination

The Failover Destination acts as a backup routing option if Acefone is unable to successfully process your API request.

Acefone transfers the call to the configured Failover Destination when:

• The API endpoint is unreachable.
• The API response exceeds the configured Ring Timeout.
• The API returns an invalid or unsupported response.

Supported Failover Destinations include:

• Agent
• Voicemail
• Voice Bot
• Inbound Queue
• IVR
• Department
• Time Condition
• Auto Attendant
• Custom Dialplan
• API Dialplan
• Hangup

Ring Timeout

Specify the maximum duration (in seconds) that Acefone should wait for your API to return a response.

If a valid response is not received within the configured timeout, Acefone automatically routes the call to the configured Failover Destination. Choose an appropriate timeout based on the average response time of your application.

Content Type

Select the content type that Acefone should use when sending the API request. Supported formats include:

• application/json
• application/x-www-form-urlencoded

The request payload editor displays the default variables sent by Acefone. You can customize the payload based on your application's requirements.

Custom Mapping (Optional)

Enable Custom Mapping if your application already returns a response in its own predefined format and you do not want to modify your existing API to comply with the Acefone response structure.

When enabled, Acefone exposes a dedicated Custom Mapping tab where you can define transformation rules. Instead of requiring your application to return the Acefone response format directly, Custom Mapping acts as a response transformer. It maps the fields from your application's existing response into the Acefone API Dialplan response format before the routing decision is processed.

This allows you to integrate existing applications with minimal or no backend changes.

Step 4: Configure Request Headers

If your API requires authentication or additional HTTP headers, switch to the Headers tab.

Headers allow Acefone to include additional information with every API request. Common examples include:

Click Add to configure multiple headers.

Tip: Use request headers to securely pass authentication tokens, API keys, or any other metadata required by your application.

Step 6: Save the API Dialplan

After completing the configuration:

1. Verify the HTTPS endpoint URL.
2. Select the request method (GET or POST).
3. Configure the Failover Destination.
4. Set the Ring Timeout.
5. Add any required request headers.
6. Configure Custom Mapping, if applicable.

Click Save to create the API Dialplan.