Please enable JS

API

VEEDEEO API Documentation

This article describes the usage and features of the VEEDEEO API.

The VEEDEEO API enables the integration of our powerful video communications platform with applications and websites and brings rich interactive video call experiences to any browser based application.

If you have questions or need additional help with the API implementation, please contact our support team using your prefered channel: phone, email or Twitter.

API Usage

The VEEDEEO API enables to check the availability of VEEDEEO users - for a particular VEEDEEO Account or a particular user queue - and retrieve a video number that can be used to start a video call.

General Remarks

  • To use the VEEDEEO API you need to have an active VEEDEEO Account and a valid API Key
  • To get your API Key you need to contact support and open a API Key Request.
  • VEEDEEO users must be active for API in order to be considered in the API call.

Using Queues

A "queue" is a "tag" that can represent a specific characteristic of your VEEDEEO users or simply a group of VEEDEEO users.

Each VEEDEEO user can be assigned to one or more queues.

Queues can be used when calling the API to filter results to a specific set of users (i.e. you may want to filter users in the customer support department; or users in the support department that speak spanish;).

Examples of queues:

  • For departments: "support"; "sales"; "general";
  • For languange support: "en"; "sp";
  • For product expertise: "prod1"; "prod2"; ...

Queue names should not include each other. I.e.: you should not use queue "q-aaa" and queue "q-aa" because the later is included in the first queue code.

API Location

The VEEDEEO API is a REST webservice located at the following URL:

https://veedeeo.secure.force.com/services/apexrest/veedeeoapiREST

API URL Parameters

Parameter Usage Required? Format / Values
key API Key Yes String (18 char)
req API Request Code Yes getau - get user availability;
getvn - get video number;
vq Queue(s) No String (alphanumeric).
If you want to specify several queues, you need to separate each queue code with a semicolon (";") - i.e.: vq=sales;en

"getau" Request: Get User Availability

The "getau" request enables you to retrieve the user availability for a VEEDEEO Account, filtered by one or more queues (optional).

Sample API call - without queue filter:

https://veedeeo.secure.force.com/services/apexrest/veedeeoapiREST?key=[api_key]&req=getau

Sample API call - with queue filter:

https://veedeeo.secure.force.com/services/apexrest/veedeeoapiREST?key=[api_key]&req=getau&vq=sales
RETURN ON SUCCESS

If the webservice call is successful it will return a JSON string with:

  • The total number of users that fit the filter criteria (if any)
  • The total number of users that are online
  • The total number of users that are available to receive a call (users that are online and not in a video call)

Example of JSON return on success:

{
"available": 1,
"online": 2,
"total": 3
}
RETURN ON ERROR

If the webservice call is not successful it will return a JSON string with the error description. Possible error returns are:

  • Account not found or not active or unable to use service
  • Request not defined

Example of JSON return on error:

{
"error": "Account not found or not active or unable to use service"
}
WEBSERVICE USAGE

You can use this API call to decide if you want to show a "Start a Video Call" button or call to action in your website depending on the availability of your VEEDEEO users.

"getvn" Request: Get Video Number

The "getvn" request enables you to retrieve the video number you can use to start a video call. Note that this API call will only consider VEEDEEO users that are available (users are both online and not in a video call).

If there are more than one user available, the API call will return only one video number (at random).

Sample API call - with queue filter:

https://veedeeo.secure.force.com/services/apexrest/veedeeoapiREST?key=[api_key]&req=getvn&vq=sales
RETURN ON SUCCESS

If the webservice call is successful it will return a JSON string with a video number.

Example of JSON return on success:

{
"vnumber": "700001"
}
RETURN ON ERROR

If the webservice call is not successful it will return a JSON string with the error description. Possible error returns are:

  • No user available
  • No channels available
  • Account not found or not active or unable to use service
  • Request not defined

Example of JSON return on error:

{
"error": "No user available"
}
WEBSERVICE USAGE

You can use this API call to get the video number that the "Start a Video Call" button or call to action in your website should use to start a video call.

Call Video Number Using a Browser

You can easily start a video call to a video number using a WebRTC compatible browser (such as Google Chrome, Mozilla Firefox or Opera) using the VEEDEEO call page.

PARAMETERS FOR GUEST CALL
Parameter Usage Required? Format / Values
vn Video number Yes String
name Name No Name of person that is calling the video number

Example of video call url:

https://veedeeo.secure.force.com/veedeeoSpace?vn=700001&name=Mike

Implementation Example

You can find an example of the implementation of the VEEDEEO API at this link