En esta página, se explica cómo usar la paginación y el seguimiento cuando se llama a los extremos de la API de administrador.
Paginación
La paginación es compatible con la mayoría de los extremos de la API de administrador. Para ver las excepciones, consulta Sigue un extremo para obtener registros actualizados.
Establece el tamaño de la página
De forma predeterminada, los endpoints de API de administrador devuelven páginas que contienen 100 registros. Puedes
cambiar este número con el parámetro de consulta per, hasta un máximo de 100. Un valor mayor se reduce a 100.
Para establecer el tamaño de la página, usa el siguiente extremo:
/manager/api/v1/agents?per=50
Esto establece el tamaño de la página en 50 registros.
Solicita una página específica
Puedes solicitar una página específica de registros con el parámetro de consulta page.
Para solicitar una página específica, usa el siguiente extremo:
/manager/api/v1/agents?page=2
Esto devuelve la segunda página de registros.
Obtén todos los registros disponibles
De forma predeterminada, la API de administrador devuelve 100 registros en una página de respuesta, aunque puedes cambiar la cantidad de registros en una página estableciendo el tamaño de la página. En el caso de los extremos que admiten la paginación,
el encabezado de respuesta incluye la cantidad total de registros disponibles. Si ese
número supera el tamaño de la página, debes llamar a la API varias veces para obtener
todos los registros. Para los extremos que admiten la paginación, la respuesta
incluye un encabezado Link que sigue el RFC 5988. Hay un vínculo rel="next"
cuando hay más registros disponibles, y un vínculo rel="last" indica el número
de la página final. La respuesta también incluye los encabezados Total y Per-Page.
Para obtener todos los registros disponibles, haz lo siguiente:
Llama a un extremo de API de administrador que admita la paginación. Para obtener más información, consulta Paginación. El encabezado de respuesta indica cuántos registros hay para devolver.
Compara la cantidad de registros que se devolverán con el tamaño de la página. Si la cantidad de registros que se devolverán es menor que el tamaño de la página, se devolvieron todos los registros. De lo contrario, continúa con el paso siguiente.
Vuelve a llamar al extremo y especifica la siguiente página de registros. Para obtener más información, consulta Cómo solicitar una página específica. Repite este paso hasta que se muestren todos tus registros.
Sigue un extremo para obtener registros actualizados
Google recomienda no usar la paginación para los endpoints de API de llamada, chat y actividad del agente, ya que no podemos garantizar resultados óptimos. En su lugar, te recomendamos que sigas estos endpoints de API para obtener registros actualizados. Seguir un extremo de API significa llamarlo de forma continua para obtener registros nuevos o actualizados desde tu última solicitud.
Sigue el extremo de API de Calls
Cada vez que se modifica un registro de llamadas, se actualiza su marca de tiempo updated_at. Puedes usar la marca de tiempo para especificar los registros de llamadas que deseas recuperar cuando llames al extremo de API de Calls.
Para seguir el extremo de API de Calls cada 60 minutos, sigue estos pasos:
Realiza una solicitud al extremo de API de Calls (
/manager/api/v1/calls) y especifica los siguientes parámetros de consulta:updated_at[from]: Especifica que deseas obtener los registros que se actualizaron en esta hora o después de ella.sort_column: Especifica el campo por el que se ordenarán los registros.sort_direction: Especifica la dirección de ordenamiento de los registros en la respuesta.
A continuación, se muestra un ejemplo de secuencia de comandos de Bash que usa el 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" | jqLa API de Calls devuelve una respuesta similar a la siguiente:
[ { "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" } ]Se devuelven los objetos de respuesta actualizados en la marca de tiempo que especificaste o después de ella, ordenados por fecha, en orden ascendente. Usa la marca de tiempo
updated_atdel último objeto de esta respuesta para la marca de tiempo en tu próxima llamada al extremo. El filtrofromes inclusivo, por lo que la siguiente respuesta repite el registro en esa marca de tiempo. Anula la duplicación en el ID de registro o registra los IDs que ya se procesaron en esa marca de tiempo y omítelos.Llama al extremo de API de llamadas 60 minutos después. Se devuelven los registros de llamadas actualizados desde tu última solicitud.
Repite el paso anterior para seguir supervisando el extremo.
Sigue el extremo de API de Chats
Usa la marca de tiempo updated_at del último objeto de esta respuesta para la marca de tiempo de tu próxima llamada al extremo. El filtro updated_at[from] es inclusivo, por lo que la siguiente respuesta repite el registro en esa marca de tiempo. Anula la duplicación en el ID de registro o registra los IDs que ya se procesaron en esa marca de tiempo y omítelos.
Cada vez que se modifica un registro de chat, se actualiza su marca de tiempo updated_at. Puedes usar la marca de tiempo para especificar los registros de chat que deseas recuperar cuando llames al extremo de API de Chats.
Para seguir el extremo de API de Chats cada 60 minutos, sigue estos pasos:
Realiza una solicitud al extremo de API de Chats (
/manager/api/v1/chats) y especifica los siguientes parámetros de consulta:updated_at[from]: Especifica que deseas obtener los registros que se actualizaron en esta hora o después de ella.sort_column: Especifica el campo por el que se ordenarán los registros.sort_direction: Especifica la dirección de ordenamiento de los registros en la respuesta.
A continuación, se muestra un ejemplo de secuencia de comandos de Bash que usa el 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" | jqLa API de Chats devuelve una respuesta similar a la siguiente:
[ { "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" } ]Se devuelven los objetos de respuesta actualizados en la marca de tiempo especificada o después de ella, ordenados por fecha, en orden ascendente. Usa la marca de tiempo
updated_atdel último objeto de esta respuesta para la marca de tiempo en tu próxima llamada al extremo.Vuelve a llamar al extremo de API 60 minutos después. Se devuelven los registros de chat actualizados desde tu última solicitud.
Repite el paso anterior para seguir supervisando el extremo.
Sigue el extremo de API de Agent Activity
A diferencia de los registros de chat y llamadas, los registros de actividad de los agentes no se actualizan y,
por lo tanto, no tienen una marca de tiempo updated_at. Puedes usar la marca de tiempo started_at
para especificar los registros de actividad que deseas recuperar cuando llames
al extremo de API de Agent Activity. El filtro started_at[from] es inclusivo,
por lo que la siguiente respuesta repite el registro en esa marca de tiempo. Anula la duplicación en el ID de registro o registra los IDs que ya se procesaron en esa marca de tiempo y omítelos.
Para seguir el extremo de API de Agent Activity cada 60 minutos, sigue estos pasos:
Realiza una solicitud al extremo de API de Agent Activity (
/manager/api/v1/agent_activity_logs) y especifica los siguientes parámetros de consulta:started_at[from]. Especifica que quieres los registros de actividad que se iniciaron en esta hora o después.ended_at[from]: Especifica que deseas obtener los registros de actividad que finalizaron en este momento o después. Usa esta opción en lugar destarted_at[from]para capturar las sesiones que comenzaron antes de tu ventana, pero que finalizaron dentro de ella.page: Incluye este parámetro para que la respuesta devuelva encabezados de paginación. Sinpage, la respuesta se limita al tamaño de página predeterminado de 100 registros sin devolver los encabezadosLink,TotaloPer-Page.sort_column: Especifica el campo por el que se ordenarán los registros.sort_direction: Especifica la dirección de ordenamiento de los registros en la respuesta.
A continuación, se muestra un ejemplo de secuencia de comandos de Bash que usa el 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" | jqLa API de Agent Activity devuelve una respuesta similar a la siguiente:
[ { "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" } ]Se devuelven los objetos de respuesta que se iniciaron en la marca de tiempo especificada o después de ella, ordenados por fecha, en orden ascendente. Usa la marca de tiempo
started_atdel último objeto de esta respuesta para la marca de tiempo en tu próxima llamada al extremo.Vuelve a llamar al extremo de API de Agent Activity 60 minutos después. Se devuelven los registros actualizados del registro de actividad del agente desde tu última solicitud.
Repite el paso anterior para seguir supervisando el extremo.