Paginação e rastreamento

Nesta página, explicamos como usar a paginação e o tailing 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 Como acompanhar um endpoint para registros atualizados.

Definir o tamanho da página

Por padrão, os endpoints de API Manager retornam páginas com 100 registros. É possível alterar esse número usando o parâmetro de consulta per, até um máximo de 100. Um valor maior é reduzido para 100.

Para definir o tamanho da página, 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 alterar o número de registros em uma página definindo o tamanho da página. Para os endpoints que aceitam 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. Para endpoints que aceitam paginação, a resposta inclui um cabeçalho Link de acordo com a RFC 5988. Um link rel="next" está presente sempre que mais registros estão disponíveis, e um link rel="last" fornece o número da página final. A resposta também inclui os cabeçalhos Total e Per-Page.

Para acessar 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 há para retornar.

  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 serão retornados. Caso contrário, prossiga 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.

Monitorar um endpoint para registros atualizados

O Google não recomenda o uso de paginação para os endpoints de API de chamada, chat e atividade do agente, porque não podemos garantir resultados ideais. Em vez disso, recomendamos acompanhar esses endpoints de API para registros atualizados. Seguir 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. Você pode usar o carimbo de data/hora para especificar os registros de chamadas que 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 ao 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 nesse horário ou depois dele.

    • sort_column. Especifique o campo para classificar os registros.

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

    Veja 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 no carimbo de data/hora especificado ou depois dele 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. O filtro from é inclusivo, então a próxima resposta repete o registro nesse carimbo de data/hora. Elimine a duplicação no ID do registro ou registre os IDs já processados nesse carimbo de data/hora e pule-os.

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

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

Acompanhar o endpoint de API Chats

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. O filtro updated_at[from] é inclusivo, então a próxima resposta repete o registro nesse carimbo de data/hora. Elimine a duplicação no ID do registro ou registre os IDs já processados nesse carimbo de data/hora e pule-os.

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 ao 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 nesse horário ou depois dele.

    • sort_column. Especifique o campo para classificar os registros.

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

    Veja 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 e hora especificadas ou depois delas 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 sua ú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. Use 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. O filtro started_at[from] é inclusivo, então a próxima resposta repete o registro nesse carimbo de data/hora. Elimine a duplicação no ID do registro ou registre os IDs já processados nesse carimbo de data/hora e pule-os.

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

  1. Faça uma solicitação ao 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 atividades que foram iniciados nessa data e hora ou depois.

    • ended_at[from]. Especifique que você quer registros de atividades que terminaram nesse horário ou depois dele. Use essa opção em vez de started_at[from] para capturar sessões que começaram antes da janela, mas terminaram dentro dela.

    • page. Inclua esse parâmetro para que a resposta retorne cabeçalhos de paginação. Sem page, a resposta é limitada ao tamanho de página padrão de 100 registros sem retornar os cabeçalhos Link, Total ou Per-Page.

    • sort_column. Especifique o campo para classificar os registros.

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

    Veja 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 e hora especificadas ou depois 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 atualizados do registro de atividades do agente desde sua última solicitação são retornados.

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