Obtener la actividad reciente de un Agente

Obtén el número de nuevas sesiones y preguntas de usuarios de uno o varios Agentes en los últimos N minutos, adecuado para verificar actividad periódicamente. Se pueden consultar hasta 50 Agentes a la vez.

Método de solicitud

GET

URL de la solicitud

https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity

Verificación de la solicitud

Usa la autenticación Basic con DevKey / DevSecret a nivel de cuenta: Authorization: Basic ${BASIC_TOKEN}, donde ${BASIC_TOKEN} es la codificación Base64 de DevKey:DevSecret.

La cuenta que realiza la solicitud debe ser miembro de la organización correspondiente a org_id y tener permisos de «ver uso» (por defecto los Owners y administradores de la organización los tienen), además de poder ver el Agente: creador del Agente, Owner de la organización, o miembros a los que se haya concedido permiso sobre ese Agente (o todos los Agentes).
Debe llamar a la dirección del centro de datos donde se encuentra la organización, ${endpoint} se obtiene del region devuelto por Consultar la lista de organizaciones (SG → sg, TH → th, JP → jp). Si se llama a otro centro de datos, devolverá «no es miembro de esta organización».

Frecuencia de llamadas

Cada clave de desarrollador puede llamar a esta API hasta 60 veces por minuto.
Cada llamada cuenta para el límite por minuto de «API de estadísticas» del paquete de la organización, compartido con las llamadas usando la API Key del Agente a interfaces de estadísticas.
Los resultados de la consulta se almacenan en caché durante 30 segundos; se recomienda llamar una vez por minuto y combinar varios Agentes en una sola solicitud.

Solicitud

Ejemplo de solicitud

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \ -H 'Authorization: Basic ${BASIC_TOKEN}'

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/recent-activity?org_id=${org_id}&agent_id=${agent_id_1},${agent_id_2}&minutes=5' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

Este bloque de código en una ventana flotante

Encabezado de la solicitud

Campo	Tipo	Descripción
Authorization	Basic ${BASIC_TOKEN}	Usar el Token Básico después de codificar `DevKey:DevSecret` en Base64.

Parámetros de la solicitud

Campo	Tipo	Obligatorio	Descripción
org_id	String	Sí	ID de la organización.
agent_id	String	Sí	ID del Agente, múltiples separados por comas en inglés, hasta 50, los repetidos solo se cuentan una vez. No soporta Workflow.
minutes	Integer	No	Estadísticas de los últimos minutos, de 1 a 60, por defecto 5.

Respuesta

Ejemplo de respuesta

{ "code": 0, "message": "OK", "data": { "minutes": 5, "window_start": 1790664900000, "window_end": 1790665200000, "agents": [ { "agent_id": "65f0c2a1b4e8d93a1c7e5b21", "new_conversation_count": 3, "new_message_count": 27 } ] } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "minutes": 5,
        "window_start": 1790664900000,
        "window_end": 1790665200000,
        "agents": [
            {
                "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
                "new_conversation_count": 3,
                "new_message_count": 27
            }
        ]
    }
}

Este bloque de código en una ventana flotante

Respuesta exitosa

Campo	Tipo	Descripción
minutes	Integer	Longitud de la ventana de estadísticas (minutos).
window_start	Long	Inicio de la ventana (marca de tiempo en milisegundos).
window_end	Long	Fin de la ventana (marca de tiempo en milisegundos, no inclusivo).
agents[].agent_id	String	ID del agente, el orden coincide con `agent_id` en la solicitud.
agents[].new_conversation_count	Long	Número de sesiones nuevas dentro de la ventana que ya han tenido conversaciones.
agents[].new_message_count	Long	Número de preguntas enviadas por el usuario dentro de la ventana, sin incluir respuestas de IA.

Respuesta fallida

Campo	Tipo	Descripción
code	Integer	Código de error.
message	String	Detalles del error.

Códigos de error

El código de estado HTTP corresponde a los tres primeros dígitos del código de error, por ejemplo, 40000 corresponde a 400, 40100 corresponde a 401, 403132 corresponde a 403.

Código de error	Descripción
40000	Error de parámetro, como falta de parámetros obligatorios o valores de parámetros no válidos.
40001	Llamadas demasiado frecuentes: esta clave de desarrollador ha superado el límite por minuto de esta interfaz.
40008	Se ha superado el límite por minuto de la "API de estadísticas" del paquete de la organización.
40010	Interfaz temporalmente cerrada, por favor intente más tarde.
40100	Sin permiso: falta permiso para ver el uso o sin derecho a ver este Agente (incluyendo agentes que no pertenecen a la organización).
40105	No es miembro de la organización o se ha llamado a la dirección de otro centro de datos.
40324	DevKey o DevSecret incorrecto.
40378	Agente eliminado.
403132	Rango de tiempo inválido: la hora de inicio no es anterior a la hora de finalización, o excede el rango máximo de consulta.

Criterios de estadística

Se deben considerar ambos números: Las conversaciones en canales de mensajería instantánea continuarán con la misma sesión si no hay nuevos mensajes dentro de 60 minutos; un agente activo del canal también puede no tener nuevas conversaciones durante mucho tiempo, por lo que solo ver el número de nuevas conversaciones podría interpretarse erróneamente como inactividad.
Alcance de la estadística: Solo se estadístican los canales del espacio de desarrollo, incluyendo API, páginas para compartir, incrustaciones en la web, componentes de burbuja, LiveDesk, así como todos los canales de mensajería instantánea y telefonía; no se incluyen las vistas previas de depuración en el espacio de desarrollo ni el uso de ese agente en el espacio de trabajo.
Frecuencia de actualización: Cálculo en tiempo real.