Paginación y seguimiento

En esta página, se explica cómo usar la paginación y el seguimiento cuando se llama a los extremos de la API del administrador.

Paginación

La paginación es compatible con la mayoría de los extremos de la API de administración. Para ver las excepciones, consulta Cómo seguir un extremo para obtener registros actualizados.

Cómo establecer el tamaño de la página

De forma predeterminada, los extremos de la API de Manager devuelven páginas que contienen 100 registros. Puedes cambiar este número con el parámetro de consulta per.

Para establecer el tamaño de las páginas, usa el siguiente endpoint:

/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 del administrador devuelve 100 registros en una página de respuesta, aunque puedes cambiar la cantidad de registros en una página configurando 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 tu página, deberás llamar a la API varias veces para obtener todos los registros. La API del administrador no indica explícitamente que hay registros adicionales para devolver.

Para obtener todos los registros disponibles, haz lo siguiente:

  1. 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 se deben devolver.

  2. Compara la cantidad de registros que se devolverán con el tamaño de página. Si la cantidad de registros que se devolverán es menor que el tamaño de la página, se habrán devuelto todos los registros. De lo contrario, continúa con el siguiente paso.

  3. Vuelve a llamar al endpoint 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.

Cómo seguir un extremo para obtener registros actualizados

Google no recomienda usar la paginación para los extremos de la API de llamadas, chats y actividad de agentes porque no podemos garantizar resultados óptimos. En su lugar, te recomendamos que sigas estos extremos de API para obtener registros actualizados. Hacer un seguimiento de un extremo de API significa llamarlo de forma continua para obtener registros nuevos o actualizados desde tu última solicitud.

Realiza un seguimiento del 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 llamas extremo de API de Calls.

Para hacer un seguimiento del extremo de API de Calls cada 60 minutos, sigue estos pasos:

  1. 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 registros que se actualizaron en esta fecha y hora o después.

    • 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.

    El siguiente es un ejemplo de secuencia de comandos 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" | jq

    La 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 fecha y hora que especificaste o después de esa fecha y hora, ordenados por fecha en orden ascendente. Usa la marca de tiempo updated_at del último objeto de esta respuesta para la marca de tiempo en tu próxima llamada al extremo.

  2. Llama extremo de API de Call 60 minutos después. Se devuelven los registros de llamadas actualizados desde tu última solicitud.

  3. Repite el paso anterior para seguir registrando el extremo.

Realiza un seguimiento del extremo de API de Chats

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 llamas extremo de API de Chats.

Para hacer un seguimiento del extremo de API de Chats cada 60 minutos, sigue estos pasos:

  1. 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 registros que se actualizaron en esta fecha y hora o después.

    • 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.

    El siguiente es un ejemplo de secuencia de comandos 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" | jq

    La 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 fecha y hora especificadas o después de ellas, ordenados por fecha en orden ascendente. Usa la marca de tiempo updated_at del último objeto de esta respuesta para la marca de tiempo en tu próxima llamada al extremo.

  2. Vuelve a llamar al extremo de API 60 minutos después. Se devuelven los registros de chat actualizados desde tu última solicitud.

  3. Repite el paso anterior para seguir registrando el extremo.

Cómo seguir el extremo de API de Agent Activity

A diferencia de los registros de chat y llamadas, los registros de actividad del agente 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 llamas extremo de API de Agent Activity.

Para hacer un seguimiento del extremo de API de Agent Activity cada 60 minutos, sigue estos pasos:

  1. 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 deseas registros de actividad que se iniciaron en esta fecha y hora o después.

    • 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.

    El siguiente es un ejemplo de secuencia de comandos 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" | jq

    La 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 fecha y hora especificadas o después de ellas, ordenados por fecha en orden ascendente. Usa la marca de tiempo started_at del último objeto de esta respuesta para la marca de tiempo en tu próxima llamada al extremo.

  2. Vuelve a llamar 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.

  3. Repite el paso anterior para seguir registrando el extremo.