Questa pagina spiega come utilizzare l'impaginazione e il tailing quando chiami gli endpoint dell'API di gestione.
Impaginazione
La paginazione è supportata per la maggior parte degli endpoint dell'API Manager. Per le eccezioni, consulta Monitoraggio di un endpoint per i record aggiornati.
Imposta le dimensioni della pagina
Per impostazione predefinita, gli endpoint API di gestione restituiscono pagine contenenti 100 record. Puoi modificare questo numero utilizzando il parametro di query per, fino a un massimo di 100. Un valore più alto viene ridotto a 100.
Per impostare le dimensioni della pagina, utilizza il seguente endpoint:
/manager/api/v1/agents?per=50
In questo modo, le dimensioni della pagina vengono impostate su 50 record.
Richiedi una pagina specifica
Puoi richiedere una pagina specifica di record utilizzando il parametro di query page.
Per richiedere una pagina specifica, utilizza il seguente endpoint:
/manager/api/v1/agents?page=2
Restituisce la seconda pagina di record
Recupera tutti i record disponibili
Per impostazione predefinita, l'API di gestione restituisce 100 record in una pagina di risposta, anche se puoi modificare il numero di record in una pagina impostando le dimensioni della pagina. Per gli endpoint che supportano l'impaginazione, l'intestazione della risposta include il numero totale di record disponibili. Se questo numero supera le dimensioni della pagina, devi chiamare l'API più volte per ottenere tutti i record. Per gli endpoint che supportano l'impaginazione, la risposta include un'intestazione Link conforme alla RFC 5988. Un link rel="next" è presente ogni volta che sono disponibili più record, mentre un link rel="last" indica il numero della pagina finale. La risposta include anche le intestazioni Total e Per-Page.
Per ottenere tutti i record disponibili:
Chiama un endpoint API di gestione che supporta l'impaginazione. Per ulteriori informazioni, vedi Impaginazione. L'intestazione della risposta indica il numero di record da restituire.
Confronta il numero di record da restituire con la dimensione della pagina. Se il numero di record da restituire è inferiore alle dimensioni della pagina, sono stati restituiti tutti i record. In caso contrario, vai al passaggio successivo.
Chiama di nuovo l'endpoint, specificando la pagina di record successiva. Per saperne di più, consulta Richiedi una pagina specifica. Ripeti questo passaggio finché non vengono restituiti tutti i record.
Monitora un endpoint per i record aggiornati
Google sconsiglia di utilizzare l'impaginazione per gli endpoint API call, chat e agent activity perché non possiamo garantire risultati ottimali. Ti consigliamo invece di monitorare questi endpoint API per i record aggiornati. Il tailing di un endpoint API consiste nel chiamarlo continuamente per ottenere i record nuovi o aggiornati dall'ultima richiesta.
Endpoint API Tail the Calls
Ogni volta che un record di chiamate viene modificato, il relativo timestamp updated_at viene aggiornato. Puoi
utilizzare il timestamp per specificare i record di chiamata che vuoi recuperare quando
chiami l'endpoint dell'API Calls.
Per monitorare l'endpoint dell'API Calls ogni 60 minuti, segui questi passaggi:
Invia una richiesta all'endpoint dell'API Calls (
/manager/api/v1/calls), specificando i seguenti parametri di ricerca:updated_at[from]. Specifica che vuoi i record aggiornati in questa data e ora o in un momento successivo.sort_column. Specifica il campo in base al quale ordinare i record.sort_direction. Specifica la direzione di ordinamento dei record nella risposta.
Di seguito è riportato uno script Bash di esempio che utilizza il comando
curl:# 1. Define your environment variables (usually set in your shell or .env file) export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/" export API_USER="ccaip-host" export API_PASS="CCAI Platform API Key" # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC) # For macOS (BSD date): # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ") # For Linux (GNU date): TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ") # 3. Execute the curl command # -u handles the Base64 encoding for Basic Auth automatically curl -g -u "${API_USER}:${API_PASS}" \ "https://${API_HOSTNAME}/manager/api/v1/calls?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jqL'API Calls restituisce una risposta simile alla seguente:
[ { "id": 100, ... "updated_at": "2025-01-01T00:00:00Z" }, { "id": 98, ... "updated_at": "2025-01-02T00:00:00Z" }, { "id": 150, ... "updated_at": "2025-01-03T00:00:00Z" } ]Vengono restituiti gli oggetti di risposta aggiornati alla data e ora specificate o successivamente, ordinati per data in ordine crescente. Utilizza il timestamp
updated_atdell'ultimo oggetto di questa risposta per il timestamp della chiamata successiva all'endpoint. Il filtrofromè inclusivo, quindi la risposta successiva ripete il record in quel timestamp. Deduplica in base all'ID record o registra gli ID già elaborati in quel timestamp e ignorali.Chiama l'endpoint API Call 60 minuti dopo. Vengono restituiti i record delle chiamate aggiornati dall'ultima richiesta.
Ripeti il passaggio precedente per continuare a monitorare l'endpoint.
Segui l'endpoint API Chats
Utilizza il timestamp updated_at dell'ultimo oggetto di questa risposta per il timestamp della chiamata successiva all'endpoint. Il filtro updated_at[from] è inclusivo, quindi la risposta successiva ripete il record in quel timestamp. Deduplica in base all'ID record o registra gli ID già elaborati in quel timestamp e ignorali.
Ogni volta che un record di chat viene modificato, il relativo timestamp updated_at viene aggiornato. Puoi
utilizzare il timestamp per specificare i record della chat che vuoi recuperare quando
chiami l'endpoint API Chats.
Per monitorare l'endpoint API Chats ogni 60 minuti, segui questi passaggi:
Invia una richiesta all'endpoint dell'API Chats (
/manager/api/v1/chats), specificando i seguenti parametri di ricerca:updated_at[from]. Specifica che vuoi i record aggiornati in questa data e ora o in un momento successivo.sort_column. Specifica il campo in base al quale ordinare i record.sort_direction. Specifica la direzione di ordinamento dei record nella risposta.
Di seguito è riportato uno script Bash di esempio che utilizza il comando
curl:# 1. Define your environment variables (usually set in your shell or .env file) export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/" export API_USER="ccaip-host" export API_PASS="CCAI Platform API Key" # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC) # For macOS (BSD date): # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ") # For Linux (GNU date): TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ") # 3.. Execute the curl command # -u handles the Base64 encoding for Basic Auth automatically curl -g -u "${API_USER}:${API_PASS}" \ "https://${API_HOSTNAME}/manager/api/v1/chats?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jqL'API Chats restituisce una risposta simile alla seguente:
[ { "id": 100, ... "updated_at": "2025-01-01T00:00:00Z" }, { "id": 98, ... "updated_at": "2025-01-02T00:00:00Z" }, { "id": 150, ... "updated_at": "2025-01-03T00:00:00Z" } ]Vengono restituiti gli oggetti di risposta aggiornati in corrispondenza o dopo il timestamp specificato, ordinati per data in ordine crescente. Utilizza il timestamp
updated_atdell'ultimo oggetto di questa risposta per il timestamp della chiamata successiva all'endpoint.Chiama di nuovo l'endpoint API 60 minuti dopo. Vengono restituiti i record della chat aggiornati dall'ultima richiesta.
Ripeti il passaggio precedente per continuare a monitorare l'endpoint.
Monitora l'endpoint API Agent Activity
A differenza dei record di chat e chiamate, i log delle attività degli agenti non vengono aggiornati e, pertanto, non hanno un timestamp updated_at. Puoi utilizzare il timestamp started_at per specificare i record delle attività che vuoi recuperare quando chiami l'endpoint API Agent Activity. Il filtro started_at[from] è inclusivo,
quindi la risposta successiva ripete il record in quel timestamp. Esegui la deduplicazione sull'ID record o registra gli ID già elaborati in quel timestamp e ignorali.
Per monitorare l'endpoint dell'API Agent Activity ogni 60 minuti, segui questi passaggi:
Effettua una richiesta all'endpoint dell'API Agent Activity (
/manager/api/v1/agent_activity_logs), specificando i seguenti parametri di ricerca:started_at[from]. Specifica che vuoi i log delle attività avviati in questa data e ora o in un momento successivo.ended_at[from]. Specifica che vuoi i log delle attività che sono terminate in questa data e ora o dopo. Utilizza questo valore anzichéstarted_at[from]per rilevare le sessioni iniziate prima della finestra, ma terminate al suo interno.page. Includi questo parametro in modo che la risposta restituisca le intestazioni di impaginazione. Senzapage, la risposta è limitata alla dimensione predefinita della pagina di 100 record senza restituire le intestazioniLink,TotaloPer-Page.sort_column. Specifica il campo in base al quale ordinare i record.sort_direction. Specifica la direzione di ordinamento dei record nella risposta.
Di seguito è riportato uno script Bash di esempio che utilizza il comando
curl:# 1. Define your environment variables (usually set in your shell or .env file) export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com" export API_USER="ccaip-host" export API_PASS="CCAI Platform API Key" # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC) # For macOS (BSD date): # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ") # For Linux (GNU date): TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ") # 3. Execute the curl command # -u handles the Base64 encoding for Basic Auth automatically curl -g -u "${API_USER}:${API_PASS}" \ "https://${API_HOSTNAME}/manager/api/v1/agent_activity_logs?started_at[from]=${TIMESTAMP}&sort_column=started_at&sort_direction=asc" | jqL'API Agent Activity restituisce una risposta simile alla seguente:
[ { "id": 100, ... "started_at": "2025-01-01T00:00:00Z" }, { "id": 98, ... "started_at": "2025-01-02T00:00:00Z" }, { "id": 150, ... "started_at": "2025-01-03T00:00:00Z" } ]Vengono restituiti gli oggetti di risposta avviati in corrispondenza o dopo il timestamp specificato, ordinati per data in ordine crescente. Utilizza il timestamp
started_atdell'ultimo oggetto di questa risposta per il timestamp della chiamata successiva all'endpoint.Chiama di nuovo l'endpoint API Agent Activity 60 minuti dopo. Vengono restituiti i record del log delle attività dell'agente aggiornati dalla tua ultima richiesta.
Ripeti il passaggio precedente per continuare a monitorare l'endpoint.