Skip to content

Developer Guide

Jump to bottom
Tim edited this page Jan 23, 2015 · 20 revisions

Table of Contents

Overview

The Developer Guide is targeted at developers who will be consuming the integration service's REST API. This guide will document the technical usage of each resource in the API as well as provide a functional guide on how to use the integration service throughout the lifetime of a video conversation.

Postman Collection

A Postman collection is available in the repo at /resources. The collection contains requests for each method. There is also an environment export with the variables used by the Postman collection.

CoreService

The Core Service contains resources to interact with conversation objects and all entities directly related to CIC. The CoreServiceLib project can be found in the repo at /src/VidyoIntegration/CicComponents/CoreServiceLib/

Note: All resource paths are assumed to be prefixed with /ininvid/v1. For example, the request to create a new conversation will be represented as POST /conversations while the full resource URI would be http://integrationserver.com:80/ininvid/v1/conversations.

POST /coreservice/initialize

The initialize resource initializes the service after startup. This method's only intended use is to be called by the Windows Service host to initialize the Core Service. This is necessary to trigger the service to create the stateful components -- the connection to CIC and to reconstitute any in-progress conversations. This method should not be called at any other point; after being called the first time, the method will return immediately without performing any action.

Request

The request is a POST request and does not contain a body.

POST /ininvid/v1/coreservice/initialize HTTP/1.1
Host: integrationserver.com:80
Content-Type: multipart/form-data
Cache-Control: no-cache

Response

The response does not contain a body and will return one of the following status codes:

  • 204 Initialized
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Length → 0
Content-Type → text/html
Date → Thu, 22 Jan 2015 17:37:05 GMT
Server → Microsoft-HTTPAPI/2.0

GET /coreservice/info

The /coreservice/info resource returns information about the Core Service. This information includes CIC connection status, uptime (time since the service started), and a count of requests to each resource in the Core Service.

Request

The request is a GET request and does not contain any parameters.

GET /ininvid/v1/coreservice/info HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • conversationCount - (int) The number of active conversations
  • isConnectedToCic - (boolean) true if connected to CIC, false otherwise
  • connectionMessage - (string) A string with a human readable message about the connection state
  • cicServer - (string) The name of the CIC server to which the session is connected
  • cicUser - (string) The name of the CIC user account that owns the session
  • uptime - (TimeSpan) The duration that the service has been running
  • sessionManager - (string) The name of the session manager to which teh session is connected. This will be the name of the CIC server unless connected to an OSSM.
  • requestCounts - (array) This is an array of properties indicating how many times each resource has been requested. The property name is the concatenated string of the request method (get, post, delete, etc.) and the short resource path.

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 17:41:17 GMT
Link → <info.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "conversationCount": 1,
    "isConnectedToCic": true,
    "connectionMessage": "Up [LogOn] - Successfully connected to Interaction Center.",
    "cicServer": "cicservername",
    "cicUser": "serviceaccount",
    "uptime": "00:12:55.6853785",
    "sessionManager": "sessionmanagername",
    "requestCounts": {
        "post /coreservice/initialize": 2,
        "get /coreservice/info": 8,
        "get /coreservice/info/routes": 2,
        "get /conversations": 8,
        "get /queues/stats?queues[]={queue}": 4,
        "post /conversations": 1,
        "delete /conversations/{conversationId}": 1
    }
}

GET /coreservice/info/routes

Returns information about the available routes to resources in the Core Service.

Request

The request is a GET request and does not contain any parameters.

GET /ininvid/v1/coreservice/info/routes HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • <root> - (array) An array of service info objects
    • serviceName - (string) The name of the service
    • routes - (array) An array of route info
      • method - (string) The HTTP method for the request
      • path - (string) The relative path to the resource

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 18:01:39 GMT
Link → </routes.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

[
	{
		"serviceName": "VidyoIntegration.CoreServiceLib.CoreRequestRouter",
		"routes": [
			{
				"method": "POST",
				"path": "/ininvid/v1/conversations"
			},
			{
				"method": "POST",
				"path": "/ininvid/v1/conversations/attach"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/conversations"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/conversations/{conversationId}"
			},
			{
				"method": "DELETE",
				"path": "/ininvid/v1/conversations/{conversationId}"
			},
			{
				"method": "POST",
				"path": "/ininvid/v1/coreservice/initialize"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/coreservice/info"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/coreservice/info/routes"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/queues/stats"
			}
		]
	}
]

GET /queues/stats?queues={queue}

Returns queue statistic information about the specified queues.

Request

The request is a GET request and supports the following querystring parameters:

  • queues - (string[]) The queue or queues that should be retrieved. Repeat the queues parameter for each queue.

Example request:

GET /ininvid/v1/queues/stats?queues=sales&queues=support&waitForData=false HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • <root> - (array) An array of queue info objects
    • queueName - (string) The Cic queue name
    • interactionCount - (int, stat ID: inin.queue:InteractionCount) Number of non-disconnected interactions of a specified type maintained by queue manager
    • numberAvailableForAcdInteractions - (int, stat ID: inin.workgroup:NumberAvailableForACDInteractions) The number of agents available to take ACD interactions. An agent is considered to be available to take ACD interactions if all of the following apply: a) the agent is not on another interaction, b) the agent has an available status, c) the agent is logged on, d) the agent is activated on the specified workgroup.
    • percentAvailable - (int, stat ID: inin.workgroup:PercentAvailable) Percent of logged on agents that are available for ACD interactions. ((available to take ACD interactions / logged on) * 100). Value will be between 0 and 100 unless it is not set, in which case it will be -1.
    • averageWaitTimeCurrentPeriod - (duration, stat ID: inin.agent:AverageWaitTime) Average wait time in queue of all interactions. In other words, the average time an interaction from the specified workgroup has alerted the agent in the current period. This is the average time all interactions have been in the ACD - Alerting state on the agents queue for the specified workgroup.
    • averageWaitTimePreviousPeriod - (duration, stat ID: inin.agent:AverageWaitTime) Average wait time in queue of all interactions. In other words, the average time an interaction from the specified workgroup has alerted the agent in the previous period. This is the average time all interactions have been in the ACD - Alerting state on the agents queue for the specified workgroup.
    • averageWaitTimeCurrentShift - (duration, stat ID: inin.agent:AverageWaitTime) Average wait time in queue of all interactions. In other words, the average time an interaction from the specified workgroup has alerted the agent in the current shift. This is the average time all interactions have been in the ACD - Alerting state on the agents queue for the specified workgroup.
    • averageWaitTimePreviousShift - (duration, stat ID: inin.agent:AverageWaitTime) Average wait time in queue of all interactions. In other words, the average time an interaction from the specified workgroup has alerted the agent in the previous shift. This is the average time all interactions have been in the ACD - Alerting state on the agents queue for the specified workgroup.
    • interactionsWaiting - (int, stat ID: inin.workgroup:InteractionsWaiting) Number of interactions waiting to be connected to an agent. These interactions are currently in the ACD - Wait Agent state.

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 18:09:32 GMT
Link → </stats.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

[
	{
		"queueName": "sales",
		"interactionCount": 0,
		"numberAvailableForAcdInteractions": 0,
		"percentAvailable": -1,
		"averageWaitTimeCurrentPeriod": "-10675199.02:48:05.4775808",
		"averageWaitTimePreviousPeriod": "-10675199.02:48:05.4775808",
		"averageWaitTimeCurrentShift": "-10675199.02:48:05.4775808",
		"averageWaitTimePreviousShift": "-10675199.02:48:05.4775808",
		"interactionsWaiting": 0
	},
	{
		"queueName": "support",
		"interactionCount": 1,
		"numberAvailableForAcdInteractions": 0,
		"percentAvailable": -1,
		"averageWaitTimeCurrentPeriod": "-10675199.02:48:05.4775808",
		"averageWaitTimePreviousPeriod": "-10675199.02:48:05.4775808",
		"averageWaitTimeCurrentShift": "-10675199.02:48:05.4775808",
		"averageWaitTimePreviousShift": "00:00:07",
		"interactionsWaiting": 1
	}
]

POST /conversations

Creates a new video conversation.

Request

The request is a POST request and requires the following body elements:

  • queueName - (string) The name of the CIC queue on which the interaction will be created. This can be a user or workgroup queue name; the queue type must be specified in the queueType parameter.
  • queueType - (string) The type of queue. Valid values are Workgroup or User.
  • mediaTypeParameters - (object) The media type parameter details for creating a conversation
    • additionalAttributes - (array) An array of attribute data (key/value pair objects). These attributes will be set on the interaction when it is created.
      • key - (string) The attribute name that will be set
      • value - (string) The value to which the attribute will be set
    • mediaType - (string) The type of media to create. Valid values to use here are GenericInteraction and Callback.
    • If the media type is GenericInteraction, the following parameters should be specified as children of mediaTypeParameters:
      • initialState - (string) The initial state in which to create the generic interaction. This should always be set to Offering unless a specific use case requires it to be set to something else.
    • If the media type is Callback, the following parameters should be specified as children of mediaTypeParameters:
      • callbackPhoneNumber - (string) The phone number to set on the callback interaction
      • callbackMessage - (string) The message to set on the callback interaction for use by the agent

Example request using a generic interaction:

POST /ininvid/v1/conversations HTTP/1.1
Host: notamac.i3domain.inin.com:8001
Content-Type: application/json
Cache-Control: no-cache
Postman-Token: cd2670c1-7954-6444-fb98-988ce732a27a

{
  "queueName":"support",
  "queueType": "Workgroup",
  "mediaTypeParameters":{
    "mediaType": "GenericInteraction",
    "initialState": "Offering",
    "additionalAttributes":[
      {
        "key":"Eic_RemoteName",
        "value":"Vidyo chat from postman"
      }
    ]
  }
}

Response

The response contains a body with the following members:

  • conversationId - (string) The GUID used to identify the conversation. The format will always be XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  • interactionId - (long) The interaction ID associated with the conversation
  • room - (object) The object containing data about the Vidyo room
    • roomId - (int) The Vidyo room ID
    • roomKey - (string) The Vidyo room key
    • name - (string) The name of the Vidyo room
    • extension - (string) The extension of the Vidyo room
    • pin - (string) The pin of the Vidyo room
    • roomUrl - (string) The Vidyo room URL. This is the direct room URL, NOT the guest join URL.
    • createdDateTime (datetime) The timestamp of when the room was created
  • attributeDictionary - (object) A collection of properties (key/value pairs) with the tracked attributes on the interaction. The property name is the name of the attribute and the property value is the value of the attribute.
  • scopedQueueName - (string) The scoped queue name of the CIC queue that the interaction is currently residing on. This will be a workgroup queue while the interaction is waiting for ACD assignement and will be a user queue after the interaction has been assigned (note that this value is set to the user queue while the interaction is alerting the user).
  • isConversationMuted - (bool) true indicates that the interaction has been put on hold and all participants in the room have been muted. false indicates that the interaction is not on hold.
  • initializationParameters - (object) The initialization parameters used to reconstitute the conversation. This is only intended to be used internally by the integration service.
  • userOwner - (string) The CIC username of the user that the interaction is assigned to. This value differs from scopedQueueName in that is only set when the user picks up the interaction and it enters a connected state; it will be empty otherwise. This can be used to identify if an agent has been assigned to the interaction to determine when it is appropriate to join the customer to the room.
  • roomUrl - (string) The base URL to join the Vidyo room. This is loaded with all of the necessary parameters to auto-join except for guestName. The display name for a participant should be appended to the querystring as "&guestName=<display name>".

The response will return one of the following status codes:

  • 200 OK
  • 400 <error message>
  • 500 <error message>

Example response using a generic interaction:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 18:28:21 GMT
Link → </conversations.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "conversationId": "9b017eca-d461-d489-9f46-8d54c6c54455",
    "interactionId": 2001480066,
    "room": {
        "roomId": 4258,
        "roomKey": "5lWgL2qvr7kf",
        "name": "Vidyo Integration Room (923462293)",
        "extension": "923469793",
        "pin": "804580",
        "roomUrl": "http://vidyoserver.com/flex.html?roomdirect.html&key=5lWgL2qvr7kf",
        "createdDateTime": "2015-01-22T11:28:21.8260894-07:00"
    },
    "attributeDictionary": {
        "eic_RemoteName": "Vidyo chat from postman",
        "video_ConversationId": "9b017eca-d489-4fc4-9f46-8d54c6c54455",
        "video_RoomId": "4258",
        "video_RoomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWgL2qvr7kf&key=5lWHd7ngvr7kf&roomPin=807580",
        "video_LastAgentToScreenPop": "",
        "eic_CallId": "2001480066",
        "eic_CallIdKey": "200148006640150122",
        "eic_CallStateString": "ACD - Wait Agent",
        "eic_WorkgroupName": "Support"
    },
    "scopedQueueName": "Workgroup Queue:Support",
    "isConversationMuted": false,
    "initializationParameters": {
        "mediaType": 2,
        "initialState": 5,
        "scopedQueueName": "Workgroup Queue:support",
        "additionalAttributes": {
            "eic_RemoteName": "Vidyo chat from postman",
            "video_ConversationId": "9b017eca-d489-4fc4-9f46-8d54c6c54455",
            "video_RoomId": "4258",
            "video_RoomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWHd2qvr7kf&key=5lWgL2qvr7kf&roomPin=804580"
        },
        "interactionId": 0
    },
    "userOwner": "",
    "roomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWHd2qvr7kf&key=5lWgL2qvr7kf&roomPin=804580"
}

POST /conversations/attach

Attaches a video conversation to an existing chat, callback, or generic interaction.

Note: For chat interactions, the service will insert the message "Video chat has been added to the chat" followed by the join URL for the guest that includes the specified guest name

Request

The request is a POST request and requires the following body elements:

  • interactionId - (long) This is the interaction ID of the interaction to which the video conversation will be attached. The interaction must be a chat, callback, or generic interaction or the request will fail.
  • additionalAttributes - (array) An array of attribute data (key/value pair objects). These attributes will be set on the interaction.
    • key - (string) The attribute name that will be set
    • value - (string) The value to which the attribute will be set
  • guestName - (string) The display name for the guest

Example request:

POST /ininvid/v1/conversations/attach HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

{
  "interactionId":2001480069,
  "additionalAttributes":[
    {
      "key":"Eic_RemoteName",
      "value":"Vidyo chat attached from postman"
    }
  ],
  "guestName":"Walter White"
}

Response

The response contains a body with the following members:

  • conversationId - (string) The GUID used to identify the conversation. The format will always be XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  • interactionId - (long) The interaction ID associated with the conversation
  • room - (object) The object containing data about the Vidyo room
    • roomId - (int) The Vidyo room ID
    • roomKey - (string) The Vidyo room key
    • name - (string) The name of the Vidyo room
    • extension - (string) The extension of the Vidyo room
    • pin - (string) The pin of the Vidyo room
    • roomUrl - (string) The Vidyo room URL. This is the direct room URL, NOT the guest join URL.
    • createdDateTime (datetime) The timestamp of when the room was created
  • attributeDictionary - (object) A collection of properties (key/value pairs) with the tracked attributes on the interaction. The property name is the name of the attribute and the property value is the value of the attribute.
  • scopedQueueName - (string) The scoped queue name of the CIC queue that the interaction is currently residing on. This will be a workgroup queue while the interaction is waiting for ACD assignement and will be a user queue after the interaction has been assigned (note that this value is set to the user queue while the interaction is alerting the user).
  • isConversationMuted - (bool) true indicates that the interaction has been put on hold and all participants in the room have been muted. false indicates that the interaction is not on hold.
  • initializationParameters - (object) The initialization parameters used to reconstitute the conversation. This is only intended to be used internally by the integration service.
  • userOwner - (string) The CIC username of the user that the interaction is assigned to. This value differs from scopedQueueName in that is only set when the user picks up the interaction and it enters a connected state; it will be empty otherwise. This can be used to identify if an agent has been assigned to the interaction to determine when it is appropriate to join the customer to the room.
  • roomUrl - (string) The base URL to join the Vidyo room. This is loaded with all of the necessary parameters to auto-join except for guestName. The display name for a participant should be appended to the querystring as "&guestName=<display name>".

The response will return one of the following status codes:

  • 200 OK
  • 400 <error message>
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 22:36:45 GMT
Link → </attach.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "conversationId": "0422fbc7-5990-4e0f-80da-262c2965c6d5",
    "interactionId": 2001480069,
    "room": {
        "roomId": 2573,
        "roomKey": "a3A68BBDuL5P",
        "name": "Vidyo Integration Room (915081920)",
        "extension": "915081920",
        "pin": "465796",
        "roomUrl": "http://vidyoserver.com/flex.html?roomdirect.html&key=a3A68BBDuL5P",
        "createdDateTime": "2015-01-22T15:36:45.2160763-07:00"
    },
    "attributeDictionary": {
        "eic_RemoteName": "Vidyo chat attached from postman",
        "video_ConversationId": "0422fbc7-5990-4e0f-80da-262c2965c6d5",
        "video_RoomId": "2573",
        "video_RoomUrl": "http://vidyoserver.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3da3A68BBDuL5P&key=a3A68BBDuL5P&roomPin=465796",
        "eic_AssignedWorkgroup": "Chat"
    },
    "scopedQueueName": null,
    "isConversationMuted": false,
    "mediaType": 0,
    "initializationParameters": {
        "mediaType": 3,
        "scopedQueueName": null,
        "additionalAttributes": {
            "eic_RemoteName": "Vidyo chat attached from postman",
            "video_ConversationId": "0422fbc7-5990-4e0f-80da-262c2965c6d5",
            "video_RoomId": "2573",
            "video_RoomUrl": "http://vidyoserver.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3da3A68BBDuL5P&key=a3A68BBDuL5P&roomPin=465796"
        },
        "interactionId": 2001480069
    },
    "userOwner": null,
    "roomUrl": "http://vidyoserver.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3da3A68BBDuL5P&key=a3A68BBDuL5P&roomPin=465796"
}

GET /conversations

Retrieves a list of the active conversations.

Request

The request is a GET request and does not contain any parameters.

GET /ininvid/v1/conversations HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • <root> - (array) A collection of Conversation objects
    • conversationId - (string) The GUID used to identify the conversation. The format will always be XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
    • interactionId - (long) The interaction ID associated with the conversation
    • room - (object) The object containing data about the Vidyo room
      • roomId - (int) The Vidyo room ID
      • roomKey - (string) The Vidyo room key
      • name - (string) The name of the Vidyo room
      • extension - (string) The extension of the Vidyo room
      • pin - (string) The pin of the Vidyo room
      • roomUrl - (string) The Vidyo room URL. This is the direct room URL, NOT the guest join URL.
      • createdDateTime (datetime) The timestamp of when the room was created
    • attributeDictionary - (object) A collection of properties (key/value pairs) with the tracked attributes on the interaction. The property name is the name of the attribute and the property value is the value of the attribute.
    • scopedQueueName - (string) The scoped queue name of the CIC queue that the interaction is currently residing on. This will be a workgroup queue while the interaction is waiting for ACD assignement and will be a user queue after the interaction has been assigned (note that this value is set to the user queue while the interaction is alerting the user).
    • isConversationMuted - (bool) true indicates that the interaction has been put on hold and all participants in the room have been muted. false indicates that the interaction is not on hold.
    • initializationParameters - (object) The initialization parameters used to reconstitute the conversation. This is only intended to be used internally by the integration service.
    • userOwner - (string) The CIC username of the user that the interaction is assigned to. This value differs from scopedQueueName in that is only set when the user picks up the interaction and it enters a connected state; it will be empty otherwise. This can be used to identify if an agent has been assigned to the interaction to determine when it is appropriate to join the customer to the room.
    • roomUrl - (string) The base URL to join the Vidyo room. This is loaded with all of the necessary parameters to auto-join except for guestName. The display name for a participant should be appended to the querystring as "&guestName=<display name>".

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response showing one conversation:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 18:28:21 GMT
Link → </conversations.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

[
	{
		"conversationId": "9b017eca-d461-d489-9f46-8d54c6c54455",
		"interactionId": 2001480066,
		"room": {
			"roomId": 4258,
			"roomKey": "5lWgL2qvr7kf",
			"name": "Vidyo Integration Room (923462293)",
			"extension": "923469793",
			"pin": "804580",
			"roomUrl": "http://vidyoserver.com/flex.html?roomdirect.html&key=5lWgL2qvr7kf",
			"createdDateTime": "2015-01-22T11:28:21.8260894-07:00"
		},
		"attributeDictionary": {
			"eic_RemoteName": "Vidyo chat from postman",
			"video_ConversationId": "9b017eca-d489-4fc4-9f46-8d54c6c54455",
			"video_RoomId": "4258",
			"video_RoomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWgL2qvr7kf&key=5lWHd7ngvr7kf&roomPin=807580",
			"video_LastAgentToScreenPop": "",
			"eic_CallId": "2001480066",
			"eic_CallIdKey": "200148006640150122",
			"eic_CallStateString": "ACD - Wait Agent",
			"eic_WorkgroupName": "Support"
		},
		"scopedQueueName": "Workgroup Queue:Support",
		"isConversationMuted": false,
		"initializationParameters": {
			"mediaType": 2,
			"initialState": 5,
			"scopedQueueName": "Workgroup Queue:support",
			"additionalAttributes": {
				"eic_RemoteName": "Vidyo chat from postman",
				"video_ConversationId": "9b017eca-d489-4fc4-9f46-8d54c6c54455",
				"video_RoomId": "4258",
				"video_RoomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWHd2qvr7kf&key=5lWgL2qvr7kf&roomPin=804580"
			},
			"interactionId": 0
		},
		"userOwner": "",
		"roomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWHd2qvr7kf&key=5lWgL2qvr7kf&roomPin=804580"
	}
]

GET /conversations/{conversationId}

Retrieves a conversation

Request

The request is a GET request and contains the following parameters:

  • conversationId - (string) The GUID used to identify the conversation. The format will always be XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

    GET /ininvid/v1/conversations/9b017eca-d461-d489-9f46-8d54c6c54455 HTTP/1.1 Host: integrationserver.com:80 Content-Type: application/json Cache-Control: no-cache

Response

The response contains a body with the following members:

  • conversationId - (string) The GUID used to identify the conversation. The format will always be XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  • interactionId - (long) The interaction ID associated with the conversation
  • room - (object) The object containing data about the Vidyo room
    • roomId - (int) The Vidyo room ID
    • roomKey - (string) The Vidyo room key
    • name - (string) The name of the Vidyo room
    • extension - (string) The extension of the Vidyo room
    • pin - (string) The pin of the Vidyo room
    • roomUrl - (string) The Vidyo room URL. This is the direct room URL, NOT the guest join URL.
    • createdDateTime (datetime) The timestamp of when the room was created
  • attributeDictionary - (object) A collection of properties (key/value pairs) with the tracked attributes on the interaction. The property name is the name of the attribute and the property value is the value of the attribute.
  • scopedQueueName - (string) The scoped queue name of the CIC queue that the interaction is currently residing on. This will be a workgroup queue while the interaction is waiting for ACD assignement and will be a user queue after the interaction has been assigned (note that this value is set to the user queue while the interaction is alerting the user).
  • isConversationMuted - (bool) true indicates that the interaction has been put on hold and all participants in the room have been muted. false indicates that the interaction is not on hold.
  • initializationParameters - (object) The initialization parameters used to reconstitute the conversation. This is only intended to be used internally by the integration service.
  • userOwner - (string) The CIC username of the user that the interaction is assigned to. This value differs from scopedQueueName in that is only set when the user picks up the interaction and it enters a connected state; it will be empty otherwise. This can be used to identify if an agent has been assigned to the interaction to determine when it is appropriate to join the customer to the room.
  • roomUrl - (string) The base URL to join the Vidyo room. This is loaded with all of the necessary parameters to auto-join except for guestName. The display name for a participant should be appended to the querystring as "&guestName=<display name>".

The response will return one of the following status codes:

  • 200 OK
  • 400 <error message>
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 18:28:21 GMT
Link → </conversations.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "conversationId": "9b017eca-d461-d489-9f46-8d54c6c54455",
    "interactionId": 2001480066,
    "room": {
        "roomId": 4258,
        "roomKey": "5lWgL2qvr7kf",
        "name": "Vidyo Integration Room (923462293)",
        "extension": "923469793",
        "pin": "804580",
        "roomUrl": "http://vidyoserver.com/flex.html?roomdirect.html&key=5lWgL2qvr7kf",
        "createdDateTime": "2015-01-22T11:28:21.8260894-07:00"
    },
    "attributeDictionary": {
        "eic_RemoteName": "Vidyo chat from postman",
        "video_ConversationId": "9b017eca-d489-4fc4-9f46-8d54c6c54455",
        "video_RoomId": "4258",
        "video_RoomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWgL2qvr7kf&key=5lWHd7ngvr7kf&roomPin=807580",
        "video_LastAgentToScreenPop": "",
        "eic_CallId": "2001480066",
        "eic_CallIdKey": "200148006640150122",
        "eic_CallStateString": "ACD - Wait Agent",
        "eic_WorkgroupName": "Support"
    },
    "scopedQueueName": "Workgroup Queue:Support",
    "isConversationMuted": false,
    "initializationParameters": {
        "mediaType": 2,
        "initialState": 5,
        "scopedQueueName": "Workgroup Queue:support",
        "additionalAttributes": {
            "eic_RemoteName": "Vidyo chat from postman",
            "video_ConversationId": "9b017eca-d489-4fc4-9f46-8d54c6c54455",
            "video_RoomId": "4258",
            "video_RoomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWHd2qvr7kf&key=5lWgL2qvr7kf&roomPin=804580"
        },
        "interactionId": 0
    },
    "userOwner": "",
    "roomUrl": "http://servername.com/vidyoweb/?portalUri=http%3a%2f%2fvidyoserver.com%2fflex.html%3froomdirect.html%26key%3d5lWHd2qvr7kf&key=5lWgL2qvr7kf&roomPin=804580"
}

DELETE /conversations/{conversationId}

Deletes a conversation

Request

The request is a GET request and contains the following parameters:

  • conversationId - (string) The GUID used to identify the conversation. The format will always be XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Example Request:

DELETE /ininvid/v1/conversations/9b017eca-d461-d489-9f46-8d54c6c54455 HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response does not contain a body and will return one of the following status codes:

  • 204 Conversation Deleted
  • 400 <error message>
  • 401 Unable to delete conversation
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Length → 0
Content-Type → text/html
Date → Thu, 22 Jan 2015 22:57:20 GMT
Server → Microsoft-HTTPAPI/2.0

VidyoService

The Vidyo Service contains resources to interact with the Vidyo server; this service simply wraps the Vidyo Guest and Admin SOAP APIs into a single streamlined REST API. The CoreServiceLib project can be found in the repo at /src/VidyoIntegration/VidyoComponents/VidyoService/

GET /vidyoservice/info

The /vidyoservice/info resource returns information about the Vidyo Service.

Request

The request is a GET request and does not contain any parameters.

GET /ininvid/v1/vidyoservice/info HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • requestCounts - (array) This is an array of properties indicating how many times each resource has been requested. The property name is the concatenated string of the request method (get, post, delete, etc.) and the short resource path.

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 17:41:17 GMT
Link → <info.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "requestCounts": {
        "get /rooms/{roomId}/participants": 67833,
        "get /vidyoservice/info": 3,
        "post /rooms": 4,
        "delete /rooms/{roomId}": 5
    }
}

GET /vidyoservice/info/routes

Returns information about the available routes to resources in the Vidyo Service.

Request

The request is a GET request and does not contain any parameters.

GET /ininvid/v1/vidyoservice/info/routes HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • <root> - (array) An array of service info objects
    • serviceName - (string) The name of the service
    • routes - (array) An array of route info
      • method - (string) The HTTP method for the request
      • path - (string) The relative path to the resource

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 18:01:39 GMT
Link → </routes.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

[
	{
		"serviceName": "VidyoIntegration.VidyoService.VidyoRequestRouter",
		"routes": [
			{
				"method": "POST",
				"path": "/ininvid/v1/rooms"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/rooms"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/rooms/{roomId}"
			},
			{
				"method": "DELETE",
				"path": "/ininvid/v1/rooms/{roomId}"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/rooms/{roomId}/participants"
			},
			{
				"method": "DELETE",
				"path": "/ininvid/v1/rooms/{roomId}/participants/{participantId}"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/rooms/{roomId}/participantCount"
			},
			{
				"method": "PATCH",
				"path": "/ininvid/v1/rooms/{roomId}/actions/{participantId}"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/vidyoservice/info"
			},
			{
				"method": "GET",
				"path": "/ininvid/v1/vidyoservice/info/routes"
			}
		]
	}
]

POST /rooms

Creates a new Vidyo room.

Request

The request is a GET request and does not contain any parameters.

Example request:

POST /ininvid/v1/rooms HTTP/1.1
Host: integrationserver.com:80
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • roomId - (int) The Vidyo room ID
  • roomKey - (string) The Vidyo room key
  • name - (string) The name of the Vidyo room
  • extension - (string) The extension of the Vidyo room
  • pin - (string) The pin of the Vidyo room
  • roomUrl - (string) The Vidyo room URL. This is the direct room URL, NOT the guest join URL.
  • createdDateTime (datetime) The timestamp of when the room was created

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 23:28:07 GMT
Link → </rooms.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "roomId": 2537,
    "roomKey": "MB481hAY1rmQ",
    "name": "Vidyo Integration Room (987641625)",
    "extension": "987641625",
    "pin": "703847",
    "roomUrl": "http://vidyoserver.com/flex.html?roomdirect.html&key=MB481hAY1rmQ",
    "createdDateTime": "2015-01-22T16:28:08.4358512-07:00"
}

GET /rooms

Gets the list of rooms held in the service's cache. To get a room that is not held in cache, use GET /rooms/{roomId}.

Request

The request is a GET request and does not contain any parameters.

Example request:

GET /ininvid/v1/vidyoservice/rooms HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • roomId - (int) The Vidyo room ID
  • roomKey - (string) The Vidyo room key
  • name - (string) The name of the Vidyo room
  • extension - (string) The extension of the Vidyo room
  • pin - (string) The pin of the Vidyo room
  • roomUrl - (string) The Vidyo room URL. This is the direct room URL, NOT the guest join URL.
  • createdDateTime (datetime) The timestamp of when the room was created

The response will return one of the following status codes:

  • 200 OK
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 23:28:07 GMT
Link → </rooms.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "roomId": 2537,
    "roomKey": "MB481hAY1rmQ",
    "name": "Vidyo Integration Room (987641625)",
    "extension": "987641625",
    "pin": "703847",
    "roomUrl": "http://vidyoserver.com/flex.html?roomdirect.html&key=MB481hAY1rmQ",
    "createdDateTime": "2015-01-22T16:28:08.4358512-07:00"
}

GET /rooms/{roomId}

Gets a room with the given Vidyo room ID.

Request

The request is a GET request and requires the following parameters:

  • roomId - (int) The Vidyo room ID

Example request:

GET /ininvid/v1/vidyoservice/rooms/2537 HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • roomId - (int) The Vidyo room ID
  • roomKey - (string) The Vidyo room key
  • name - (string) The name of the Vidyo room
  • extension - (string) The extension of the Vidyo room
  • pin - (string) The pin of the Vidyo room
  • roomUrl - (string) The Vidyo room URL. This is the direct room URL, NOT the guest join URL.
  • createdDateTime (datetime) The timestamp of when the room was created

The response will return one of the following status codes:

  • 200 OK
  • 400 <error message>
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 23:28:07 GMT
Link → </rooms.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "roomId": 2537,
    "roomKey": "MB481hAY1rmQ",
    "name": "Vidyo Integration Room (987641625)",
    "extension": "987641625",
    "pin": "703847",
    "roomUrl": "http://vidyoserver.com/flex.html?roomdirect.html&key=MB481hAY1rmQ",
    "createdDateTime": "2015-01-22T16:28:08.4358512-07:00"
}

DELETE /rooms/{roomId}

Deletes a room with the given Vidyo room ID.

Request

The request is a GET request and requires the following parameters:

  • roomId - (int) The Vidyo room ID

Example request:

DELETE /ininvid/v1/vidyoservice/rooms/2537 HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response does not contain a body and will return one of the following status codes:

  • 204 Room deleted
  • 400 <error message>
  • 410 Unable to delete room
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Length → 0
Content-Type → text/html
Date → Thu, 22 Jan 2015 23:49:49 GMT
Server → Microsoft-HTTPAPI/2.0

GET /rooms/{roomId}/participants

Gets a list of participants in a room.

Request

The request is a GET request and requires the following parameters:

  • roomId - (int) The Vidyo room ID

Example request:

GET /ininvid/v1/rooms/2537/participants HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • <root> - (array) An array of participants
    • entityId - (int) The Vidyo entity ID. This is always 0.
    • participantId - (int) The Vidyo participantId
    • entityType - (string) The Vidyo entity type. This is always Member here
    • displayName - (string) The display name of the participant

The response will return one of the following status codes:

  • 204 Room deleted
  • 400 <error message>
  • 410 Unable to delete room
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Thu, 22 Jan 2015 23:58:52 GMT
Link → </participants.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

[
    {
        "entityId": 0,
        "participantId": 311,
        "entityType": "Member",
        "displayName": "Walter White"
    }
]

GET /rooms/{roomId}/participantCount

Gets the count of participants in a room. This is just a helper method and is equivalent to calling GET /rooms/{roomId}/participants and counting the number of results.

Request

The request is a GET request and requires the following parameters:

  • roomId - (int) The Vidyo room ID

Example request:

GET /ininvid/v1/rooms/2537/participantCount HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

Response

The response contains a body with the following members:

  • count - (int) The number of participants in the room

The response will return one of the following status codes:

  • 204 Room deleted
  • 400 <error message>
  • 410 Unable to delete room
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Type → application/json; charset=utf-8
Date → Fri, 23 Jan 2015 00:05:38 GMT
Link → </participantCount.xml>; rel="application/xml"
Server → Microsoft-HTTPAPI/2.0
Transfer-Encoding → chunked
Vary → Accept

{
    "count": 1
}

PATCH /rooms/{roomId}/actions/{participantId}

Performs an action on a participant in a room.

Request

The request is a PATCH operation and requires the following URL parameters:

  • roomId - (int) The Vidyo room ID
  • participantId - (int) The Vidyo participantId

The request body requires the following parameters:

  • action - (string) The action to perform
  • data - (string) Data associated with the action

The following action/data combinations are permitted:

  • action = MuteAudio, data = true to mute the participant's audio stream, data = false to unmute
  • action = MuteVideo, data = true to mute the participant's video stream, data = false to unmute
  • action = MuteBoth, data = true to mute both the participant's video and audio stream, data = false to unmute both

Example request:

PATCH /ininvid/v1/rooms/2358/actions/287 HTTP/1.1
Host: integrationserver.com:80
Content-Type: application/json
Cache-Control: no-cache

{
  "action":"MuteVideo",
  "data":"true"
}

Response

The response does not contain a body and will return one of the following status codes:

  • 204 Action performed
  • 400 <error message>
  • 500 <error message>

Example response:

Access-Control-Allow-Headers → Accept, Origin, Content-type
Access-Control-Allow-Methods → POST,GET
Access-Control-Allow-Origin → *
Content-Length → 0
Content-Type → text/html
Date → Fri, 23 Jan 2015 16:30:47 GMT
Server → Microsoft-HTTPAPI/2.0
Clone this wiki locally