> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inagent.inconcertcx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Historial de llamadas de un contacto
> Consulta los intentos de llamada de un contacto dentro de un lote.
Devuelve los intentos ya realizados sobre un contacto dentro del lote. Puedes localizarlo mediante su `identifier` externo o mediante el `contactId` interno.
Usa preferentemente `identifier` para relacionar la consulta con el registro de tu CRM u otro sistema de origen. Envía exactamente uno de los dos identificadores.
El parámetro `timezone` es opcional y determina la zona horaria de `occurredAt`. Si lo omites, las fechas se devuelven en UTC.
## Ejemplos de consulta
```bash identifier theme={null}
curl --request GET \
--url 'https://api.backend.inconcertcc.com/autocontact/api/v1/batches/bf3d6869-4809-4474-be09-ff1c0f9e0a3a/contacts/event-history?identifier=CLI-001&timezone=Europe%2FMadrid&limit=20&offset=0' \
--header 'apikey: TU_API_KEY'
```
```bash contactId theme={null}
curl --request GET \
--url 'https://api.backend.inconcertcc.com/autocontact/api/v1/batches/bf3d6869-4809-4474-be09-ff1c0f9e0a3a/contacts/event-history?contactId=7d2f8a1b-3c4e-4f50-9a6b-2c3d4e5f6a7b&limit=20&offset=0' \
--header 'apikey: TU_API_KEY'
```
```json Response theme={null}
{
"contact": {
"contactId": "7d2f8a1b-3c4e-4f50-9a6b-2c3d4e5f6a7b",
"identifier": "CLI-001"
},
"data": [
{
"batchId": "bf3d6869-4809-4474-be09-ff1c0f9e0a3a",
"contactId": "7d2f8a1b-3c4e-4f50-9a6b-2c3d4e5f6a7b",
"identifier": "CLI-001",
"name": "Juan Pérez",
"address": "5491155551234",
"result": "NO_ANSWER",
"resultDetail": "No contesta",
"attemptNumber": 1,
"occurredAt": "2026-09-21 10:41:43.000",
"channelId": "c1a2b3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"dialId": "d9e8f7a6-5b4c-4d3e-2f1a-0b9c8d7e6f5a"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0
},
"timezone": "Europe/Madrid"
}
```
Los campos sin datos se devuelven como `null`, no como cadenas vacías. Un contacto cargado que todavía no fue marcado devuelve `data` vacío y `pagination.total: 0`; esto no significa que el contacto no exista.
`occurredAt` utiliza el formato `YYYY-MM-DD HH:mm:ss.SSS` y no incluye un offset. Interprétalo junto con el campo `timezone` de la respuesta. Evita pasarlo directamente a `new Date(occurredAt)`, porque JavaScript usaría la zona horaria del cliente, que puede ser distinta de la solicitada.
Consulta [Códigos de resultado](./contact-result-codes) para interpretar `result`.
## OpenAPI
````yaml api-reference/dialer/openapi.yaml GET /batches/{batchId}/contacts/event-history
openapi: 3.1.0
info:
title: AutoContact API
version: final
summary: Gestión de lotes de marcación automática y carga de contactos.
description: >
API de AutoContact: gestión de lotes de marcación automática y de los
contactos que los integran.
Todos los recursos se publican bajo `/autocontact/api/v1/`.
## Autenticación
Las peticiones se autentican con el header `apikey`. La misma credencial
permite operar los lotes
de la cuenta a los que tenga acceso. El servicio deriva la cuenta de esa
credencial y verifica que
el recurso solicitado le pertenezca.
Un lote que no pertenece a la cuenta responde `404`, igual que un lote
inexistente.
## Operaciones asíncronas
Algunas operaciones responden `202` en lugar de `200`: la petición se acepta
y el trabajo continúa
en segundo plano. Es el caso de la carga de contactos, el arranque y la
eliminación de un lote.
Esas respuestas incluyen un `operationId` que se consulta en
`GET /batches/operations/{operationId}` para conocer el resultado.
`POST /batches` no genera una operación: devuelve directamente el `batchId`,
el estado `created` y
el origen del lote, sin `operationId`.
Tiempo de retención de las operaciones:
| Tipo de operación | Disponible durante |
|---|---|
| Carga de contactos | 6 horas |
| Ciclo de vida del lote (arranque, archivado, eliminación) | 1 hora, y 10
minutos desde que finaliza |
## Reintentos seguros con `Idempotency-Key`
Las operaciones de escritura aceptan el header opcional `Idempotency-Key`.
Resuelve el caso en que
se produce un error de red después de que la petición llegó al servicio: sin
este header no es
posible determinar si el trabajo se procesó, y reintentar podría duplicar
llamadas telefónicas.
Con el header, un reintento que use la misma clave y el mismo cuerpo
devuelve la respuesta original
sin procesar nada de nuevo. Las claves se conservan 24 horas.
Recomendación de uso: generar un identificador único (por ejemplo un UUID)
antes del primer intento
y reutilizarlo solo en los reintentos de esa misma operación.
Requisitos de la clave: entre 1 y 255 caracteres, solo ASCII imprimible. Una
clave que no cumpla
estos requisitos se rechaza con `400 INVALID_IDEMPOTENCY_KEY` en lugar de
ignorarse, para evitar
procesar la petición sin la protección que el cliente espera tener.
### Headers de respuesta
| Header | Cuándo aparece | Significado |
|---|---|---|
| `Idempotency-Replayed: true` | En un reintento | La respuesta corresponde
a la petición original; no se procesó de nuevo |
| `Retry-After` | Junto a `409 IDEMPOTENCY_KEY_IN_FLIGHT` | Segundos a
esperar antes de reintentar |
| `Idempotency-Status: bypassed` | Excepcionalmente | La petición se procesó
**sin** protección de idempotencia |
El header `Idempotency-Status: bypassed` indica que el servicio de
idempotencia no estaba
disponible y la petición se procesó igualmente, para no interrumpir la
operación. La respuesta es
válida, pero esa petición concreta no quedó protegida: si no se recibe
respuesta, se recomienda
verificar el estado antes de reintentar.
Las respuestas con error `5xx` no se almacenan, de modo que un reintento con
la misma clave vuelve a
procesar la petición.
servers:
- url: https://api.backend.inconcertcc.com/autocontact/api/v1
description: API de Inagent
security:
- ApiKeyAuth: []
tags:
- name: Lotes
description: |
Creación, consulta y control de lotes de marcación.
- name: Contactos
description: |
Carga de contactos en un lote, reagendamiento y anulación.
- name: Direcciones bloqueadas
description: |
Direcciones excluidas de la marcación en toda la cuenta.
- name: Operaciones
description: |
Seguimiento de las operaciones asíncronas que devuelven `202`.
paths:
/batches/{batchId}/contacts/event-history:
parameters:
- $ref: '#/components/parameters/BatchId'
get:
tags:
- Contactos
summary: Consulta el historial de intentos de un contacto
description: >
Devuelve únicamente los intentos ya ejecutados sobre un contacto dentro
del lote. Un contacto
cargado que todavía no fue marcado devuelve `data` vacío y
`pagination.total: 0`; esto no
significa que el contacto no exista.
El contacto se puede localizar mediante su `identifier` externo o
mediante el `contactId`
interno. Debe enviarse exactamente uno de los dos parámetros. Para
integraciones con un CRM u
otro sistema de origen, se recomienda utilizar `identifier`.
`timezone` determina la zona horaria de `occurredAt`. Si se omite, las
fechas se devuelven en
UTC. `occurredAt` tiene el formato `YYYY-MM-DD HH:mm:ss.SSS` y no
incluye un offset; debe
interpretarse junto con el campo `timezone` de la respuesta. Los campos
sin datos se devuelven
como `null`, no como cadenas vacías.
operationId: getContactEventHistory
parameters:
- name: identifier
in: query
required: false
schema:
type: string
description: Identificador del contacto en el sistema de origen. Recomendado.
example: CLI-001
- name: contactId
in: query
required: false
schema:
type: string
format: uuid
description: Identificador interno asignado por Inagent al importar el contacto.
- name: timezone
in: query
required: false
schema:
type: string
default: UTC
description: Zona horaria IANA utilizada para expresar `occurredAt`.
example: Europe/Madrid
- name: limit
in: query
required: false
schema:
type: integer
description: Cantidad máxima de intentos que se devolverán.
example: 20
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Desplazamiento desde el primer intento.
example: 0
responses:
'200':
description: Historial de intentos del contacto.
content:
application/json:
schema:
type: object
required:
- contact
- data
- pagination
- timezone
properties:
contact:
type: object
required:
- contactId
- identifier
properties:
contactId:
type: string
format: uuid
identifier:
type: string
data:
type: array
items:
type: object
required:
- batchId
- contactId
- identifier
- name
- address
- result
- resultDetail
- attemptNumber
- occurredAt
- channelId
- dialId
properties:
batchId:
type: string
format: uuid
contactId:
type: string
format: uuid
identifier:
type: string
name:
type:
- string
- 'null'
address:
type:
- string
- 'null'
result:
type:
- string
- 'null'
resultDetail:
type:
- string
- 'null'
attemptNumber:
type: integer
occurredAt:
type: string
description: >-
Fecha y hora en la zona indicada por `timezone`, sin
sufijo de zona.
example: '2026-09-21 10:41:43.000'
channelId:
type:
- string
- 'null'
format: uuid
dialId:
type:
- string
- 'null'
format: uuid
pagination:
type: object
required:
- total
- limit
- offset
properties:
total:
type: integer
limit:
type: integer
offset:
type: integer
timezone:
type: string
example:
contact:
contactId: 7d2f8a1b-3c4e-4f50-9a6b-2c3d4e5f6a7b
identifier: CLI-001
data:
- batchId: bf3d6869-4809-4474-be09-ff1c0f9e0a3a
contactId: 7d2f8a1b-3c4e-4f50-9a6b-2c3d4e5f6a7b
identifier: CLI-001
name: Juan Pérez
address: '5491155551234'
result: NO_ANSWER
resultDetail: No contesta
attemptNumber: 1
occurredAt: '2026-09-21 10:41:43.000'
channelId: c1a2b3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
dialId: d9e8f7a6-5b4c-4d3e-2f1a-0b9c8d7e6f5a
pagination:
total: 1
limit: 20
offset: 0
timezone: Europe/Madrid
components:
parameters:
BatchId:
name: batchId
in: path
required: true
schema:
type: string
format: uuid
description: Id del lote.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: apikey
description: API key obtenida desde la interfaz de Inagent, dentro del marcador.
````