Introduction

This guide outlines an implementation approach that has been successful for customers integrating Pure CallerID Aegis services with ViciDial, enabling real-time compliance workflows to be executed before a call is delivered to the carrier network.

For customers also using Pure CallerID Core services, this guide further details how to dynamically assign outbound telephone numbers (pcidFromNumber), ensure proper STIR/SHAKEN support, and keep your telephone number inventory current via daily syncs and webhook-driven remediation.

⚠️ Note:
This is not a one-size-fits-all solution. Both Asterisk and ViciDial are highly customizable open-source platforms, and many production environments include proprietary dial plan logic, third-party modules, or custom data handling.

What follows is a sample implementation pattern that reflects what we’ve had reported to us as successful real-world deployments. Use at your own discretion. Adaptation to your environment is expected.

Related: Aegis Workflow Execution

SECTION 1: Execute Aegis Workflow Pre-Call

What This Does

This section outlines how to trigger an Aegis compliance workflow before a call is placed from ViciDial. The purpose is to decide whether a call should proceed, based on your compliance rules, data, campaign logic, or other configured decisioning. Aegis acts as the real-time gatekeeper, either allowing or rejecting the call, and optionally returning a provisioned TN (pcidFromNumber) if you're using Core.

Why This Matters

• Compliance & Risk Reduction: Only approved calls are delivered to the carrier.

• Real-Time Decisions: You can block high-risk leads, bad data, or non-consented contacts before allowing the call to egress to the carrier network.

• Optional Core Phone Number Assignment: If Core is in use, you’ll also receive an assigned trusted outbound telephone number, properly mapped for geographical relevance, for STIR/SHAKEN signing and trusted consumer contact.

How to Implement: Aegis Workflow Execution

1.1 Prerequisites

• Pure CallerID API key(s) and fully built, tested, and published Aegis workflow(s) - available via the Pure CallerID application

• ViciDial server access

• AGI support and shell scripting

• jq installed on the server

1.2 AGI Script: aegis_pre_call.sh

#!/bin/bash
while read -r ARG && [ "$ARG" != "" ]; do export "$ARG"; done

RESPONSE=$(curl -s -X POST https://api.purecallerid.com/aegis/workflow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
        \"lead_id\": \"${uniqueid}\",
        \"phone_number\": \"${CALLERID(num)}\",
        \"campaign_id\": \"${campaign_id:-unknown}\",
        \"user\": \"${user:-system}\"
      }")

ACCEPTED=$(echo "$RESPONSE" | jq -r '.accepted')
if [ "$ACCEPTED" != "true" ]; then
  exit 0
fi

PCID_FROM=$(echo "$RESPONSE" | jq -r '.pcidFromNumber')
echo "SET VARIABLE PCID_FROM $PCID_FROM"

1.3 Dialplan Update

exten => _X.,1,AGI(aegis_pre_call.sh)
exten => _X.,n,Set(CALLERID(num)=${PCID_FROM})
exten => _X.,n,Dial(SIP/${EXTEN}@carrier,60,tTor)

SECTION 2: Dynamic Assignment of Core Community CallerID Pool Numbers

What This Does

This section explains how to use the Core telephone number returned by Aegis (pcidFromNumber) as the Caller ID for the outbound call. These numbers are fully provisioned, branded, monitored, and signed under Pure CallerID’s Core service infrastructure to the specific brand and campaign associated with the Aegis workflow.

Why This Matters

• STIR/SHAKEN Compliance: Calls need to be signed with an authorized number to avoid attestation issues with your carrier partners.

• Reputation & Branding: Using a provisioned number helps protect answer rates and brand trust.

• Per-Call Precision: Aegis provides the most appropriate number based on campaign, use case, geographic relevance. 

How to Implement Core (Dynamic Community CallerID Pool Number Assignment & STIR/SHAKEN)

If you are a Core services customer, each Aegis-approved call will supply a specific outbound number (pcidFromNumber) returned by Aegis. These numbers are:

• Fully provisioned, registered, managed, and monitored to your brand and specific campaign being called in the Aegis workflow

• Regularly serviced (based on time-based policies)

• Replaced automatically if flagged by SPAM Sentry for remediation

2.1 Configure STIR/SHAKEN

Update stir_shaken.conf in Asterisk to support dynamic signing for these numbers:

[tn]
type=tn
private_key_file=/etc/asterisk/keys/core.key
public_cert_url=https://yourdomain.com/corecert.pem
attest_level=A

2.2 Create Core Community CallerID Pool Storage Table

CREATE TABLE pcid_core_tns (
  tn VARCHAR(15) PRIMARY KEY,
  status ENUM('active','retired') DEFAULT 'active',
  last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2.3 Keep This Table Updated

There are two required mechanisms to ensure the Core pool number list remains current:

A. Daily Inventory Sync (Scheduled Job)

Use this endpoint daily to validate your active numbers: Phone Number Inventory API

curl -s -X GET https://api.purecallerid.com/number-inventory \
  -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.numbers[]' | while read -r tn; do
    mysql -e "INSERT INTO pcid_core_tns (tn) VALUES ('$tn') ON DUPLICATE KEY UPDATE status='active', last_updated=NOW();"
done

B. Sentry Replacement Webhook (Realtime Updates)

Configure this webhook to receive replacement events within the admin section of the Pure CallerID application: Webhook Event Examples – Sentry Replacement

Example Payload:

{
  "event": "sentry_number_replaced",
  "old_tn": "+14065550100",
  "new_tn": "+14065550199",
  "timestamp": "2025-07-09T12:34:56Z"
}

Recommended Action:

• Mark old_tn as retired in your DB

• Insert new_tn as active

Webhook handler pseudo-code:

UPDATE pcid_core_tns SET status='retired', last_updated=NOW() WHERE tn='+14065550100';
INSERT INTO pcid_core_tns (tn, status) VALUES ('+14065550199', 'active')
  ON DUPLICATE KEY UPDATE status='active', last_updated=NOW();

Summary: Recommended Steps For Implementation 

Related Links

• Aegis Workflow – API Guide

• Phone Number Inventory API

• Webhook Event Examples