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.
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:
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
Example of REST HTTP request with the session id (vvcsid) specified in your request headers: