Paginação e rastreamento

Esta página explica como usar a paginação e o acompanhamento ao chamar os endpoints da API Manager.

Paginação

A paginação é compatível com a maioria dos endpoints da API Manager. Para exceções, consulte Acompanhar um endpoint para registros atualizados.

Definir o tamanho da página

Por padrão, os endpoints da API Manager retornam páginas que contêm 100 registros. É possível mudar esse número usando o parâmetro de consulta per.

Para definir o tamanho das páginas, use o seguinte endpoint:

/manager/api/v1/agents?per=50

Isso define o tamanho da página como 50 registros.

Solicitar uma página específica

É possível solicitar uma página específica de registros usando o parâmetro de consulta page.

Para solicitar uma página específica, use o seguinte endpoint:

/manager/api/v1/agents?page=2

Isso retorna a segunda página de registros.

Receber todos os registros disponíveis

Por padrão, a API Manager retorna 100 registros em uma página de resposta, mas é possível mudar o número de registros em uma página definindo o tamanho dela. Para os endpoints que oferecem suporte à paginação, o cabeçalho de resposta inclui o número total de registros disponíveis. Se esse número exceder o tamanho da página, será necessário chamar a API várias vezes para receber todos os registros. A API Manager não indica explicitamente que há outros registros a serem retornados.

Para receber todos os registros disponíveis, faça o seguinte:

1. Chame um endpoint de API Manager que ofereça suporte à paginação. Para mais informações, consulte Paginação. O cabeçalho de resposta indica quantos registros serão retornados.

2. Compare o número de registros a serem retornados com o tamanho da página. Se o número de registros a serem retornados for menor que o tamanho da página, todos os registros terão sido retornados. Caso contrário, continue para a próxima etapa.

3. Chame o endpoint novamente, especificando a próxima página de registros. Para mais informações, consulte Solicitar uma página específica. Repita essa etapa até que todos os registros sejam retornados.

Acompanhar um endpoint para registros atualizados

O Google não recomenda o uso da paginação para os endpoints de API de atividade de chamada, chat, e agente porque não podemos garantir resultados ideais. Em vez disso, recomendamos acompanhar esses endpoints de API para registros atualizados. Acompanhar um endpoint de API significa chamá-lo continuamente para receber registros novos ou atualizados desde a última solicitação.

Acompanhar o endpoint de API Calls

Sempre que um registro de chamadas é modificado, o carimbo de data/hora updated_at é atualizado. É possível usar o carimbo de data/hora para especificar os registros de chamadas que você quer recuperar ao chamar o endpoint de API Calls.

Para acompanhar o endpoint de API Calls a cada 60 minutos, siga estas etapas:

1. Faça uma solicitação para o endpoint de API Calls (/manager/api/v1/calls), especificando os seguintes parâmetros de consulta:

   • updated_at[from]. Especifique que você quer registros que foram atualizados nessa data ou depois dela.

   • sort_column. Especifique o campo para classificar os registros.

   • sort_direction. Especifique a direção de classificação dos registros na resposta.

   Confira a seguir um exemplo de script Bash que usa o 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
   

   A API Calls retorna uma resposta semelhante a esta:

     [
       {
         "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"
       }
     ]
   

   Os objetos de resposta atualizados na data especificada ou depois dela são retornados, classificados por data, em ordem crescente. Use o carimbo de data/hora updated_at do último objeto nessa resposta para o carimbo de data/hora na próxima chamada para o endpoint.

2. Chame o endpoint de API Call 60 minutos depois. Os registros de chamadas atualizados desde a última solicitação são retornados.

3. Repita a etapa anterior para continuar acompanhando o endpoint.

Acompanhar o endpoint de API Chats

Sempre que um registro de chat é modificado, o carimbo de data/hora updated_at é atualizado. É possível usar o carimbo de data/hora para especificar os registros de chat que você quer recuperar ao chamar o endpoint de API Chats.

Para acompanhar o endpoint de API Chats a cada 60 minutos, siga estas etapas:

1. Faça uma solicitação para o endpoint de API Chats (/manager/api/v1/chats), especificando os seguintes parâmetros de consulta:

   • updated_at[from]. Especifique que você quer registros que foram atualizados nessa data ou depois dela.

   • sort_column. Especifique o campo para classificar os registros.

   • sort_direction. Especifique a direção de classificação dos registros na resposta.

   Confira a seguir um exemplo de script Bash que usa o 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
   

   A API Chats retorna uma resposta semelhante a esta:

   [
     {
       "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"
     }
   ]
   

   Os objetos de resposta atualizados na data especificada ou depois dela são retornados, classificados por data, em ordem crescente. Use o carimbo de data/hora updated_at do último objeto nessa resposta para o carimbo de data/hora na próxima chamada para o endpoint.

2. Chame o endpoint de API novamente 60 minutos depois. Os registros de chat atualizados desde a última solicitação são retornados.

3. Repita a etapa anterior para continuar acompanhando o endpoint.

Acompanhar o endpoint de API Agent Activity

Ao contrário dos registros de chat e chamada, os registros de atividade do agente não são atualizados e, portanto, não têm um carimbo de data/hora updated_at. É possível usar o carimbo de data/hora started_at para especificar os registros de atividade que você quer recuperar ao chamar o endpoint de API Agent Activity.

Para acompanhar o endpoint de API Agent Activity a cada 60 minutos, siga estas etapas:

1. Faça uma solicitação para o endpoint de API Agent Activity (/manager/api/v1/agent_activity_logs), especificando os seguintes parâmetros de consulta:

   • started_at[from]. Especifique que você quer registros de atividade que foram iniciados nessa data ou depois dela.

   • sort_column. Especifique o campo para classificar os registros.

   • sort_direction. Especifique a direção de classificação dos registros na resposta.

   Confira a seguir um exemplo de script Bash que usa o 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
   

   A API Agent Activity retorna uma resposta semelhante a esta:

   [
     {
       "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"
     }
   ]
   

   Os objetos de resposta iniciados na data especificada ou depois dela são retornados, classificados por data, em ordem crescente. Use o carimbo de data/hora started_at do último objeto nessa resposta para o carimbo de data/hora na próxima chamada para o endpoint.

2. Chame o endpoint de API Agent Activity novamente 60 minutos depois. Os registros de atividade do agente atualizados desde a última solicitação são retornados.

3. Repita a etapa anterior para continuar acompanhando o endpoint.