NethVoice: port VTENEXT CRM integration from version 14

[gsanchietti]

Port the NethVoice integration with VTENEXT CRM (as described in the NethVoice 14 manual: https://nethvoice.docs.nethesis.it/it/v14/integration.html) to NethVoice version 8.

Main features:

1. Notification of external calls to VTENEXT (via AGI script, argument adaptation required)
2. Access and synchronization of call history (lookup script adaptation, authorization via CRM APIs)
3. Click-to-call from VTENEXT (via NethLink, using TEL/Call-To protocol, or keyboard shortcuts)
4. Phonebook sync: requires script updates for new version

Proposed Solution

• Port the existing integration procedures, scripts, and API configuration from NethVoice 14 to NS8
• Review all required scripts (call notification via AGI, lookup, phonebook synchronization) and update them as needed for NS8 compatibility and current API usage
• Provide step-by-step integration guides for NS8, including setup for API tokens, endpoints, and script arguments
• Clarify required configuration changes, prerequisites, and required access to the VTENEXT instance for integration testing

See also

• Manual: https://nethvoice.docs.nethesis.it/it/v14/integration.html
• Support ticket: https://helpdesk.nethesis.it/a/tickets/194217

[a-ghigi]

QA

Image 1.5.5-testing.18

For a fresh install of 1.5.5-testing.18, use the command:

add-module ghcr.io/nethesis/nethvoice:1.5.5-testing.18

For updating to 1.5.5-testing.18, use:

api-cli run update-module --data '{"module_url":"ghcr.io/nethesis/nethvoice:1.5.5-testing.18","instances":["nethvoice1"]}'

VTENEXT Configuration

Obtain the Webservice Access Key

1. Log in as the user handling the API calls
2. Open Settings (gear icon at the bottom left).
3. Select Business Process Manager (buildings icon on the left).
4. Go to Webservice REST.
5. In the Username field, select the user that will run the scripts.
6. Press the button Webservice accesskey – Show.
7. Authenticate.
8. Copy the content of the Access Key field.

Install the NethVoice.zip plugin

1. Download NethVoice.zip to your disk.
2. Open Settings (gear icon at the bottom left).
3. Select Business Process Manager (buildings icon on the left).
4. Go to Module Manager.
5. Select the Custom Modules tab.
6. Press the button Import new module.
7. Press the file selection button and choose the NethVoice.zip file from your disk.
8. Press Import.
9. Verify that the NethVoice module appears in the Standard Modules list.

Install the scripts in NethVoice

1. Access the machine via ssh.
2. To entert Nethvoice module, run the command:

   runagent -m nethvoice1
   

3. To enter freepbx container, run the command:

   podman exec -ti freepbx /bin/sh    
   

4. Copy the files:
   • lookup_vte.php from /usr/src/nethvoice/samples to /usr/src/nethvoice/lookup.d
   • vte_incoming_call.php from /usr/src/nethvoice/samples to /var/lib/asterisk/agi-bin
   • vte.php from /usr/share/phonebooks/samples/ to /usr/share/phonebooks/scripts
5. Edit all three scripts to update:
   • the API base URL
   • the username
   • the Access Key
6. Define NETHCTI_CDR_SCRIPT_EXTENSION_RING var in module environment, pointing at lookup_vte.php script
7. To acquire changes restart freepbx with command:

   systemctl --user restart freepbx
   

Test cases

lookup_vte.php

• Create a user in VTENEXT with a specific phone number.
• Call from that number.
• Check that the user information shows up.

vte.php

• Wait for user information import from VTENEXT, or force it with:

  runagent -m nethvoice1
  podman exec -ti freepbx /bin/sh
  /usr/share/phonebooks/scripts/vte.php
  

• Check VTENEXT phone directory for imported data.

vte_incoming_call.php

• Create a user in VTENEXT with an extension set.
• Call that extension.
• Check that VTENEXT logged the call and assigned it to the called user.

[Amygos]

Testing release nethesis/ns8-nethvoice 1.5.4-testing.7

[viktec]

So far I have tested only the first two scripts and both are working as expected:

lookup_vte.php

vte.php

Tests for vte_incoming_call.php have not been performed yet.