Interactions API

Esta API permite consultar y obtener datos de interacciones de uContact. A través de sus endpoints, es posible obtener listados paginados de interacciones filtrados por rango de fechas o identificador de cliente, y recuperar el detalle completo de una interacción específica.

Obtener interacciones

Este endpoint retorna una lista paginada con un resumen de las interacciones.

Método: GET
URL: https://<dominio>.ucontactcloud.com/api/interactions

Descripción general

Retorna una lista paginada de resúmenes de interacciones filtrada por los parámetros proporcionados. Es obligatorio enviar ya sea un rango de fechas (initialdate y finaldate) o un contactId. Los parámetros client, clientId y clientName pueden usarse como filtros adicionales opcionales. Si no se especifican filtros de permisos en el cuerpo de la solicitud, los resultados se filtran según los permisos del usuario que realiza la petición.

Parámetros de consulta

Parámetro	Tipo	Descripción	Valores disponibles	Ejemplo
`initialdate`	String (requerido*)	Inicio del rango de fechas para filtrar interacciones	Cualquier fecha en formato `yyyy-MM-dd HH:mm:ss`, debe ser anterior o igual a `finaldate`	`2025-11-01 00:00:00`
`finaldate`	String (requerido*)	Fin del rango de fechas para filtrar interacciones	Cualquier fecha en formato `yyyy-MM-dd HH:mm:ss`, debe ser anterior o igual a hoy y posterior o igual a `initialdate`	`2025-12-15 23:59:59`
`format`	String (opcional)	Formato de fecha utilizado para interpretar `initialdate` y `finaldate` cuando se envía un formato personalizado	Cualquier patrón de fecha válido. Por defecto: `yyyy-MM-dd HH:mm:ss`	`yyyy-MM-dd`
`contactId`	String (requerido*)	Identificador de contacto usado para filtrar interacciones. Puede usarse en lugar de un rango de fechas	Cualquier cadena de texto	`test`
`client`	String (opcional)	Filtra interacciones donde `clientId` o `clientName` comienza con el valor proporcionado	Cualquier cadena de texto	`test`
`clientId`	String (opcional)	Filtra interacciones donde `clientId` comienza con el valor proporcionado	Cualquier cadena de texto	`123`
`clientName`	String (opcional)	Filtra interacciones donde `clientName` comienza con el valor proporcionado. En algunas interacciones este campo puede estar ausente (por ejemplo, webchat)	Cualquier cadena de texto	`John`
`timezone`	String (opcional)	Zona horaria utilizada para interpretar el rango de fechas. Por defecto UTC si no se especifica	Cualquier zona horaria IANA válida	`America/Montevideo`
`channels`	String (opcional)	Filtro por canal, separados por comas	`email`, `telephony`, `sms`, `whatsapp`, `webchat`, `instagram`, `messenger`	`telephony,sms,whatsapp,email`
`connectedInteraction`	String (opcional)	Filtra interacciones según si tuvieron un agente o no	`WITH_AGENT`, `WITHOUT_AGENT`	`WITH_AGENT`
`subject`	String (opcional)	Filtra por asunto de la interacción. Solo funciona con interacciones de tipo email	—	`Support request`
`interactionType`	String (opcional)	Filtra por dirección de la interacción	`INBOUND`, `OUTBOUND`, `OUTBOUND_HUB`	`INBOUND`
`guid`	String (opcional)	Filtra por el identificador único de la interacción (UUID)	Cualquier UUID válido	`b9afae52-e3b4-4c96-a568-39e90e78a737`
`connectorId`	String (opcional)	Filtra por el identificador del conector utilizado en la interacción	Cualquier valor de texto o numérico	`234324234`
`index`	Integer (requerido)	Número de página para la paginación	`>= 0`	`1`
`rows`	Integer (requerido)	Cantidad de resultados por página	`> 0`	`25`
`orders`	Array (opcional)	Array JSON de objetos con criterios de ordenamiento, con las propiedades `field` y `direction`	—	`[{"field":"start_date","direction":"asc"}]`

*Es obligatorio enviar initialdate y finaldate juntos, o bien contactId.

Cuerpo de la solicitud

El cuerpo de la solicitud es opcional y puede usarse para filtrar resultados por recursos específicos. Si se omite, la API retorna resultados filtrados según los permisos del usuario que realiza la petición. Los filtros users y automations se combinan cuando ambos están presentes.

Content-Type: application/json
Cuerpo: Un objeto JSON con cualquiera de los siguientes filtros opcionales:

json

{
  "users": ["agent1", "agent2"],
  "campaigns": ["Campaign_1"],
  "dispositions": [1, 4, 6, 7],
  "outboundHubs": ["hub1"],
  "automations": ["automation1"]
}

Propiedad	Tipo	Descripción
`users`	Array[String] (opcional)	Lista de nombres de usuario de agentes para filtrar. Se combina con `automations` cuando ambos están presentes
`campaigns`	Array[String] (opcional)	Lista de nombres de campañas para filtrar
`dispositions`	Array[Integer] (opcional)	Lista de IDs de disposición. Filtra interacciones donde al menos un segmento tiene una de estas disposiciones
`outboundHubs`	Array[String] (opcional)	Lista de nombres de hubs de salida para filtrar
`automations`	Array[String] (opcional)	Lista de nombres de automatizaciones para filtrar. Se combina con `users` cuando ambos están presentes

Respuesta

Retorna un objeto de resultado paginado.

Cuerpo de la respuesta

Campo	Tipo	Descripción
`result`	Array	Array de objetos con el resumen de cada interacción
`index`	Integer	Índice de página actual
`rows`	Integer	Cantidad de filas por página
`total`	Integer	Total de interacciones que coinciden con la consulta
`serverDate`	String	Fecha del servidor al momento de la respuesta

Cada objeto en result representa una interacción. Contiene la información general de la interacción e incluye un array segments donde cada segmento especifica el agente y la campaña involucrados en ese segmento.

Campo	Tipo	Descripción
`guid`	String	Identificador único de la interacción
`channel`	String	Canal de comunicación utilizado (ej. `telephony`, `email`, `whatsapp`, `sms`)
`segments`	Array	Lista de segmentos que componen la interacción
`direction`	String	Dirección de la interacción (`inbound` o `outbound`)
`timings`	Object	Información de tiempos de la interacción
`client`	Object	Información sobre el cliente involucrado
`flags`	Object	Indicadores booleanos que describen el estado de la interacción
`disposition`	Object/null	Disposición establecida al finalizar la interacción, `null` si no fue definida
`dialer`	Object/null	Información del marcador si la interacción fue creada por un hub de salida, `null` en caso contrario
`connectorId`	String	Identificador del conector utilizado

Objetos en segments:

Campo	Tipo	Descripción
`campaign`	String	Nombre de la campaña para este segmento
`agent`	String	Nombre de usuario del agente que atendió este segmento

Objeto timings:

Campo	Tipo	Descripción
`startDate`	String	Fecha y hora en que comenzó la interacción
`endDate`	String	Fecha y hora en que finalizó la interacción
`duration`	Integer	Duración total de la interacción en segundos

Objeto client:

Campo	Tipo	Descripción
`id`	String	Identificador del cliente
`name`	String	Nombre del cliente
`contactId`	String	Identificador de contacto en el CRM vinculado

Objeto flags:

Campo	Tipo	Descripción
`holiday`	Boolean	Si la interacción ocurrió en un día festivo
`outOfTime`	Boolean	Si la interacción ocurrió fuera del horario de atención
`finished`	Boolean	Si la interacción ha finalizado

Objeto disposition (cuando no es null):

Campo	Tipo	Descripción
`id`	Integer	Identificador de la disposición
`comment`	String	Comentario dejado por el agente
`levels`	Array[String]	Niveles de disposición seleccionados

Objeto dialer (cuando no es null):

Campo	Tipo	Descripción
`id`	Integer	Identificador del marcador
`name`	String	Nombre del marcador
`list`	String	Nombre de la lista del marcador utilizada

Ejemplo de respuesta

json

{
  "result": [
    {
      "guid": "a3f1c2d4-7e89-4b56-9f01-2e3a4b5c6d7e",
      "channel": "telephony",
      "segments": [
        { "campaign": "inbound_support", "agent": "jsmith" },
        { "campaign": "inbound_support", "agent": "mjohnson" }
      ],
      "direction": "inbound",
      "timings": {
        "startDate": "2025-10-21 09:14:22",
        "endDate": "2025-10-21 09:23:15",
        "duration": 533
      },
      "client": { "id": "15551234567", "name": "Sarah Connor", "contactId": "crm_00483" },
      "flags": {
        "holiday": false,
        "outOfTime": false,
        "finished": true
      },
      "disposition": {
        "id": 12,
        "comment": "Customer requested a callback for next week.",
        "levels": ["Support", "Follow-up"]
      },
      "dialer": null,
      "connectorId": "support_trunk_01"
    }
  ],
  "index": 1,
  "rows": 5,
  "total": 348,
  "serverDate": "2025-10-21 09:30:00"
}

Códigos de estado

Código	Descripción
200	Éxito
400	Solicitud incorrecta – parámetros faltantes o inválidos, o solicitud de un recurso sin permiso
500	Error interno del servidor – ej. consulta mal formada

Obtener detalle de una interacción

Este endpoint retorna el detalle completo de una interacción específica.

Método: GET
URL: https://<dominio>.ucontactcloud.com/api/interactions/id/<guid>

Descripción general

Retorna todos los segmentos de una interacción específica identificada por su GUID. Cada segmento representa una etapa del ciclo de vida de la interacción — incluyendo encolado, atención por parte del agente y transferencias — con información detallada de tiempos, cliente, eventos, disposición y transferencias.

Parámetros de ruta

Parámetro	Tipo	Descripción
`guid`	String	El identificador único de la interacción

Respuesta

Retorna un objeto de resultado que contiene un array de objetos con el detalle de cada segmento.

Cuerpo de la respuesta

Campo	Tipo	Descripción
`result`	Array	Array de objetos con el detalle de cada segmento
`index`	Integer	Siempre `0`
`rows`	Integer	Siempre `0`
`total`	Integer	Siempre `0`
`serverDate`	String	Fecha del servidor al momento de la respuesta

Cada objeto en result representa un segmento y contiene:

Campo	Tipo	Descripción
`segmentId`	String	Identificador único del segmento
`campaign`	String	Nombre de la campaña asociada a este segmento
`channel`	String	Canal de comunicación (ej. `telephony`, `email`, `whatsapp`, `sms`)
`direction`	String	Dirección de la interacción (`inbound` o `outbound`)
`connectorId`	String	Identificador del conector utilizado
`agent`	String	Nombre de usuario del agente que atendió este segmento
`assignedAgent`	String	Nombre de usuario del agente al que fue asignada la interacción
`origin`	String/null	Origen del segmento. Valores posibles: `backToQueue`, `null`, `campaign`, `endBot`, `agent`
`subject`	String	Asunto de la interacción (solo aplica para email)
`in`	Integer	Cantidad de mensajes entrantes en este segmento
`out`	Integer	Cantidad de mensajes salientes en este segmento
`data`	Object	Información adicional sobre la interacción, como metadatos específicos del canal y variables
`events`	Array	Lista de eventos ocurridos durante el segmento (ej. `Parked`, `Hold`)
`timings`	Object	Información detallada de tiempos del segmento
`client`	Object	Información sobre el cliente involucrado
`flags`	Object	Indicadores booleanos que describen el estado del segmento
`disposition`	Object/null	Disposición establecida al finalizar el segmento, `null` si no fue definida
`dialer`	Object/null	Información del marcador si la interacción fue creada por un hub de salida, `null` en caso contrario
`transfer`	Object/null	Información de transferencia si se realizó una transferencia, `null` en caso contrario
`comments`	Array	Lista de comentarios añadidos al segmento

Objeto timings:

Campo	Tipo	Descripción
`startDate`	String	Fecha y hora en que comenzó el segmento
`endDate`	String	Fecha y hora en que finalizó el segmento
`dateAttended`	String	Fecha y hora en que la interacción fue atendida por primera vez
`dateAttendedAgent`	String	Fecha y hora en que un agente atendió la interacción por primera vez
`dateFirstResponse`	String	Fecha y hora de la primera respuesta del agente
`duration`	Integer	Duración total del segmento en segundos
`holdtime`	Integer	Tiempo total que la interacción estuvo en espera en segundos
`attentionTime`	Integer	Tiempo que el agente dedicó activamente a la interacción en segundos
`firstResponseTime`	Integer	Tiempo hasta la primera respuesta en segundos
`art`	Integer	Tiempo de respuesta promedio en segundos

Objeto client:

Campo	Tipo	Descripción
`id`	String	Identificador del cliente
`name`	String	Nombre visible del cliente
`userName`	String	Nombre de usuario del cliente
`contactId`	String	Identificador de contacto en el CRM vinculado

Objeto flags:

Campo	Tipo	Descripción
`finished`	Boolean	Si el segmento ha finalizado
`abandon`	Boolean	Si la interacción fue abandonada por el cliente
`finishedByTimeout`	Boolean	Si la interacción fue finalizada por tiempo de espera agotado
`finishedByClient`	Boolean	Si la interacción fue finalizada por el cliente
`attendedByBot`	Boolean	Si la interacción fue atendida por un bot
`holiday`	Boolean	Si la interacción ocurrió en un día festivo
`outOfTime`	Boolean	Si la interacción ocurrió fuera del horario de atención

Objeto disposition (cuando no es null):

Campo	Tipo	Descripción
`id`	String	Identificador de la disposición
`comment`	String	Comentario dejado por el agente
`levels`	Array[String]	Niveles de disposición seleccionados

Objeto transfer (cuando no es null):

Campo	Tipo	Descripción
`type`	String	Tipo de transferencia (`attended` o `blind`)
`destinationType`	String	Tipo de destino (`campaign`, `agent`, `external`, etc.)
`destination`	String	Nombre de la campaña o agente de destino
`successful`	Boolean	Si la transferencia se completó exitosamente

Objeto dialer (cuando no es null):

Campo	Tipo	Descripción
`id`	Integer	Identificador del marcador
`name`	String	Nombre del marcador

Cada objeto en events:

Campo	Tipo	Descripción
`event`	String	Tipo de evento ocurrido (ej. `hold`)
`startTime`	String	Fecha y hora en que comenzó el evento
`endTime`	String	Fecha y hora en que finalizó el evento

Ejemplo de respuesta

json

{
  "result": [
    {
      "segmentId": "10041",
      "campaign": "inbound_support",
      "channel": "telephony",
      "direction": "inbound",
      "connectorId": "234324234",
      "agent": "Agent1",
      "assignedAgent": "",
      "origin": "",
      "subject": "",
      "in": 0,
      "out": 0,
      "data": {},
      "events": [],
      "timings": {
        "startDate": "2025-10-21 09:14:22",
        "endDate": "2025-10-21 09:15:03",
        "dateAttended": "2025-10-21 09:14:22",
        "dateAttendedAgent": "",
        "dateFirstResponse": "",
        "duration": 41,
        "holdtime": 0,
        "attentionTime": 0,
        "firstResponseTime": 0,
        "art": 0
      },
      "client": {
        "id": "15551234567",
        "name": "Sarah Connor",
        "userName": "",
        "contactId": "crm_00483"
      },
      "flags": {
        "finished": false,
        "abandon": false,
        "finishedByTimeout": false,
        "finishedByClient": false,
        "attendedByBot": false,
        "holiday": false,
        "outOfTime": false
      },
      "disposition": null,
      "dialer": null,
      "transfer": null,
      "comments": []
    },
    {
      "segmentId": "10042",
      "campaign": "inbound_support",
      "channel": "telephony",
      "direction": "inbound",
      "connectorId": "234324234",
      "agent": "Agent1",
      "assignedAgent": "",
      "origin": "campaign",
      "subject": "",
      "in": 0,
      "out": 0,
      "data": {},
      "events": [
        { "event": "hold", "startTime": "2025-10-21 09:18:05", "endTime": "2025-10-21 09:19:12" }
      ],
      "timings": {
        "startDate": "2025-10-21 09:15:03",
        "endDate": "2025-10-21 09:23:15",
        "dateAttended": "2025-10-21 09:15:11",
        "dateAttendedAgent": "2025-10-21 09:15:11",
        "dateFirstResponse": "2025-10-21 09:15:14",
        "duration": 492,
        "holdtime": 67,
        "attentionTime": 425,
        "firstResponseTime": 3,
        "art": 28
      },
      "client": {
        "id": "15551234567",
        "name": "Sarah Connor",
        "userName": "",
        "contactId": "crm_00483"
      },
      "flags": {
        "finished": true,
        "abandon": false,
        "finishedByTimeout": false,
        "finishedByClient": false,
        "attendedByBot": false,
        "holiday": false,
        "outOfTime": false
      },
      "disposition": {
        "id": "12",
        "comment": "Customer requested a callback for next week.",
        "levels": ["Support", "Follow-up"]
      },
      "dialer": null,
      "transfer": {
        "type": "attended",
        "destinationType": "campaign",
        "destination": "billing_support",
        "successful": false
      },
      "comments": []
    }
  ],
  "index": 0,
  "rows": 0,
  "total": 0,
  "serverDate": "2026-03-10 16:38:00"
}

Códigos de estado

Código	Descripción
200	Éxito
400	Solicitud incorrecta – parámetros faltantes o inválidos, o solicitud de un recurso sin permiso
404	Interacción no encontrada
500	Error interno del servidor – ej. consulta mal formada

Tipos de flujos

Funcionalidades

Teléfono de prueba

Usabilidad del diseñador

¿Cómo guardar el flujo?

Histórico

Funcionalidades

Actividades

Primeros pasos

API REST

Autenticación

Window Proxy

Eventos

Webhooks events

Tipos de funciones

Interactions API

Obtener interacciones

Descripción general

Parámetros de consulta

Cuerpo de la solicitud

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Códigos de estado

Obtener detalle de una interacción

Descripción general

Parámetros de ruta

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Códigos de estado

Autenticación

Eventos

Interactions API ​

Obtener interacciones ​

Descripción general ​

Parámetros de consulta ​

Cuerpo de la solicitud ​

Respuesta ​

Cuerpo de la respuesta ​

Ejemplo de respuesta ​

Códigos de estado ​

Obtener detalle de una interacción ​

Descripción general ​

Parámetros de ruta ​

Respuesta ​

Cuerpo de la respuesta ​

Ejemplo de respuesta ​

Códigos de estado ​

Interactions API

Obtener interacciones

Descripción general

Parámetros de consulta

Cuerpo de la solicitud

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Códigos de estado

Obtener detalle de una interacción

Descripción general

Parámetros de ruta

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta

Códigos de estado