If you are using the last version of Vivocha click here to access the documentation site

If you are using the last version of Vivocha click here to access the documentation site
Back to VIVOCHA homepage ------ See our FAQ's

Skip to end of metadata
Go to start of metadata

If you are using the last version of Vivocha click here to access the documentation site

Vivocha offers a REST API to access to the main features offered by the platform.

With these APIs you can subscribe your webhooks to the vivocha events, request new contacts bypassing the client interface, set a custom webservice for checking the agents availability, or simply get infos about pending contacts and current status.

Base URL


Account services

Subscribe to CTI Events

Unsubscribe to CTI Events

Register Media Webservice

Unregister Media Webservice

Contact services

Get Contact Info

Send Message

Generic services

Get Version


Reports on Contacts, Visitors, Services, Agents, etc.


The Vivocha REST API service requires to be authenticated in order to make requests.

There are two way to do authentication:

  • pass your credentials on each REST request using a custom header in your HTTP(S) request (highly recommended).
  • using a session id obtained from the response header Set-Cookie when you sending your credentials to the login url (GET or POST).

The authentication params

The authentication params are necessary to make a secure access to all Vivocha services. They are essentially composed by the following data:

  • Vivocha User ID.
  • Vivocha User Password.
  • Current Unix Timestamp (must not have a greater difference than 10 minutes from Vivocha servers, so keep your system clock synchronized).

The authentication params are 3 and are generated in this way:

  • auth: md5( Vivocha User ID + md5( Vivocha User Password ) + Current Timestamp )
  • uid: Vivocha User ID
  • ts: Current Timestamp

Authentication with custom header

To authenticate your request you have to specify the custom "x-vvc-auth" header with the authentication object.

The authentication object is a simple JSON object with the authentication parameters described in the previous paragraph (auth, uid, ts). 

Example of REST HTTP request with x-vvc-auth header:

Host: www.vivocha.com
Accept: application/json
x-vvc-auth: {"auth":"34531fbf801d47c27f13c99c29c5fdfb","ts":1362043907983,"uid":"vivocha"}

Authentication with login url

To authenticate using the simple login you have to use the simple login url used to authenticate to the Vivocha web interface (Dashboard or Agent Desktop):


The login url accepts GET and/or POST HTTP(S) requests with the authentication params in order to create a session

So must simply make and HTTTP request to this url passing your auth params into the querystring or body (depending on the type of request), i.e.:


If your authentication parametesr are correctly verificate you'll obtain a HTTP 302 response that redirects you to the Vivocha dashboard.

You could ignore the redirection, you have only to get the vvcsid cookie value from the HTTP response header in order to use it in all the subsequents requests to the Vivocha REST API.

Login response headers

HTTP/1.1 302 Moved Temporarily
Server: nginx
Date: Thu, 28 Feb 2013 12:10:50 GMT
Content-Type: text/html
Set-Cookie: vvcsid=512f494ace9426a230000026; domain=vivocha.com; path=/; expires=Fri, 01 Mar 2013 00:10:50 GMT
Location: https://www.vivocha.com/a/vivocha/dash/


Example of REST HTTP request with the session id (vvcsid) specified in your request headers:

Host: www.vivocha.com
Cookie: vvcsid=512f2ef4ce9426a230000026

  • No labels