michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cc1c8f69aa
netgescon-day0/docs/ai/restart/CTI-PANASONIC-NS1000-SETUP.md

10 KiB
Raw Blame History

CTI Panasonic NS1000 - Setup operativo

Obiettivo: intercettare chiamate dal centralino Panasonic NS1000 (CSTA porta 33333) e creare/chiudere automaticamente Post-it in NetGescon con filtro rubrica.

Nota architetturale:

  • non serve un hardware dedicato aggiuntivo se il PBX espone gia CSTA in rete;
  • il bridge/adapter puo essere eseguito internamente su Linux come servizio applicativo;
  • il flusso consigliato resta Panasonic NS1000 -> adapter CSTA Linux -> API HTTPS NetGescon.

Prerequisiti verificati

  • Connessione TCP PBX CSTA: 192.168.0.101:33333 raggiungibile.
  • Modello centralino: Panasonic NS1000.

1) Configurazione applicazione NetGescon

Aggiungi in .env del nodo applicativo:

NETGESCON_CTI_SHARED_TOKEN=<TOKEN_LUNGO_RANDOM>
NETGESCON_CTI_PBX_HOST=192.168.0.101
NETGESCON_CTI_PBX_PORT=33333
NETGESCON_CTI_BRIDGE_TIMEOUT=10
NETGESCON_CTI_BRIDGE_READ_BYTES=2048
NETGESCON_CTI_BRIDGE_RECONNECT_DELAY=5
NETGESCON_CTI_BRIDGE_MAX_IDLE_TIMEOUTS=30
NETGESCON_CTI_BRIDGE_LOG_FILE=storage/logs/cti-panasonic-raw.ndjson

Poi:

cd /home/michele/netgescon/netgescon-day0
php artisan optimize:clear
php artisan config:clear
php artisan route:clear

Staging reale (confermato):

  • path applicazione: /var/www/netgescon
  • web server: nginx
  • porta pubblica: 80
  • URL staging tipico: http://<IP_SERVER_200>/

2) Endpoint disponibili

  • POST /api/v1/cti/panasonic/incoming
    • crea Post-it chiamata in chiamate_post_it
    • fa match automatico numero -> rubrica_universale
    • scrive anche communication_messages con channel=panasonic_csta, target_extension, assigned_user_id
  • POST /api/v1/cti/panasonic/call-ended
    • chiude automaticamente il Post-it aperto (match su event_id, fallback su numero)
    • salva esito, durata_secondi, chiusa_il
    • chiude anche il record communication_messages CSTA corrispondente
  • GET /api/v1/cti/panasonic/lookup?phone=...
    • solo lookup rubrica (match yes/no)
  • GET /api/v1/cti/panasonic/click-to-call/pending?extension=101
    • coda outbound per adapter/middleware CSTA
  • POST /api/v1/cti/panasonic/click-to-call/{id}/claim
    • lock logico della richiesta da parte dell'adapter
  • POST /api/v1/cti/panasonic/click-to-call/{id}/status
    • esito esecuzione (accepted, completed, failed, cancelled)

Autenticazione: header X-CTI-Token: <TOKEN>.

3) Comando server web prova (porta 8000, solo sviluppo)

cd /home/michele/netgescon/netgescon-day0
php artisan serve --host=0.0.0.0 --port=8000

Nota: in staging non usare artisan serve; usare nginx su porta 80 con root applicativa /var/www/netgescon.

4) Comando minimo per vedere solo dati HTTP in arrivo

Se vuoi solo vedere cosa arriva, senza script:

ncat -kl 8099

Se ncat non e disponibile:

while true; do nc -l -p 8099; echo; echo "-----"; done

Poi configura il centralino (o il tool di test) verso http://<IP_SERVER_200>:8099.

5) Comando minimo per sniffing CSTA grezzo (porta 33333)

Per vedere traffico protocollo CSTA a livello rete direttamente sul server .200:

sudo tcpdump -i any -nn -s0 -A host 192.168.0.101 and port 33333

Per dump esadecimale (piu utile se payload non testuale):

sudo tcpdump -i any -nn -s0 -X host 192.168.0.101 and port 33333

Se non vedi nessun pacchetto durante una chiamata:

  1. Verifica che il PBX stia davvero parlando con questo server (e non con altro host).
  2. Verifica che l'evento chiamata sia abilitato lato centralino (CSTA monitor/notify).
  3. Prova senza filtro host per escludere IP errato:
sudo tcpdump -i any -nn -s0 -A port 33333
  1. Verifica quale sorgente arriva davvero sulla porta:
sudo tcpdump -i any -nn "tcp port 33333"
  1. Verifica che non sia traffico su altra porta (es. CTI middleware):
sudo tcpdump -i any -nn -s0 -A host 192.168.0.101 and \(port 33333 or port 33334 or port 33335\)
  1. Verifica che sul server non ci sia un servizio locale che assorbe la sessione senza inoltro HTTP:
sudo ss -lntp | grep -E ':33333|:8099|:80'

5-bis) Daemon Linux minimale di cattura CSTA

Avvio manuale:

cd /home/michele/netgescon/netgescon-day0
bash scripts/ops/netgescon-panasonic-csta-bridge.sh

Il daemon:

  • apre la socket TCP verso il PBX
  • resta in ascolto con riconnessione automatica
  • salva i frame grezzi in storage/logs/cti-panasonic-raw.ndjson
  • stampa dump hex e una resa testuale best-effort

Per installarlo come servizio usare il template:

scripts/systemd/netgescon-panasonic-csta-bridge.service.template

6) Listener terminale con script (log su file)

Metti questo listener in ascolto e punta il PBX a http://<IP_SERVER_200>:8099 per vedere esattamente i dati in arrivo.

cd /home/michele/netgescon/netgescon-day0
bash scripts/ops/netgescon-cti-listener.sh --port 8099

7) Test rapido terminale (incoming + call-ended)

cd /home/michele/netgescon/netgescon-day0
bash scripts/ops/netgescon-panasonic-csta-test.sh \
  --pbx-ip 192.168.0.101 \
  --pbx-port 33333 \
  --app-url http://127.0.0.1:8000 \
  --token "<TOKEN_LUNGO_RANDOM>" \
  --phone "+393331112233" \
  --ext "101" \
  --duration 90 \
  --outcome "risposta"

8) Comandi singoli per simulare chiamate da terminale

Evento incoming (una riga):

curl -sS -X POST "http://127.0.0.1:8000/api/v1/cti/panasonic/incoming" -H "Content-Type: application/json" -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" -d '{"phone":"+393331112233","direction":"inbound","event_type":"Delivered","called_extension":"101","event_id":"evt-001","note":"test incoming"}'

Evento call-ended (una riga):

curl -sS -X POST "http://127.0.0.1:8000/api/v1/cti/panasonic/call-ended" -H "Content-Type: application/json" -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" -d '{"phone":"+393331112233","direction":"inbound","event_type":"ConnectionCleared","event_id":"evt-001","outcome":"risposta","duration_seconds":83,"ended_at":"2026-03-11T10:20:00+01:00","note":"test call-ended"}'

Lookup rubrica (una riga):

curl -sS "http://127.0.0.1:8000/api/v1/cti/panasonic/lookup?phone=+393331112233" -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>"

9) Esempio comandi da usare lato interfaccia centralino

Se il centralino puo inviare HTTP su evento incoming call, usa:

curl -sS -X POST "http://<IP_NETGESCON>:8000/api/v1/cti/panasonic/incoming" \
  -H "Content-Type: application/json" \
  -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" \
  -d '{
    "phone": "<CALLING_NUMBER>",
    "name": "<CALLER_NAME_OPTIONAL>",
    "direction": "in_arrivo",
    "called_extension": "<EXT>",
    "event_id": "<PBX_EVENT_ID>",
    "note": "evento CSTA NS1000"
  }'

Per filtro rubrica (prima del popup interno):

curl -sS "http://<IP_NETGESCON>:8000/api/v1/cti/panasonic/lookup?phone=<CALLING_NUMBER>" \
  -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>"

Per evento fine chiamata (chiusura automatica Post-it):

curl -sS -X POST "http://<IP_NETGESCON>:8000/api/v1/cti/panasonic/call-ended" \
  -H "Content-Type: application/json" \
  -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" \
  -d '{
    "phone": "<CALLING_NUMBER>",
    "direction": "inbound",
    "event_type": "ConnectionCleared",
    "event_id": "<PBX_EVENT_ID>",
    "outcome": "risposta",
    "duration_seconds": 83,
    "ended_at": "2026-03-11T10:20:00+01:00",
    "note": "evento call-ended NS1000"
  }'

13) Bridge/adapter CSTA Phase III: prova pratica

Contratto minimo consigliato per un adapter esterno:

  1. Sottoscrive gli eventi PBX/CSTA su uno o piu interni.
  2. Converte i nomi evento PBX in payload HTTP NetGescon:
    • Delivered -> incoming
    • ConnectionCleared -> call-ended
  3. Per l'outbound interroga periodicamente click-to-call/pending.
  4. Esegue claim della richiesta.
  5. Invia MakeCall o equivalente al PBX verso source_extension -> target_number.
  6. Aggiorna lo stato con accepted/completed/failed.

Payload di stato outbound consigliato:

{
  "status": "completed",
  "event_id": "csta-out-001",
  "provider_call_id": "ns1000-call-7788",
  "called_extension": "101",
  "duration_seconds": 64,
  "outcome": "answered"
}

10) Cosa fa il match numeri

  • normalizza il numero (es. +39, 0039, spazi, trattini)
  • confronta le ultime 7 cifre con:
    • telefono_cellulare
    • telefono_ufficio
    • telefono_casa
    • telefono_cellulare_nazionale

11) Dev + staging sulla stessa macchina (.200)

  • Sviluppo consigliato: http://127.0.0.1:8000 (artisan serve)
  • Staging reale: http://<IP_SERVER_200>/ su nginx:80, app in /var/www/netgescon

Comandi esempio:

# sviluppo
cd /home/michele/netgescon/netgescon-day0
php artisan serve --host=0.0.0.0 --port=8000

# staging (deploy path reale)
cd /var/www/netgescon
php artisan optimize:clear
php artisan migrate --force
sudo systemctl reload nginx

Nel PBX configura URL diversi per ambiente, mantenendo stesso payload/token o token distinti.

12) Step successivo consigliato

  1. Agganciare evento reale CSTA incoming.
  2. Agganciare evento call-ended per aggiornare esito e durata.
  3. Mostrare popup operatore in Filament con scheda rubrica trovata.

12-bis) Mappatura studio corrente

  • 201: centralino con segreteria
  • 205: operatore studio
  • 206: amministratore
  • 601: gruppo/modalita giorno
  • 603: gruppo/modalita notte

Questi interni devono essere censiti nella scheda amministratore per consentire al routing applicativo di riconoscere gli alias condivisi del PBX oltre agli interni utente personali.

12-ter) Impostazioni PBX da recuperare o configurare

  • conferma che la porta CTI/CSTA sia realmente 33333
  • eventuale utente/password o token richiesti per la sessione CSTA
  • eventuale payload iniziale di handshake/login richiesto dal PBX
  • conferma della licenza o modulo necessario per MonitorStart e MakeCall
  • elenco device/interni da monitorare:
    • 201
    • 205
    • 206
    • 601
    • 603
  • eventi da ricevere, se configurabili:
    • Delivered
    • Established
    • ConnectionCleared
    • Failed o equivalente
  • abilitazione del controllo outbound per chiamate originate da 205

Se il PBX espone solo un feed CTI generico e non una configurazione eventi dettagliata, va comunque bene: il daemon serve proprio a catturare il traffico reale e ricostruire il protocollo effettivo.