Search for interactions

Owned by Helen Griffith
Last updated: Aug 06, 2024

The GET /interactions endpoint enables you to retrieve interaction metadata and managed content. You can search for interactions and the endpoint will return a list of interactions that the user has access to with their account. The endpoint returns only the interactions that have at least one piece of interaction content.

In this page


Most URLs in the example code use the following values:

Headers

Header parameters in Requests (Interaction Content API) apply to this endpoint.

Authorization scopes supported:

ScopeAccess granted
interaction-content:readEntire endpoint

Parameters

The endpoint accepts the following query parameters:

start

Type

Required

Example

StringTrue2021-01-01T00:00:00Z

The start date and time for the interaction search (inclusive). Use ISO8601 format. The maximum date range between start and end dates for an interaction search is 7 days. The range includes the start date.

end

Type

Required

Example

StringTrue2021-02-01T00:00:00Z

The end date and time for the interaction search (inclusive). Use ISO8601 format. The maximum date range between start and end dates for an interaction search is 7 days. The range includes the end date.

handlingAgentId

Type

Required

Example

StringFalse67833

The ID of the agent you want to find interactions for.

connectFrom

Type

Required

Example

StringFalse33890021

The address of the party that initiated the interaction. This is most commonly a phone number, but for non-phone interactions it could be an email, chat handle, or similar. This parameter uses a 'starts with' search. Minimum length is 1, maximum is 50.

connectTo

Type

Required

Example

StringFalse33890022

The address of the party that received the interaction. This is most commonly a phone number, but for non-phone interactions it could be an email, chat handle, or similar. This parameter uses a 'starts with' search. Minimum length is 1, maximum is 50.

direction

Type

Required

Example

StringFalseinbound

The direction of the interaction. Available values are inbound or outbound. An inbound interaction occurs when a customer initiates an interaction, and outbound interactions when an agent initiates an interaction. If you do not specify a value, the API returns interactions in both directions.

continuationToken

Type

Required

Example

StringFalseMjAyMS0wMi0xNVQwNzo1MzoxM1pfMQ==

Continuation token generated by previous API call. This must be provided to return additional pages of data. When not provided the first page is returned.

limit

Type

Required

Example

integerFalse1000

The required size (number of items) per page returned in response, with a minimum of 1 and a maximum of 1000. Defaults to 1000.

Request

Request interaction between two dates

curl -L -X GET "https://***.api.newvoicemedia.com/interaction-content/interactions?start=2021-12-01T14:18:23.857Z&end=2021-12-06T14:18:23.857Z" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json" \

Request interaction between two dates with a continuationToken

curl -L -X GET "https://***.api.newvoicemedia.com/interaction-content/interactions?start=2021-12-01T14:18:23.857Z&end=2021-12-06T14:18:23.857Z&continuationToken=MjAyMS0wMi0xNVQwNzo1MzoxM1pfMQ==" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v3+json" \

Request interaction between two dates that start with an area code

curl -L -X GET "https://***.api.newvoicemedia.com/interaction-content/interactions?start=2021-12-01T14:18:23.857Z&end=2021-12-06T14:18:23.857Z&connectfrom=01473" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v2+json" \

Responses

Responses to the endpoint returns the presences of all the users.

Successful response

For information about successful responses, see Success response code and parameters in Responses (Interaction Content API).

Example responses

Next page exists

{
  "items": [
    {
      "guid": "2480fc2c-bbd7-427c-9439-02f76583aef5",
      "start": "2020-02-16T14:11:56Z",
      "connectFrom": 14154204204,
      "connectTo": 22222,
      "direction": "inbound",
      "handlingAgents": [
        {
          "id": "1342"
        }
      ],
      "content": [
        {
          "contentKey": "callRecording",
          "type": "callRecording",
          "contentType": "audio/wav",
          "contentLength": 359,
          "lastModified": "2020-02-16T14:19:35Z",
          "properties": {}
        },
        {
          "contentKey": "fbebd00a-9017-48d3-ad5c-156f4c45024e",
          "type": "voicemail",
          "contentType": "audio/wav",
          "contentLength": 121,
          "owningAgent": {
            "id": "1342"
          },
          "lastModified": "2020-02-16T14:19:01Z",
          "properties": {}
        },
	 	{
          "contentKey": "ad76a807-3e21-41c6-992e-dc9865ffcc9d",
          "type": "ivrAudioRecording",
          "contentType": "audio/wav",
          "contentLength": 100,
          "owningInteractionPlan": {
            "id": "816f1144-ac27-4bba-a280-cc66"
          },
          "lastModified": "2020-02-16T14:20:01Z",
          "properties": {}
        },
	 	{
          "contentKey": "73c986b3-c704-4f8d-ac3c-53205772a003",
          "type": "chatTranscript",
          "contentType": "application/json",
          "contentLength": 906,
          "lastModified": "2024-02-01T13:31:31Z",
          "properties": {
            "version": {
              "value": 1
            },
			"duration" : {
			  "value": 5000
 			}
          }
	 	}
      ]
    }
  ],
  "meta": {
    "nextContinuationToken": "MjAyMS0wMS0yMFQxMDoxMDowMC4wMDBaXw=="
  }
}

Next page does not exist

{
  "items": [
    {
      "guid": "2480fc2c-bbd7-427c-9439-02f76583aef5",
      "start": "2020-02-16T14:11:56Z",
      "connectFrom": 14154204204,
      "connectTo": 22222,
      "direction": "inbound",
      "handlingAgents": [
        {
          "id": "1342"
        }
      ],
      "content": [
        {
          "contentKey": "callRecording",
          "type": "callRecording",
          "contentType": "audio/wav",
          "contentLength": 359,
          "lastModified": "2020-02-16T14:19:35Z",
          "properties": {}
        },
        {
          "contentKey": "fbebd00a-9017-48d3-ad5c-156f4c45024e",
          "type": "voicemail",
          "contentType": "audio/wav",
          "contentLength": 121,
          "owningAgent": {
            "id": "1342"
          },
          "lastModified": "2020-02-16T14:19:01Z",
          "properties": {}
        },
	 	{
          "contentKey": "ad76a807-3e21-41c6-992e-dc9865ffcc9d",
          "type": "ivrAudioRecording",
          "contentType": "audio/wav",
          "contentLength": 100,
          "owningInteractionPlan": {
            "id": "816f1144-ac27-4bba-a280-cc66"
          },
          "lastModified": "2020-02-16T14:20:01Z",
          "properties": {}
        },
	 	{
          "contentKey": "73c986b3-c704-4f8d-ac3c-53205772a003",
           "type": "chatTranscript",
          "contentType": "application/json",
          "contentLength": 906,
          "lastModified": "2024-02-01T13:31:31Z",
          "properties": {
            "version": {
              "value": 1
            },
			"duration" : {
			  "value": 5000
 			}
          }
	 	}
      ]
    }
  ],
  "meta": {
    "nextContinuationToken": null
  }
}

where:

  • guid. The unique identifier of the interaction.
  • start. The interaction start date.
  • connectFrom. The address of the party that initiated the interaction. For a phone call connectFrom is their phone number.
  • connectTo. The address of the party that was being contacted within the interaction. For a phone call connectTo is their phone number.
  • direction. The direction of the interaction. Can be:
    • inbound. Interaction was initiated by a customer to interact with a VCC agent
    • outbound. Interaction was initiated by a VCC agent to interact with a customer
  • handlingAgents. A JSON array with identifiers of the agents involved in the interaction.
    • id. The unique identifier of each handling agent.
  • content. A JSON array with content attached to this interaction. 
    • contentKey. The key of the content type you can retrieve from a given interaction using the GET ‘/interactions/{guid}/content/{contentKey}’ endpoint.
    • type. The type of the content. Supported types are:
      • callRecording
      • screenRecording
      • voicemail
      • transcript
      • chatTranscript
      • categorizationResult
      • sentimentSummary
      • attachment
      • ivrAudioRecording
      • videoRecording
      • conversationSummary
      • interactionLog
    • contentType. The media type of the interaction content such as audio/wav or application/json.
    • contentLength. The size (number of bytes) of the individual item of content, for example, voicemail.
    • owningAgent. The identifier of the agent that owns the content. Returned only for some types of content — where type is voicemail.
      • id. The unique identifier of the owning agent.
    • owningInteractionPlan. The identifier of the interaction plan that the content was created by. Returned only for some types of content — where type is ivrAudioRecording.
      • id. The unique identifier of the interaction plan.
    • lastModified. The date/time (in UTC) that the interaction content was last modified.
    • properties. Depending on the content type, additional properties may be returned.
      • version. The version of the content type returned for only some types of content.
        • value. The version of the content type.  
      • duration. Content-level duration returned for types: callRecording, screenRecording, chatTranscript, voicemail, videoRecording, ivrAudioRecording.
        • value. The duration of the content in milliseconds. 
  • meta. 
    • nextContinuationToken. The token that can be used to request the next page of results.


Try it out

  

For information, see Trying out Vonage Contact Center APIs.