FreePBX CallerID Superfecta module for TrueCNAM

source-TrueCNAM.module

<?php
/**
 * TrueCNAM module
 * Service Details at http://truecnam.com/products
 * Free Users get 2 lookups/minute 25/hour as of this note. Visit site for latest info
 * Copyright (C) 2015 Sangoma Technologies
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * 06.04.2015 initial release by James Finstrom [email protected]
 * 06.04.2015 Adding recommendations per Lorne Gaetz.
 *
 */

class TrueCNAM extends superfecta_base{
  public $description = "truecnam.com lookup module can pull CNAM, stored CNAM and spam score.";
  public $version_requirement = "2.11";
  public $source_param = array(
    'APIKey' => array(
      'description' => "API Key - Can be obtained after registering with truecnam.com",
      'type' => 'text'
    ),
    'Password' => array(
      'description' => "truecnam password",
      'type' => 'password'
    ),
    'TrueSpam' => array(
      'description' => 'Evaluate TrueSpam score',
      'type' => 'checkbox',
      'default' => 'checked'
    ),
    'TrueSpam_Threshold' => array(
      'description' => "Maximum TrueSPAM score The scale is 0-100, Recommended 80",
      'type' => 'number',
      'default' => '80'
    )
  );
  function get_caller_id($thenumber, $run_param=array()) {
    $debug = $this->debug;
    if(empty($run_param['APIKey']) || empty($run_param['Password'])) {
        $this->DebugPrint("TrueCNAM requires a registered account.");
        return '';
    }
    if($run_param['TrueSPAM']){
      $this->DebugPrint("TrueSpam enabled");
      $resp_type = 'extended';
    }else{
      $this->DebugPrint("TrueSpam disabled");
      $resp_type = 'basic';
    }
    $url = sprintf("https://api.truecnam.net/api/v1?username=%s&password=%s&resp_type=%s&resp_format=json&calling_number=%s&call_party=terminating",$run_param['APIKey'],$run_param['Password'],$resp_type,$thenumber);
    $ret = $this->get_url_contents($url);
    $data = json_decode($ret,true);
    if($data['err']){
      $this->DebugPrint("Lookup Error");
      $this->DebugPrint($data['error_message']);
    }
    if($run_param['TrueSPAM']){
      if($data['spam_score_match']){
        $this->DebugPrint("TrueSpam Score availible");
        if($data['spam_score'] > $run_param['TrueSpam_Threshold']){
          $this->spam = true;
        }else{
          $this->spam = false;
        }
      }else{
        $this->DebugPrint("TrueSpam Score not availible");
        $this->spam = false;
      }
    }
    return($data['name']);
  }
}

Overhaul based on testing and comments from truecnam.

• removed lines setting spam = false, could interfere with other lookups
• fixed typos with variable names TrueSPAM/TrueSpam
• added support for user to share did with truecnam per their request
• added support for user to config for either name or spam score or both
• added some debug output and inline comments

<?php
/**
 * TrueCNAM module
 * Service Details at http://truecnam.com/products
 * Free Users get 2 lookups/minute 25/hour as of this note. Visit site for latest info
 * Copyright (C) 2015 Sangoma Technologies
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * 2015-06-04 initial release by James Finstrom [email protected]
 * 
 */

class TrueCNAM extends superfecta_base{
    public $description = "truecnam.com lookup module can pull CNAM, stored CNAM and spam score.";
    public $version_requirement = "2.11";
    public $source_param = array(
        'APIKey' => array(
            'description' => "API Key - Can be obtained after registering with truecnam.com",
            'type' => 'text',
        ),
        'Password' => array(
            'description' => "truecnam password",
            'type' => 'password',
        ),
        'Use_for_CNAM' => array(
            'description' => 'Use truecnam.com to look up Caller ID',
            'type' => 'checkbox',
            'default' => 'on',
        ),
        'TrueSpam' => array(
            'description' => 'Use truecnam.com to look up a spam score',
            'type' => 'checkbox',
            'default' => null,
        ),
        'TrueSpam_Threshold' => array(
            'description' => "Minimum threshold at which a call is considered spam. TrueSPAM score ranges from 0-100 with 100 being spammer",
            'type' => 'number',
            'default' => '80',
        ),
        'Share_DID' => array(
            'description' => 'Share the DID (number being dialed, i.e. your phone number not the number of the inbound caller) being called with truecnam.com to assist their algorithm efforts - optional.',
            'type' => 'checkbox',
            'default' => null,
        ),
    );
    function get_caller_id($thenumber, $run_param=array()) {
        $debug = $this->debug;
        if(empty($run_param['APIKey']) || empty($run_param['Password'])) {
            $this->DebugPrint("TrueCNAM requires a registered account.");
            return '';
        }
        $this->DebugPrint("Searching www.truecnam.com ...");

        // If user has opted to share DID, truecnam.com requires DID to be a proper phone number
        if($run_param['Share_DID']) {
            $the_did = $this->get_DID();
            if (!is_numeric($the_did)){
                $the_did = null;
            } else {
                $this->DebugPrint("Sharing DID = ".$the_did." with truecnam.com");
            }
        } else {
            $this->DebugPrint("Withholding DID from truecnam.com");
            $the_did = null;
        }

        // different response types are supported, extended response type returns all information and we can check ['cnam_match'] for true
        $resp_type = 'extended';

        $url = sprintf("https://api.truecnam.net/api/v1?username=%s&password=%s&resp_type=%s&resp_format=json&calling_number=%s&call_party=terminating&called_number=%s",$run_param['APIKey'],$run_param['Password'],$resp_type,$thenumber,$the_did);

        $ret = $this->get_url_contents($url);
        $data = json_decode($ret, true);
        if($data['err']){
            $this->DebugPrint("Lookup Error");
            $this->DebugPrint($data['error_message']);
            return;
        }
        // only do spam scoring if enabled by user
        if($run_param['TrueSpam']){
            if($data['spam_score_match']){
                if($data['spam_score'] > $run_param['TrueSpam_Threshold']){
                    $this->spam = true;
                    $this->DebugPrint("Spam score ".$data['spam_score']." exceeds threshold ".$run_param['TrueSpam_Threshold'].", marking call as spam");
                }else{
                    $this->DebugPrint("Spam score ".$data['spam_score']." less than threshold ".$run_param['TrueSpam_Threshold'].", not marking call as spam");
                }
            }else{
                $this->DebugPrint("TrueSpam Score not available");
            }
        } else {
            $this->DebugPrint("Not evaluating spam score");
        }

        // Only use for CNAM if enabled by user and lookup succeeds
        if ($data['cnam_match'] && $run_param['Use_for_CNAM']){
            $this->DebugPrint("Found name...");
            return($data['name']);
        } else {
            $this->DebugPrint("Name not available or not configured for name lookup");
        }
    }
}

works