Llamadas · API de Totem

Resumen

Una llamada son los metadatos de una llamada telefónica, o de una sesión de voz web, vinculada a un lead: su dirección (direction), cuándo empezó, cuánto duró y cómo terminó. Las grabaciones, las transcripciones y los resúmenes nunca se exportan. El nombre y el número de quien llama viajan en el lead vinculado, no en la llamada.

outcome indica cómo terminó la llamada: answered_human, answered_ai, voicemail, no_answer, busy, failed o unknown cuando la llamada sigue en curso o nada indica quién respondió. Léelo junto con outcome_basis, que indica la prueba en la que se basa:

`outcome_basis`	El resultado se basa en
`inbound_verdict`	La clasificación de Totem de una llamada entrante.
`ai_analysis`	La clasificación que hace Totem del estado, el motivo de fin y la duración que informa Retell.
`duration_floor`	La duración de una llamada en una línea atendida por personas: una de al menos 10 segundos cuenta como respondida.
`carrier_answer_only`	Solo la señal de respuesta del operador de telefonía. Nunca cuenta como respondida, así que una llamada conectada se lee `unknown`.
`browser_session`	Una sesión de voz web con el asistente.
`none`	Ninguna prueba.

La base depende de cómo se hizo la llamada. Las entrantes en las líneas de teléfono de Totem tienen inbound_verdict, o carrier_answer_only si Totem no las ha clasificado. Todas las salientes en las líneas de teléfono de Totem, las haga la IA o una persona, tienen carrier_answer_only, así que una saliente conectada es unknown. Las llamadas atendidas a través de la plataforma de voz Retell tienen ai_analysis, y las de una centralita Zadarma conectada, duration_floor. Una sesión de voz web tiene browser_session, y una llamada que sigue en curso, none. El last_answered_call_at de un lead solo cuenta answered_human y answered_ai, así que no tiene en cuenta las salientes conectadas en las líneas de teléfono de Totem.

duration_seconds se redondea a la baja en segundos enteros y es null mientras la llamada sigue en curso. lead es null cuando la llamada no está vinculada a ningún lead o cuando el lead ya no existe.

Usa GET /v1/calls y GET /v1/calls/{id} para consultar llamadas; GET /v1/calls?lead= lista las llamadas de un lead. Para mantener una copia, sigue el feed de cambios, que entrega cada llamada nueva y cada cambio: lo explica Sincroniza una copia.

Lista las llamadas

GET /v1/calls

Devuelve una página de llamadas del equipo, cada una con su dirección, su hora de inicio, su duración y un resultado normalizado, y vinculada a su lead cuando lo hay. Envía lead para obtener las llamadas de un lead. Las grabaciones y las transcripciones no se exportan.

Permisos: calls:read
Límite de frecuencia: Sincronización

Parámetros de consulta

limit integer Rango 1–100 Por defecto 25
Elementos por página, de 1 a 100. Por defecto, 25.
cursor string 1–512 caracteres
El next_cursor de la página anterior. Omítelo en la primera página.
lead string Prefijo del id lead_…
Solo las llamadas vinculadas a este lead: el lead de cada elemento es este identificador. Un lead de otro equipo, o que no existe, no coincide con nada.

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos Call.

object string
Siempre list.
data Array<Call>
Los elementos de esta página.
has_more boolean
true si hay otra página: pídela con next_cursor, aunque esta traiga menos elementos que limit.
next_cursor string Puede ser null
Cursor opaco de la página siguiente, o null en la última. No lo interpretes.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 capture_not_ready Los datos del equipo aún se están preparando
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/calls?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "id": "call_m2kUbFcayHlZ5Lgs9xZNmDS3c3Jvk",
      "object": "call",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "direction": "inbound",
      "started_at": "2026-09-28T10:17:00.000Z",
      "duration_seconds": 184,
      "outcome": "answered_ai",
      "outcome_basis": "inbound_verdict",
      "version": 2,
      "updated_at": "2026-09-28T10:21:04.010Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Obtén una llamada

GET /v1/calls/{id}

Devuelve una llamada por su identificador. Una llamada que esta clave no puede leer, o que se eliminó, responde 404 resource_missing.

Permisos: calls:read
Límite de frecuencia: Lectura

Parámetros de ruta

id string Obligatorio Prefijo del id call_…
El identificador público de la llamada.

Respuesta

Devuelve un objeto Call.

id string Prefijo del id call_…
Identificador público del registro.
object string
Siempre call.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
lead string Puede ser null Prefijo del id lead_…
El lead al que está vinculada la llamada, o null si no está vinculada o el lead ya no existe. El nombre y el teléfono solo aparecen en el lead.
direction string Puede ser null
inbound o outbound; null si no está guardada.
Valores posibles
- inbound
- outbound
started_at string Puede ser null Formato date-time
Cuándo empezó la llamada (UTC), o cuándo se registró si el proveedor no dio hora de inicio.
duration_seconds integer Puede ser null Rango ≥ 0
Segundos enteros de la llamada (redondeados hacia abajo); null mientras la llamada sigue en curso, o si no están guardados.
outcome string
Cómo terminó la llamada: answered_human, answered_ai, voicemail, no_answer, busy, failed o unknown (aún en curso, o sin pruebas de quién contestó). Léelo junto con outcome_basis.
Valores posibles
- answered_human
- answered_ai
- voicemail
- no_answer
- busy
- failed
- unknown
outcome_basis string
La prueba detrás de outcome: inbound_verdict (la clasificación de Totem de una llamada entrante en sus líneas de teléfono), ai_analysis (la clasificación que hace Totem del estado, el motivo de fin y la duración que informa Retell), duration_floor (una llamada en una centralita Zadarma conectada, donde al menos 10 segundos cuentan como contestada), carrier_answer_only (solo la señal de respuesta del operador, que nunca cuenta como contestada, así que una llamada conectada es unknown: todas las salientes en las líneas de Totem, las haga la IA o una persona, y una entrante que Totem no ha clasificado), browser_session (una sesión de voz web con el asistente) o none (ninguna prueba, como en una llamada que sigue en curso).
Valores posibles
- inbound_verdict
- ai_analysis
- duration_floor
- carrier_answer_only
- browser_session
- none
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

Errores

403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 resource_missing Recurso no encontrado
409 capture_not_ready Los datos del equipo aún se están preparando

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/calls/call_m2kUbFcayHlZ5Lgs9xZNmDS3c3Jvk' \
  -H "Authorization: Bearer $TOTEM_API_KEY"

{
  "id": "call_m2kUbFcayHlZ5Lgs9xZNmDS3c3Jvk",
  "object": "call",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "direction": "inbound",
  "started_at": "2026-09-28T10:17:00.000Z",
  "duration_seconds": 184,
  "outcome": "answered_ai",
  "outcome_basis": "inbound_verdict",
  "version": 2,
  "updated_at": "2026-09-28T10:21:04.010Z"
}

El objeto `Call`

Una llamada: su dirección, su horario y un resultado normalizado. Sin grabación ni transcripción.

Atributos

id string Prefijo del id call_…
Identificador público del registro.
object string
Siempre call.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
lead string Puede ser null Prefijo del id lead_…
El lead al que está vinculada la llamada, o null si no está vinculada o el lead ya no existe. El nombre y el teléfono solo aparecen en el lead.
direction string Puede ser null
inbound o outbound; null si no está guardada.
Valores posibles
- inbound
- outbound
started_at string Puede ser null Formato date-time
Cuándo empezó la llamada (UTC), o cuándo se registró si el proveedor no dio hora de inicio.
duration_seconds integer Puede ser null Rango ≥ 0
Segundos enteros de la llamada (redondeados hacia abajo); null mientras la llamada sigue en curso, o si no están guardados.
outcome string
Cómo terminó la llamada: answered_human, answered_ai, voicemail, no_answer, busy, failed o unknown (aún en curso, o sin pruebas de quién contestó). Léelo junto con outcome_basis.
Valores posibles
- answered_human
- answered_ai
- voicemail
- no_answer
- busy
- failed
- unknown
outcome_basis string
La prueba detrás de outcome: inbound_verdict (la clasificación de Totem de una llamada entrante en sus líneas de teléfono), ai_analysis (la clasificación que hace Totem del estado, el motivo de fin y la duración que informa Retell), duration_floor (una llamada en una centralita Zadarma conectada, donde al menos 10 segundos cuentan como contestada), carrier_answer_only (solo la señal de respuesta del operador, que nunca cuenta como contestada, así que una llamada conectada es unknown: todas las salientes en las líneas de Totem, las haga la IA o una persona, y una entrante que Totem no ha clasificado), browser_session (una sesión de voz web con el asistente) o none (ninguna prueba, como en una llamada que sigue en curso).
Valores posibles
- inbound_verdict
- ai_analysis
- duration_floor
- carrier_answer_only
- browser_session
- none
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

{
  "id": "call_m2kUbFcayHlZ5Lgs9xZNmDS3c3Jvk",
  "object": "call",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "direction": "inbound",
  "started_at": "2026-09-28T10:17:00.000Z",
  "duration_seconds": 184,
  "outcome": "answered_ai",
  "outcome_basis": "inbound_verdict",
  "version": 2,
  "updated_at": "2026-09-28T10:21:04.010Z"
}

Resumen

Parámetros de consulta

Cabeceras

Respuesta

Errores

Parámetros de ruta

Respuesta

Errores

El objeto Call

Atributos

El objeto `Call`