Call centers often need to filter specific phone numbers to comply with regulations, block unwanted calls, or categorize contacts for better call routing. VICIdial, a leading open-source call center solution, offers the Filter Phone Groups (FPG) feature, which allows administrators to manage phone number filtering dynamically.
The add_fpg_phone API enables administrators to add phone numbers to a specific Filter Phone Group (FPG) programmatically, ensuring that calls are handled according to predefined business rules. Instead of manually updating FPG lists, this API allows for automation, integration with external compliance databases, and real-time updates.
Why Use the add_fpg_phone API?
✅ Block specific numbers from being dialed
✅ Whitelist numbers to override DNC restrictions for special cases
✅ Segment leads into different phone groups based on business logic
✅ Ensure compliance with legal regulations and internal policies
✅ Automate phone number filtering based on customer interactions
In this tutorial, we will cover:
🔹 How the add_fpg_phone API works
🔹 How to configure and authenticate API access
🔹 How to construct and send API requests
🔹 Examples using a browser, cURL, and Postman
🔹 How to interpret API responses and troubleshoot errors
🔹 Best practices for using the add_fpg_phone API efficiently
Let’s get started! 🚀
Understanding the add_fpg_phone API Function
The add_fpg_phone API allows administrators to add a phone number to a specific Filter Phone Group (FPG) dynamically. This ensures that calls to or from those numbers follow predefined rules, such as blocking, whitelisting, or special routing.
What Information Does the add_fpg_phone API Require?
✔ Filter Phone Group ID – The unique identifier for the FPG to which the phone number should be added
✔ Phone Number – The number that needs to be filtered
✔ Filter Action – The type of filtering (BLOCK, ALLOW, etc.)
✔ Expiration Date – (Optional) When the filter should expire
✔ Source – A custom identifier for tracking API calls
Common Use Cases for add_fpg_phone API
🔹 Blocking specific numbers from outbound dialing
🔹 Whitelisting high-priority clients who should always receive calls
🔹 Filtering scam or fraudulent numbers from inbound queues
🔹 Categorizing numbers for special routing or handling
🔹 Automating filter updates based on customer interactions
Step 1: Prerequisites for Using the API
Before using the add_fpg_phone API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid FPG ID to associate the phone number with
✅ VICIdial server access credentials
How to Enable API Access in VICIdial
1️⃣ Log in to the VICIdial Admin Panel
2️⃣ Navigate to Admin > Users
3️⃣ Select the user who will access the API
4️⃣ Set API Access to 1 (Enabled)
5️⃣ Set User Level to 8 or higher** (Admin-level access) 6️⃣ Add add_fpg_phoneto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to add phone numbers to an FPG dynamically using the API.
Step 2: Constructing the API Request
The VICIdial API uses HTTP GET requests, meaning you can access it via a browser, cURL, or API tools like Postman.
Base API URL
🔹 Replace your-vicidial-server with your actual VICIdial instance.
Required Parameters for add_fpg_phone API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (add_fpg_phone) |
add_fpg_phone |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | FPGUpdate |
filter_phone_group_id |
The ID of the FPG where the phone should be added | BLACKLIST |
phone_number |
The phone number to add | 18005551234 |
filter_action |
Action to apply (BLOCK, ALLOW, etc.) |
BLOCK |
expiration_date |
(Optional) Date when the filter should expire | 2024-12-31 |
Step 3: Sending the API Request
Method 1: Adding a Number to an FPG via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should add the phone number to the specified FPG.
Method 2: Adding a Number to an FPG via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a confirmation message indicating the phone number has been added to the FPG.
Method 3: Adding a Number to an FPG via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ The response should display the confirmation message for the FPG update
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the phone number has been added to the specified FPG:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
18005551234 |
The phone number added to the FPG |
BLACKLIST |
The FPG where the number was assigned |
Action: BLOCK |
Indicates that the number is blocked |
Expiration: 2024-12-31 |
The date when the filter expires |
Step 5: Handling Errors & Troubleshooting
| Error Message | Cause | Solution |
|---|---|---|
ERROR: USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION |
Insufficient API permissions | Ensure user level is 8+ and API Access is enabled |
ERROR: INVALID USERNAME OR PASSWORD |
Wrong credentials | Verify API username and password |
ERROR: PHONE NUMBER NOT PROVIDED |
No phone number specified in request | Ensure phone_number parameter is included |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_fpg_phone is included |
Conclusion
The add_fpg_phone API function is an essential tool for managing phone number filtering dynamically in VICIdial. Whether you’re blocking high-risk numbers, allowing priority calls, or integrating with external compliance systems, this API provides a fast and efficient way to enforce call center filtering rules.
Feel free to contact us or simply start a live chat to get connected to one of our team members. Here is our contact information.
Calling from US: +1 954-990-0053
Email: office@callix.ai
