Update 2024:
Der untere Code funktionierte leider unter 3CX V20 nicht mehr.
Zuvor wurde es schon empfohlen, nun ist es wohl notwendig: Die Verbindung zur Instanz muss via „RESET“ verbunden werden:
#beginning with v20 we need to use Reset
$t = $PS::Reset($PS::ApplicationName, $PS::CfgServerHost, $PS::CfgServerPort, $PS::CfgServerUser, $PS::CfgServerPassword)
Da 3CX in der V16 auf .NET Core umgestellt hat, kann man nicht mehr nativ mit der PowerShell an die API herantreten. Hierfür muss zunächst PowerShell Core installiert werden.
Download von PowerShell Core ist hier zu finden: https://github.com/PowerShell/PowerShell
Beispiele und eine Dokumentation der zu ladenden Bibliothek findet man unter folgendem Download: http://downloads.3cx.com/downloads/misc/callcontrolapi/3CXCallControlAPI_v16.zip
Die Call Control API war in der Vergangenheit immer erst ab der PRO-Version nutzbar. Ob das mit der V16 immer noch erst ab der PRO-Edition möglich, konnte ich leider noch nicht testen.
Nach der Installation von PowerShell Core lässt sich diese dann über pswh.exe starten.Die Umgebung wird standardmäßig unter C:\Program Files\PowerShell\6\pwsh.exe installiert.
Die Zugangsdaten für die Call Control API befinden sich in der Windows Installation unter: C:\Program Files\3CX Phone System\Bin\3CXPhoneSystem.ini
In dem Abschnitt „ConfService“ findet man die relevanten Parameter zum Verbindungsaufbau zur Call Control API.
Die Initialisierung ist immer noch über denselben Weg wie über V15 möglich, auch wenn nun wohl ein anderer Weg über PhoneSystem Reset empfohlen wird. Da der alte Weg aber noch funktioniert und für mich nachvollziehbarer ist, verwende ich noch diesen.
Die Firma Matic-Tec.de hat dankenswerter Weise in der Vergangenheit bereits einen Artikel zur Verwendung der Call Control Api mit 3CX geschrieben (siehe https://sipip.de/blog/infos/60-3cx-automatisieren-mit-powershell-und-der-call-control-api)
Auf Basis dieses Codes habe ich den nachfolgenden PowerShell-Code geschrieben, um PhoneBook-Kontakte zu löschen bzw. anzulegen:
Add-Type -Path „C:\Program files\3CX Phone System\Bin\3cxpscomcpp2.dll
„$PS = [TCX.Configuration.PhoneSystem]
$PS::CfgServerHost = „127.0.0.1“
$PS::CfgServerPort = 5485
$PS::CfgServerUser = „Username aus der INI-Datei“
$PS::CfgServerPassword = ‚Passwort aus der INI-Datei‘
$PS::ApplicationName = „ContactApp“
#until includung V18 the above worked
#$t = ($PS::Root)
#beginning with v20 we need to use Reset
$t = $PS::Reset($PS::ApplicationName, $PS::CfgServerHost, $PS::CfgServerPort, $PS::CfgServerUser, $PS::CfgServerPassword)
$t.WaitForConnect((New-TimeSpan -Seconds 30))
if ($t.Connected) {
Write-Host „connection to call api established“
$3CXTenant = $t.GetTenant()
$PhoneBookEntries = $3CXTenant.GetPhoneBookEntries()
Write-Host „Search for Entries being tagged with CustomContact“
$OurTaggedPBEntries = $PhoneBookEntries | ? {$_.Tag -eq „CustomContact“}
Write-Host „Found $($OurTaggedPBEntries.Count) Entries“
if ($($OurTaggedPBEntries.Count) -gt 0) {
Write-Host „Remove Entries beging tagged with LDAP“
foreach ($OurTaggedPBEntry in $OurTaggedPBEntries) {
$ContactDetail = „$($OurTaggedPBEntry.Firstname) $($OurTaggedPBEntry.Lastname)
$($OurTaggedPBEntry.CompanyName)“
try {
Write-Host „Successfully removed Contact $ContactDetail“
$OurTaggedPBEntry.Delete()
} catch {
Write-Error „Failed to remove Contact $ContactDetail“
}
}
}
Write-Host „Creating new Contacts“
while ($x -le 50) {
try {
$NewContact = $3CXTenant.CreatePhoneBookEntry()
$NewContact.Firstname = „Herrmann$($x)“
$NewContact.Lastname = „Mustermann$($x)“
$NewContact.Phonenumber = „004444$($x)“
$NewContact.Tag = „CustomContact“
$NewContact.Save()
$x++
} catch {
Write-Error „Failed to Add Contact. $($_.Exception.Message)“
}
}
$t.Disconnect()
}else {
Write-Error „connection to call api failed“
}
Das Skript lädt die Bibliothek 3cxpscomcpp2.dll und initialisiert dann die Verbindung ($PS::Root) unter Verwendung der Verbindungsparameter. Die PowerShell muss hierfür privilegiert gestartet werden.
Über das Attribut „Connected“ wird der erfolgreiche Verbindungsaufbau geprüft, anschließend werden zunächst alle Kontakte mit dem definierten Tag „CustomContact“ ermittelt und in der foreach-Schleife einzeln entfernt. Dies erspart das updaten der Kontakte, welches aber natürlich auch möglich ist.
Anschließend werden beispielhaft mehrere Kontakte über die While-Schleife angelegt.