Obtener la tasa de transferencia de un Agente a humano

Obtener el número de conversaciones de un agente, el número de conversaciones transferidas a humano y la tasa de transferencia a humano según el intervalo de tiempo; el método de cálculo es consistente con la consola «Agent Insights → Tasa de transferencia a humano».

Nota: se puede consultar un máximo de 92 días de datos; solo se cuentan los canales del espacio de desarrollo, el alcance estadístico se indica más abajo en «Criterios de estadística».

Método de solicitud

GET

Dirección de la llamada

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

Autenticación de la llamada

Usar 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 llamada debe ser miembro de la organización correspondiente a org_id y tener el permiso de «Ver uso» (Owner o administrador de la organización lo tienen por defecto), además de poder ver a ese Agente: Creador del agente, Owner de la organización, o miembros a los que se les haya otorgado permiso sobre ese Agente (o todos los Agentes).
• Utilizar la dirección del centro de datos donde se encuentra la organización, ${endpoint} se obtiene de Consultar lista de organizaciones devolviendo region (SG → sg, TH → th, JP → jp). Llamar a otro centro de datos retornará «No es miembro de esta organización».

Frecuencia de llamadas

• Cada clave de desarrollador puede llamar a esta interfaz hasta 60 veces por minuto.
• Cada llamada se contabiliza en el cupo por minuto de «API de estadísticas» del plan de la organización, compartido con llamadas de interfaz de estadísticas de Agent API Key.
• Los resultados de la consulta se almacenan en caché durante 10 minutos; se recomienda realizar la llamada una vez por hora.

Solicitud

Ejemplo de solicitud

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff?org_id=${org_id}&agent_id=${agent_id}&start_time=1788192000000&end_time=1790784000000' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

                    

Encabezado de la solicitud

Parámetros de la solicitud

Respuesta

Ejemplo de respuesta

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
        "timezone": "+08:00",
        "range_start_date": "2026-09-01",
        "range_end_date": "2026-09-29",
        "data_until": 1790665200000,
        "conversation_count": 1200,
        "handoff_conversation_count": 96,
        "handoff_rate": 0.0800
    }
}

                    

Respuesta exitosa

Respuesta fallida

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.

Criterios estadísticos

• Número de sesiones: el número de sesiones que han tenido conversaciones cada día, acumuladas por día; las sesiones que continúan a través de varios días se cuentan en cada día por separado.
• Número de sesiones transferidas a humano: de esas, el número de sesiones transferidas a un humano.
• Alcance estadístico: solo se cuentan los canales del espacio de desarrollo, incluyendo API, página compartida, incrustación web, componente de burbuja, LiveDesk y varios canales de mensajería instantánea y teléfono; no incluye el uso del Agente después de publicarse en el espacio de trabajo.
• Frecuencia de actualización: para las fechas con estadísticas diarias completadas, se leen las estadísticas diarias; el cálculo del día actual es en tiempo real. Las estadísticas diarias se generan después de la medianoche según la zona horaria de la organización; antes de la finalización de la generación, el día anterior también se calcula en tiempo real, sin que aparezca «ayer» con valor 0 después de la medianoche.
• Criterios de la parte en tiempo real: se cuentan según la última conversación de la sesión; las sesiones que continúan a través de varios días solo se cuentan una vez en la parte en tiempo real (en el día de la última conversación), lo que puede diferir ligeramente de las estadísticas diarias acumuladas por día.