- Home
- /
- Articolo
Grazie per il feedback.
Webhook dei registri delle chiamate dettagliati per Webex Calling in Partner Hub
In questo articolo
Feedback?I partner multi-tenant (MT) di Webex Calling possono configurare un webhook per raccogliere i record di Webex Calling per tutti i clienti. Ciò consente un'efficiente riconciliazione della fatturazione, analisi, e reporting senza dover interrogare ogni cliente individualmente.
Panoramica
Il webhook Detailed Call Records offre una soluzione sicura, scalabile e robusta basata su eventi anziché su richieste. Questo webhook offre maggiore visibilità sulle attività Webex Calling dei tuoi clienti, supportando casi d'uso che vanno dalla fatturazione alla creazione di report personalizzati.
È possibile utilizzare questo webhook per raccogliere comodamente i record di tutti i clienti gestiti tramite Partner Hub, senza dover interrogare ogni cliente singolarmente. Questo webhook consente di sviluppare applicazioni personalizzate di reporting, fatturazione e analisi sia per requisiti aziendali interni che per servizi a valore aggiunto.
Per un'introduzione al webhook e alle API ad esso associate, guarda questo Vidcast: API cronologia dettagliata delle chiamate dei partner di Webex Calling.
Cosa offre il webhook Partner
Il webhook fornisce ogni 5 minuti registri dettagliati della cronologia delle chiamate. Ogni payload del webhook contiene:
- Registrazioni delle chiamate terminate tra 10 e 5 minuti prima dell'ora corrente.
- Eventuali registrazioni tardive elaborate dal cloud Webex Calling.
- Riempie automaticamente i record delle chiamate in ritardo nei payload dei webhook successivi per garantire una consegna affidabile.
Per mostrare come i record delle chiamate sono inclusi in ciascun payload, si consideri il seguente esempio:
- Un carico utile ricevuto a 14:05 contiene chiamate terminate tra 13:55 E 14:00.
- Chiamate che terminano tra 14:00 E 14:05 sono inclusi nel 14:10 carico utile.
- Registrazioni completate in precedenza (ad esempio, una chiamata terminata alle 14:04) ma elaborato in ritardo dal cloud Webex Calling (ad esempio, a 14:11) sono inclusi nel prossimo carico utile programmato (ad esempio, 14:15).
I webhook forniscono record in modo affidabile. Tuttavia, potresti ricevere record duplicati nei payload webhook successivi quando il sistema riproduce i record in determinate condizioni. Sei responsabile della gestione della deduplicazione dei record. Per identificare i record duplicati, utilizzare il campo reportId come chiave primaria e il campo reportTime per determinare quando una chiamata è stata completata o elaborata. Utilizza questi campi per aggiornare o inserire i record nei tuoi archivi dati interni.
Webhook in Partner Hub
Fornendo un webhook, consenti alla piattaforma di analisi di inviare i record delle chiamate al tuo URL di callback ogni volta che vengono generati.
I record di Webex Calling vengono forniti utilizzando lo stesso formato delle API esistenti Detailed Call Records. Puoi impostare un webhook e scegliere tra due tipi di feed:
- Analisi: include tutti i record delle chiamate per tutte le organizzazioni clienti con cui il partner ha una relazione Webex Calling. Ciò include le organizzazioni in cui:
- Il partner gestisce l'organizzazione del cliente con il ruolo di amministratore completo del partner.
- L'organizzazione del cliente ha un abbonamento Webex Calling attivo all'interno dell'organizzazione partner.
- Fatturazione: include i record delle chiamate effettuate dagli utenti con una licenza Webex Calling venduta e fornita dal partner. In questo feed sono inclusi i registri delle chiamate per gli spazi di lavoro.
Accesso e riservatezza dei dati
Solo il partner proprietario può accedere ai registri dettagliati delle chiamate (CDR) per la fatturazione.
- Un partner (o sub-partner) che gestisce la licenza associata al record di chiamata diventa il partner proprietario.
- La proprietà è determinata da: ID utente > ID licenza > ID abbonamento > ID partner.
- Ogni CDR è accessibile a un singolo partner.
- Alcuni record di chiamata non sono associati a un partner di fatturazione e non tutti i partner associati a un'organizzazione hanno pari accesso a tutti i record, poiché questi record potrebbero contenere informazioni di identificazione personale (PII).
Imposta un URL di richiamata webhook
Configurare il webhook nel Partner Hub. È possibile impostare un solo webhook per organizzazione partner.
Assicurati di avere il ruolo di amministratore completo del partner con 'Accesso a livello di amministratore completo dell'organizzazione' e Accesso API CDR Webex Calling selezionato in Control Hub (in , seleziona un amministratore completo o un amministratore completo partner, quindi seleziona ).
| 1 |
Accedere all'hub partner. |
| 2 |
Vai a .  |
| 3 |
Inserisci un URL da utilizzare in Webhook. L'URL deve terminare con /webhook (Per esempio, https://yourdomain.com/webhook).
|
| 4 |
Se desideri autenticare i payload dei tuoi webhook con un token segreto, puoi aggiungerne uno. Per ulteriori informazioni sui webhook e sui token segreti di Webex, vedere Webex per sviluppatori: Webhook. |
| 5 |
Selezionare uno dei seguenti Tipo di risorsa da utilizzare per il webhook:
|
Endpoint API partner
Oltre al webhook, Webex Calling fornisce endpoint API per supportare la riconciliazione dei dati. Questi endpoint consentono di recuperare o riconciliare i propri archivi dati con eventuali record mancanti che il listener del webhook potrebbe non aver ricevuto. I due endpoint API sono Reconciliation API e Records API.
I record di queste API sono disponibili per 30 giorni. Per assicurarti di ricevere tutti i record previsti, ti consigliamo di riconciliare periodicamente i tuoi archivi di record, ad esempio ogni 12 o 24 ore.
Per accedere a queste API è necessario utilizzare un token di accesso partner. Ottieni e gestisci il token di accesso del tuo partner secondo le pratiche standard di gestione dei token di accesso di Webex Developer.
Gli intervalli di finestre API sono applicabili a entrambi gli endpoint per gestire al meglio il carico del servizio.
- Per intervalli di tempo superiori a 48 ore, la durata massima consentita è di 12 ore (consigliata e applicata).
- Per intervalli di tempo pari o inferiori a 48 ore, la durata massima consentita è di 48 ore (opzione non consigliata; questa opzione verrà eliminata a partire dal 30 gennaio 2026).
- Per un ID organizzazione partner, la velocità delle API è limitata a una richiesta API iniziale al minuto, per ambito token. Se si utilizza la paginazione, sono consentite fino a 10 richieste API paginate aggiuntive al minuto per token, che possono essere effettuate subito dopo la richiesta iniziale.
Endpoint API di riconciliazione
L'endpoint dell'API di riconciliazione restituisce il numero totale di record di chiamata generati per ciascun cliente gestito dal partner entro il periodo di tempo specificato. È possibile utilizzare questi totali per verificare l'archiviazione locale e identificare eventuali record di chiamate mancanti o incoerenti per clienti specifici.
Se gestisci più di 200 organizzazioni clienti, l'API suddivide i risultati in pagine per migliorarne la leggibilità.
L'URL dell'endpoint dell'API di riconciliazione utilizza il seguente formato:
https://analytics-calling.webexapis.com/v1/partners/cdrcountbyorg?endTime=YYYY-MM-DDTHH:MM:SS.000Z&startTime=YYYY-MM-DDTHH:MM:SS.000Z Parametri API
È possibile utilizzare l'API per recuperare i registri delle chiamate degli ultimi 30 giorni. La finestra temporale selezionata deve iniziare almeno 5 minuti prima dell'ora UTC corrente e non può superare le 12 ore tra l'ora di inizio e quella di fine in una singola chiamata API.
I parametri API sono:
- startTime (obbligatorio, stringa): data e ora di inizio (UTC) per il primo record che si desidera raccogliere. Assicurarsi che:
- Formatta l'ora come
YYYY-MM-DDTHH:MM:SS.mmmZ. Per esempio,2025-08-15T06:00:00.000Z.
- La data e l'ora di inizio non devono essere anteriori di oltre 30 giorni rispetto all'ora UTC corrente.
- La finestra tra
startTimeeendTimenon può superare le 12 ore.
- Formatta l'ora come
- endTime (obbligatorio, stringa): data e ora di fine (UTC) per i record che si desidera raccogliere. I record si basano sull'orario di segnalazione, ovvero quando la chiamata viene effettuata. Assicurarsi che:
- Formatta l'ora come
YYYY-MM-DDTHH:MM:SS.mmmZ. Per esempio,2025-08-15T18:00:00.000Z. - La data e l'ora di fine devono essere 5 minuti prima dell'ora UTC corrente e non devono essere antecedenti a 30 giorni.
- La data e l'ora di fine devono essere maggiori di
startTime. - La finestra tra
startTimeeendTimenon può superare le 12 ore.
- Formatta l'ora come
Esempio di risposta JSON dell'endpoint dell'API di riconciliazione:
{
"cdr_counts": [
{
"orgId": "zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
"count": 3009
},
{
"orgId": "yyyyyyyy-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
"count": 129
},
{
"orgId": "xxxxxxxx-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
"count": 27895
}
]
}
Le intestazioni di risposta dell'API indicano il numero totale di organizzazioni restituite e se sono disponibili pagine aggiuntive. Controlla i seguenti parametri dell'intestazione per assicurarti di aver interrogato tutte le pagine:
- num-pagine: Numero totale di pagine (ad esempio, 2)
- organizzazioni totali: Numero totale di organizzazioni incluse nella risposta (ad esempio, 283)
- pagina corrente: Il numero di pagina corrente (ad esempio, 1)
Ad esempio, se le intestazioni mostrano num-pages=2, total-orgs=283, E current-page=1, stai visualizzando la prima pagina di una risposta di due pagine contenente in totale 283 organizzazioni. Per accedere alla pagina successiva, aggiungere il page=2 parametro alla tua richiesta GET, come mostrato di seguito:
https://analytics-calling.webexapis.com/v1/partners/cdrcountbyorg?endTime=YYYY-MM-DDTHH:MM:SS.000Z&startTime=YYYY-MM-DDTHH:MM:SS.000Z&page=2Endpoint API dei record
L'endpoint dell'API Records viene utilizzato per interrogare i record delle chiamate mancanti per organizzazioni specifiche in cui sono state identificate discrepanze o dati mancanti tramite l'API Reconciliation.
L'API Records restituisce i record delle chiamate in formato JSON, identico al formato descritto nell'API Detailed Call History. Il payload restituito contiene campi identici al payload restituito dalla cronologia dettagliata delle chiamate. Per ulteriori informazioni sui campi e sui relativi valori, vedere Report dettagliato della cronologia delle chiamate di Webex Calling.
L'API fornisce i registri delle chiamate terminate 5 minuti prima dell'ora corrente. Per garantire che tutti i registri delle chiamate siano resi disponibili, consigliamo di interrogare l'API un'ora dopo l'intervallo di tempo preferito.
L'URL dell'endpoint dell'API Records utilizza il seguente formato:
https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=YYYY-MM-DDTHH:MM:SS.000Z&startTime=YYYY-MM-DDTHH:MM:SS.000ZParametri API
- OrgID (obbligatorio, stringa): ID dell'organizzazione per la quale si desidera recuperare i record. È possibile ottenere gli ID organizzazione dall'API di riconciliazione.
- startTime (obbligatorio, stringa): data e ora di inizio (UTC) per il primo record che si desidera raccogliere. Assicurarsi che:
- Formatta l'ora come
YYYY-MM-DDTHH:MM:SS.mmmZ. Per esempio,2025-08-15T06:00:00.000Z. - La data e l'ora di inizio non devono essere anteriori di oltre 30 giorni rispetto all'ora UTC corrente.
- L'intervallo tra
startTimeeendTimenon deve superare le 12 ore in una singola richiesta API.
- Formatta l'ora come
- endTime (obbligatorio, stringa): data e ora di fine (UTC) dell'ultimo record che si desidera raccogliere. I record si basano sull'orario di segnalazione, ovvero quando la chiamata viene effettuata. Assicurarsi che:
- Formatta l'ora come
YYYY-MM-DDTHH:MM:SS.mmmZ. Per esempio,2025-08-15T18:00:00.000Z. - La data e l'ora di fine devono essere almeno 5 minuti precedenti all'ora UTC corrente e non più vecchie di 30 giorni.
- La data e l'ora di fine devono essere maggiori di
startTime. - L'intervallo tra
startTimeeendTimenon deve superare le 12 ore in una singola richiesta API.
- Formatta l'ora come
- Max (facoltativo, numero): limita il numero massimo di record per pagina nella risposta. Assicurarsi che:
- L'intervallo è compreso tra 500 e 5000. Il valore predefinito è 5000. Per esempio,
Max=1000. - Se l'API ha più record da restituire rispetto al valore massimo specificato, la risposta viene suddivisa in pagine.
- Se viene specificato un valore inferiore a 500, questo viene automaticamente regolato fino a 500. Se viene specificato un valore superiore a 5000, questo viene ridotto a 5000.
- L'intervallo è compreso tra 500 e 5000. Il valore predefinito è 5000. Per esempio,
Impaginazione
Per verificare se le risposte API sono suddivise in pagine, controllare le intestazioni delle risposte per individuare un'intestazione Link. Se nell'intestazione Link è presente un collegamento next, estrarlo e utilizzare il valore startTimeForNextFetch per richiedere il set di record successivo. Se non è presente alcun collegamento successivo, vengono raccolti tutti i report per l'intervallo di tempo selezionato.
Le richieste API per le pagine successive possono essere effettuate immediatamente, ma la velocità deve essere limitata a un massimo di 10 richieste paginate al minuto, per ambito token.
Ad esempio, se la richiesta API iniziale è:
https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=2025-08-15T18:00:00.000Z&startTime=2025-08-15T06:00:00.000Z&Max=5000quindi l'intestazione del collegamento nella risposta è:
; rel="next"Altri possibili valori di collegamento includono rel="first" e rel="prev" rispettivamente per la prima e le pagine precedenti.
La paginazione per questa API segue lo standard RFC5988 (Web Linking). Per ulteriori informazioni, vedere Nozioni di base sull'API REST.
Partner reports/templates API
È possibile generare e scaricare i report disponibili in Partner Hub utilizzando le API Partner Reports. Per maggiori informazioni, consultare il partner report/templates.
I partner possono anche accedere e scaricare più report direttamente da Partner Hub. Per ulteriori informazioni, vedere Report di Partner Hub.
