Interactions API

This API allows you to query and retrieve interaction data from uContact. Through its endpoints, you can get paginated summaries of interactions filtered by date range or client identifier, and retrieve the full detail of a specific interaction.

Get interactions

This endpoint returns a paginated summary list of interactions.

Method: GET
URL: https://<domain>.ucontactcloud.com/api/interactions

General description

Returns a paginated list of interaction summaries filtered by the provided parameters. Either a date range (initialdate and finaldate) or contactId must be provided. client, clientId, and clientName can be used as optional additional filters. If no permission filters are specified in the request body, the results are filtered based on the requesting user's permissions.

Query parameters

Parameter	Type	Description	Available values	Example
`initialdate`	String (required*)	Start of the date range to filter interactions	Any date in format `yyyy-MM-dd HH:mm:ss`, must be before or equal to `finaldate`	`2025-11-01 00:00:00`
`finaldate`	String (required*)	End of the date range to filter interactions	Any date in format `yyyy-MM-dd HH:mm:ss`, must be before or equal to today and after or equal to `initialdate`	`2025-12-15 23:59:59`
`format`	String (optional)	Date format used to parse `initialdate` and `finaldate` when a custom format is sent	Any valid date pattern. Default: `yyyy-MM-dd HH:mm:ss`	`yyyy-MM-dd`
`contactId`	String (required*)	Contact identifier used to filter interactions. Can be used instead of a date range	Any string	`test`
`client`	String (optional)	Filters interactions where `clientId` or `clientName` starts with the provided value	Any string	`test`
`clientId`	String (optional)	Filters interactions where `clientId` starts with the provided value	Any string	`123`
`clientName`	String (optional)	Filters interactions where `clientName` starts with the provided value. In some interactions this field may be missing (for example, webchat)	Any string	`John`
`timezone`	String (optional)	Timezone used to interpret the date range. Defaults to UTC if not specified	Any valid IANA timezone	`America/Montevideo`
`channels`	String (optional)	Filter by channel, separated by commas	`email`, `telephony`, `sms`, `whatsapp`, `webchat`, `instagram`, `messenger`	`telephony,sms,whatsapp,email`
`connectedInteraction`	String (optional)	Filter interactions by whether they had an agent or not	`WITH_AGENT`, `WITHOUT_AGENT`	`WITH_AGENT`
`subject`	String (optional)	Filter by subject of the interaction. Only works with email interactions	—	`Support request`
`interactionType`	String (optional)	Filter by interaction direction	`INBOUND`, `OUTBOUND`, `OUTBOUND_HUB`	`INBOUND`
`guid`	String (optional)	Filter by the interaction's unique identifier (UUID)	Any valid UUID	`b9afae52-e3b4-4c96-a568-39e90e78a737`
`connectorId`	String (optional)	Filter by the connector identifier used in the interaction	Any string or numeric value	`234324234`
`index`	Integer (required)	Page number for pagination	`>= 0`	`1`
`rows`	Integer (required)	Number of results per page	`> 0`	`25`
`orders`	Array (optional)	JSON array of sorting criteria objects with `field` and `direction` properties	—	`[{"field":"start_date","direction":"asc"}]`

*Either initialdate and finaldate together, or contactId must be provided.

Request body

The optional request body can be used to further filter results by specific resources. If omitted, the API returns results filtered based on the requesting user's permissions. The users and automations filters are combined when both are present.

Content-Type: application/json
Body: A JSON object containing any of the following optional filters:

json

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

Property	Type	Description
`users`	Array[String] (optional)	List of agent usernames to filter by. Combined with `automations` when both are present
`campaigns`	Array[String] (optional)	List of campaign names to filter by
`dispositions`	Array[Integer] (optional)	List of disposition ids. Filters interactions where at least one segment has one of these dispositions
`outboundHubs`	Array[String] (optional)	List of outbound hub names to filter by
`automations`	Array[String] (optional)	List of automation names to filter by. Combined with `users` when both are present

Response

Returns a paginated result object.

Response body

Field	Type	Description
`result`	Array	Array of interaction summary objects
`index`	Integer	Current page index
`rows`	Integer	Number of rows per page
`total`	Integer	Total number of interactions matching the query
`serverDate`	String	Server date at the time of the response

Each object in result represents one interaction. It returns the general information of the interaction and includes a segments array where each segment specifies the agent and campaign involved in that segment.

Field	Type	Description
`guid`	String	Unique identifier of the interaction
`channel`	String	Communication channel used (e.g. `telephony`, `email`, `whatsapp`, `sms`)
`segments`	Array	List of segments that make up the interaction
`direction`	String	Direction of the interaction (`inbound` or `outbound`)
`timings`	Object	Timing information for the interaction
`client`	Object	Information about the client involved
`flags`	Object	Boolean flags describing the state of the interaction
`disposition`	Object/null	Disposition set at the end of the interaction, `null` if not set
`dialer`	Object/null	Dialer information if the interaction was created by an outbound hub, `null` otherwise
`connectorId`	String	Identifier of the connector used

segments objects:

Field	Type	Description
`campaign`	String	Name of the campaign for this segment
`agent`	String	Username of the agent who handled this segment

timings object:

Field	Type	Description
`startDate`	String	Date and time the interaction started
`endDate`	String	Date and time the interaction ended
`duration`	Integer	Total duration of the interaction in seconds

client object:

Field	Type	Description
`id`	String	Client identifier
`name`	String	Client name
`contactId`	String	CRM contact identifier linked to this client

flags object:

Field	Type	Description
`holiday`	Boolean	Whether the interaction occurred on a holiday
`outOfTime`	Boolean	Whether the interaction occurred outside business hours
`finished`	Boolean	Whether the interaction has finished

disposition object (when not null):

Field	Type	Description
`id`	Integer	Identifier of the disposition
`comment`	String	Comment left by the agent
`levels`	Array[String]	The disposition levels selected

dialer object (when not null):

Field	Type	Description
`id`	Integer	Identifier of the dialer
`name`	String	Dialer name
`list`	String	Name of the dialer list used

Example response

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"
}

Status codes

Code	Description
200	Success
400	Bad request – missing or invalid query parameters, or requesting a resource without permission
500	Internal server error – e.g. malformed query

Get interaction detail

This endpoint returns the full detail of a specific interaction.

Method: GET
URL: https://<domain>.ucontactcloud.com/api/interactions/id/<guid>

General description

Returns all segments of a specific interaction identified by its GUID. Each segment represents a step in the interaction's lifecycle — including queuing, agent handling, and transfers — with detailed timing, client, event, disposition, and transfer information.

Path parameters

Parameter	Type	Description
`guid`	String	The unique identifier of the interaction

Response

Returns a result object containing an array of segment detail objects.

Response body

Field	Type	Description
`result`	Array	Array of segment detail objects
`index`	Integer	Always `0`
`rows`	Integer	Always `0`
`total`	Integer	Always `0`
`serverDate`	String	Server date at the time of the response

Each object in result represents a segment and contains:

Field	Type	Description
`segmentId`	String	Unique identifier for the segment
`campaign`	String	Name of the campaign associated with this segment
`channel`	String	Communication channel (e.g. `telephony`, `email`, `whatsapp`, `sms`)
`direction`	String	Direction of the interaction (`inbound` or `outbound`)
`connectorId`	String	Identifier of the connector used
`agent`	String	Username of the agent who handled this segment
`assignedAgent`	String	Username of the agent the interaction was assigned to
`origin`	String/null	Origin of the segment. Possible values: `backToQueue`, `null`, `campaign`, `endBot`, `agent`
`subject`	String	Subject of the interaction (Only applicable for email)
`in`	Integer	Number of inbound messages in this segment
`out`	Integer	Number of outbound messages in this segment
`data`	Object	Extra information about the interaction, such as channel-specific metadata and variables
`events`	Array	List of events that occurred during the segment (e.g. `Parked`, `Hold`)
`timings`	Object	Detailed timing information for the segment
`client`	Object	Information about the client involved
`flags`	Object	Boolean flags describing the state of the segment
`disposition`	Object/null	Disposition set at the end of the segment, `null` if not set
`dialer`	Object/null	Dialer information if the interaction was created by an outbound hub, `null` otherwise
`transfer`	Object/null	Transfer information if a transfer occurred, `null` otherwise
`comments`	Array	List of comments added to the segment

timings object:

Field	Type	Description
`startDate`	String	Date and time the segment started
`endDate`	String	Date and time the segment ended
`dateAttended`	String	Date and time the interaction was first attended
`dateAttendedAgent`	String	Date and time an agent first attended the interaction
`dateFirstResponse`	String	Date and time of the first agent response
`duration`	Integer	Total duration of the segment in seconds
`holdtime`	Integer	Total time the interaction was on hold in seconds
`attentionTime`	Integer	Time the agent spent actively attending the interaction in seconds
`firstResponseTime`	Integer	Time until the first response in seconds
`art`	Integer	Average response time in seconds

client object:

Field	Type	Description
`id`	String	Client identifier
`name`	String	Client display name
`userName`	String	Client username
`contactId`	String	CRM contact identifier linked to this client

flags object:

Field	Type	Description
`finished`	Boolean	Whether the segment has finished
`abandon`	Boolean	Whether the interaction was abandoned by the client
`finishedByTimeout`	Boolean	Whether the interaction was finished due to a timeout
`finishedByClient`	Boolean	Whether the interaction was finished by the client
`attendedByBot`	Boolean	Whether the interaction was handled by a bot
`holiday`	Boolean	Whether the interaction occurred on a holiday
`outOfTime`	Boolean	Whether the interaction occurred outside business hours

disposition object (when not null):

Field	Type	Description
`id`	String	Identifier of the disposition
`comment`	String	Comment left by the agent
`levels`	Array[String]	The disposition levels selected

transfer object (when not null):

Field	Type	Description
`type`	String	Type of transfer (`attended` or `blind`)
`destinationType`	String	Type of destination (`campaign`, `agent`, `external`, etc.)
`destination`	String	Name of the destination campaign or agent
`successful`	Boolean	Whether the transfer was completed successfully

dialer object (when not null):

Field	Type	Description
`id`	Integer	Identifier of the dialer
`name`	String	Dialer name

Each object in events:

Field	Type	Description
`event`	String	Type of event that occurred (e.g. `hold`)
`startTime`	String	Date and time the event started
`endTime`	String	Date and time the event ended

Example response

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"
}

Status codes

Code	Description
200	Success
400	Bad request – missing or invalid parameters, or requesting a resource without permission
404	Interaction not found
500	Internal server error – e.g. malformed query

Workflow types

Functionalities

Test phone

Functionalities

Activities

Project management

API REST

Webhooks events

Types of functions

Interactions API

Get interactions

General description

Query parameters

Request body

Response

Response body

Example response

Status codes

Get interaction detail

General description

Path parameters

Response

Response body

Example response

Status codes

Interactions API ​

Get interactions ​

General description ​

Query parameters ​

Request body ​

Response ​

Response body ​

Example response ​

Status codes ​

Get interaction detail ​

General description ​

Path parameters ​

Response ​

Response body ​

Example response ​

Status codes ​

Interactions API

Get interactions

General description

Query parameters

Request body

Response

Response body

Example response

Status codes

Get interaction detail

General description

Path parameters

Response

Response body

Example response

Status codes