API Documentation
Introduction
Callsavvy API is designed for developers to easily integrate Callsavvy on any application using any software programing technology or development platform
Our API attempts to conform to the RESTful design principles. You interact with the resources exposed through the API by accessing resource collection and element URIs using the HTTP POST or GET.
Access to our API is Freely available to all Callsavvy users. You will likely need access to a web developer or programmer (if you’re not one) to get the most use out of UfitPay API.
Obtaining Your API credentials
In order to interact with Callsavvy APIs, you will need your API credentails. You can find your API credentails under the API & Integration tab when you navigate to Settings -> Business Setup from from Callsavvy dashboard
For added security, we recommend you restrict access to your API credentials to only white-listed IP addresses and domains. You can do this under Whitelisted Domains
Authentication
All requests to Callsavvy API require authentication. Our API Authentication is implemented as HTTP Header Authentication over TLS (HTTPS).
To authenticate your request, you need to pass the following parameters as part of your HTTP request headers;
Public-Key: Your API Public Key
Private-Key: Your API Private Key
URL Format
Callsavvy API URL is made up of the Base URL and the Resource URI. A complete API URL will look like this;
Request Method
Our API accepts only JSON Encoded HTTP POST requests. Any other request method will not be recognized by our API
Below is a sample request to our balance enquiry API using cURL;
curl --request POST \
--url 'https://api.getcallsavvy.com/v1/getSummary' \
--header 'Public-Key: 1234567890' \
--header 'Private-Key: 33gTuienGR83HY32cGt' \
--header 'content-type: application/json'
--data '{"parameter":"value"}'
Response Format
Our API response (success or error) is returned in JSON data. Response codes are sent via the normal HTTP Response Code,
A success response from our server will look like this;
{
"resource": "getSummary",
"status":"success",
"data":{
"assigned_number": "123456",
"business_id": "ab9363nd8o3h"
}
}
An error response from our server will look like this;
{
"resource": "getSummary",
"status":"error",
"message":"Invalid API credentials"
}
Response Parameters
| resource (string) | This is the API resource being called |
| status (string) | This is status of the API call. |
| data (object) | This object holds the actual information returned by the API resource. The content of this parameter depends on which API resource URI is being called |
Sandbox Credentials
Feel free to use the following API credentails for development and testing purposes.
| Public Key | TEST-hdo76HDCGAjfig4jbnyUI4734BNDY |
| Private Key | TEST-934HDHD84JDVBPSW73BYjegh494WD9084NFUih34-9974r |
Inline Integrations
Embed Voice Call Inline
This resource allows you to integrate Callsavvy's VoIP technology on your app and be able to make phone calls from your application with little or no codding.
To generate a customized plugin for your app, Login to your Callsavvy Dashboard, Go to Settings then click on the API & Integrations tag
Sample Code
<!--Put this code just before the closing </body> tag on your page. Remember to replace your API credentails within the code -->
<script type="text/javascript">
(function(){
var s1=document.createElement("script"),s0=document.getElementsByTagName("script")[0];
s1.async=true;
s1.src='https://plugin.getcallsavvy.com/call/{Your API Key}?p&d={Destination Department UID}&c={Theme Color UID}';
s1.charset='UTF-8';
s1.setAttribute('crossorigin','*');
s0.parentNode.insertAdjacentElement("beforeend", s1);
})();
</script>
<!--End of Callsavvy Script-->
Embed Support Ticket Form Inline
This resource allows you to integrate Callsavvy's support ticket feature on your app, allowing your users to create new support requests directly from your application with little or no codding.
To generate a customized plugin for your app, Login to your Callsavvy Dashboard, Go to Settings then click on the API & Integrations tag
Sample Code
<!--Put this code where you’d like the support ticket widget to appear on your page. Remember to replace your API credentails within the code-->
<div id="callservy_ticket_widget_holder{Your API Key}"></div>
<!--Put this code just before the closing </body> tag on your page. Remember to replace your API credentails within the code-->
<script type="text/javascript">
(function(){
var s1=document.createElement("script"),s0=document.getElementsByTagName("script")[0];
s1.async=true;
s1.src='https://plugin.getcallsavvy.com/ticket/{Your API Key}?p&c=Z3JlZW4%3D';
s1.charset='UTF-8';
s1.setAttribute('crossorigin','*');
s0.parentNode.insertAdjacentElement("beforeend", s1);
})();
</script>
Embed Live Chat Inline
This resource allows you to integrate Callsavvy's live chat and chatbot on your app so your customers can chat you right from your application with no codding.
To generate a customized plugin for your app, Login to your Callsavvy Dashboard, Go to Settings then click on the API & Integrations tag
Sample Code
<!--Put this code just before the closing </body> tag on your page. Remember to replace your API credentails within the code-->
<script type="text/javascript">
(function(){
var s1=document.createElement("script"),s0=document.getElementsByTagName("script")[0];
s1.async=true;
s1.src='https://plugin.getcallsavvy.com/chat/{Your API Key Here}?p&c=Z3JlZW4%3D';
s1.charset='UTF-8';
s1.setAttribute('crossorigin','*');
s0.parentNode.insertAdjacentElement("beforeend", s1);
})();
</script>
RESTFul APIs
Get Business Summary POST » /getSummary
This API allows you to retrieve current status your business resource on Callsavvy. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| This resource requires no request body |
Sample success response (json)
{
"resource": "getSummary",
"status":"success",
"data": [{
"assigned_number": "‹Assigned Callsavvy business phone number›",
"account_status": "‹Current status of your business on Callsavvy›,"
"business_id": "‹Unique ID of your business on Callsavvy›",
"outbound_local_call_balance": "‹Available outbound local call minutes for the current month›",
"outbound_international_call_balance": "‹Available international outbound call minutes for the current month›",
"inbound_call_balance": "‹Available inbound call minutes for the current month›",
"sms_balance": "‹Available SMS units for the current month›"
}]
}
List Departments POST » /getDepartments
This API allows you to fetch a list of all departments created under your business. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| This resource requires no request body |
Sample success response (json)
{
"resource": "getDepartments",
"status":"success",
"data": [{
"department_id": "‹Unique ID of the department list item›",
"datetime": "‹Date and Time the chat was started›,"
"department_name": "‹The name of the department›",
"department_email": "‹Assigned email address›",
"department_agents": "‹Number of agents assigned to the department›"
}]
}
List Agents POST » /getAgents
This API allows you to fetch a list of all agents created under your business. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| This resource requires no request body |
Sample success response (json)
{
"resource": "getAgents",
"status":"success",
"data": [{
"agent_id": "‹Unique ID of the agent list item›",
"agent_name": "‹The agent's full name›",
"agent_email": "‹The agent's email address›"
}]
}
List Support Tickets POST » /getTickets
This API allows you to fetch a list of all requests your business received via support-ticket. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| department_id (string) | (optional) Pass a valid department ID here to only returned records from the department. |
| ticket_status (string) | (optional) Pass a valid ticket status here (New, Closed, Awaiting Agent Reply or Awaiting Customer Reply) to filter returned result by status. |
| sender_email (string) | (optional) Pass an email address here to filter returned result by sender'd email address. |
| datetime (string) | (optional) Pass a valid timestam (YYYY-MM-DD HH:MM:SS, YYYY-MM-DD or YYYY-MM) to only returned records from a given period. |
Sample success response (json)
{
"resource": "getTickets",
"status":"success",
"data": [{
"ticket_id": "‹Unique ID of the ticket list item›",
"datetime": "‹Date and Time the ticket was created›,"
"ticket_status": "‹Status of the ticket (New, Closed, Awaiting Agent Reply or Awaiting Customer Reply)›",
"last_reply": "‹Date and Time the ticket was last replied by agent or sender›",
"subject": "‹Subject of the ticket›",
"sender_name": "‹Sender's name›",
"sender_email": "‹Sender's email address›",
"department_id": "‹Unique ID of the ticket department›"
}]
}
Get Ticket Conversation POST » /getTicketConversation
This API allows you to fetch all conversation for a givin support-ticket. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| ticket_id (string) | (required) Pass the ID of the Ticket you want to return conversations history for. |
Sample success response (json)
{
"resource": "getTicket",
"status":"success",
"data": [{
"conversation_id": "‹Unique ID of the conversation list item›",
"datetime": "‹Date and Time of the message›,"
"message": "‹The message body. This may contain HTML›",
"from_agent": "‹This will be 'true' if the message was sent by an agent, otherwise 'valu'false'›",
"agent_name": "‹Full Name of the agent who sent the message. Value will be empty if not sent by agent›",
"files": "‹Comma separated list of attached file URLs (if any)›",
}]
}
Create New Ticket POST » /createTicket
This API allows you to create a new support-ticket on behalf of a customer. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| department_id (string) | (required) Pass the department ID you wish to create a ticket under. |
| sender_name (string) | (required) This is the customer's name to use with the ticket. |
| sender_email (string) | (required) This is the customer's email address to use with the ticket. |
| ticket_subject (string) | (required) This is the subject of the ticket. |
| ticket_message (string) | (required) This is the body of the ticket. |
Sample success response (json)
{
"resource": "createTicket",
"status":"success",
"data": {
"ticket_id": "‹Unique ID of the new ticket›",
"subject": "‹Subject of the ticket›",
"sender_name": "‹Sender's name›",
"sender_email": "‹Sender's email address›",
}
}
Add Ticket Reply POST » /replyTicket
This API allows you to add a new response to an existing support-ticket. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| ticket_id (string) | (required) Pass the department ID you wish to create a ticket under. |
| replying_agent_id (string) | (optional) Pass a valid agent ID here if this response is from one of your agents or leave it empty if the response is from the customer. |
| response_date (string) | (required) This is the date and time of the reply (YYYY-MM-DD HH:MM:SS). |
| response_message (string) | (required) This is the body of the ticket response. |
Sample success response (json)
{
"resource": "replyTicket",
"status":"success",
"data": [
"conversation_id": "‹Unique ID of the new conversation item›",
"new_status": "‹The new status of the ticket being responded to›",
}
}
List Calls POST » /getCalls
This API allows you to fetch a list of all calls your business made or received. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| department_id (string) | (optional) Pass a valid department ID here to only returned records from the department. |
| call_direction (string) | (optional) Pass a valid call direction here (Incoming or Outgoing) to filter returned result by direction. |
| datetime (string) | (optional) Pass a valid timestam (YYYY-MM-DD HH:MM:SS, YYYY-MM-DD or YYYY-MM) to only returned records from a given period. |
Sample success response (json)
{
"resource": "getCalls",
"status":"success",
"data": [{
"call_id": "‹Unique ID of the call list item›",
"datetime": "‹Date and Time the call was initiated or received›,"
"direction": "‹Direction of the call (Incoming or Outgoing)›",
"duration": "‹Duration of the call in seconds›",
"caller": "‹The number that was called or called your business ›",
"recording_url": "‹Call recording audio file URL if available›",
"department_id": "‹Unique ID of the call department›"
}]
}
List Chats POST » /getChats
This API allows you to fetch a list of all requests your business received via live-chat. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| department_id (string) | (optional) Pass a valid department ID here to only returned records from the department. |
| datetime (string) | (optional) Pass a valid timestam (YYYY-MM-DD HH:MM:SS, YYYY-MM-DD or YYYY-MM) to only returned records from a given period. |
Sample success response (json)
{
"resource": "getChats",
"status":"success",
"data": [{
"chat_id": "‹Unique ID of the chat list item›",
"datetime": "‹Date and Time the chat was started›,"
"chat_status": "‹Status of the chat (Engaged or Waiting)›",
"visitor_name": "‹Visitor's name›",
"visitor_email": "‹Visitor's email address›",
"visitor_phone": "‹Visitor's phone number›",
"department_id": "‹Unique ID of the chat department›"
}]
}
List Messangers POST » /getMessangers
This API allows you to fetch a list of all requests your business received via messanges such as facebook, whatsapp, etc. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| department_id (string) | (optional) Pass a valid department ID here to only returned records from the department. |
| datetime (string) | (optional) Pass a valid timestam (YYYY-MM-DD HH:MM:SS, YYYY-MM-DD or YYYY-MM) to only returned records from a given period. |
Sample success response (json)
{
"resource": "getMessangers",
"status":"success",
"data": [{
"messanger_id": "‹Unique ID of the messanger list item›",
"datetime": "‹Date and Time the chat was started›,"
"chat_status": "‹Status of the chat (Engaged or Waiting)›",
"visitor_name": "‹Visitor's name›",
"channel": "‹What channel the chat was initiated from (eg facebook, whatsapp, etc)›",
"visitor_phone": "‹Visitor's phone number (if availabe)›",
"department_id": "‹Unique ID of the chat department›"
}]
}
Send Bulk SMS POST » /sendSMS
This API allows you to send outbound bulk SMS message from your account through a third-party application. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| sender_id (string) | (optional) This is the message sender to be displayed on the recipient's phone. If not supplied, the sendre ID configured on your business settings will be used. |
| recipient (string) | (required) Pass the recipient's phone number (in international format). Multiple recipients can be separated with commas (eg +2240099887,+447989987) |
| message (string) | (required) This is the message content to be sent. Standard GSM SMS pagination rules applies. |
Sample success response (json)
{
"resource": "sendSMS",
"status":"success",
"data": [
"message_id": "bj693csvc3o3epnw",
"cost": "4",
"status": "sent | queued | failed"
}
}
Send Robocalls or Voice Message POST » /sendRobocall
This API allows you to initiate outbound Robocalls or send voice messages from your account through a third-party application. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| call_type (string) | (required) This is the type of call content to broadcase. Supported values are Pre-recorded-Audio or Text-2-Speech. |
| recipient (string) | (required) Pass the recipient's phone number (in international format). Multiple recipients can be separated with commas (eg +2240099887,+447989987) |
| message (string) | (required) This is the content to be played to the call recipients when they answer the call. This should be a valid MP3 audio file URL (if call_type is Pre-recorded-Audio) or message to be read out in English (if call_type is Text-2-Speech). |
| duration (string) | (required) This is the duration of the call in minutes. This must be a numeric value. If your call content is shorter than the specified duration, the message will be played in loop until timeout. |
Sample success response (json)
{
"resource": "sendRobocall",
"status":"success",
"data": [
"message_id": "bj693csvc3o3epnw",
"cost": "12",
"status": "sent | queued | failed"
}
}
Callsavvy Webhooks
Caller Information POST » ‹Your Callback URL›
Callsavvy will send the following JSON data to your webhook URL via HTTP POST each time a call is received by your business;
POST data (json)
{
"event": "callerInformation",
"call_department":"‹ID of the department being called›",
"caller_number":"‹Caller's phone number›",
"call_status":"routing"
}
Your server is expected to respond with the following json data
{
"status": "success",
"caller_name":"‹Caller name to display on the call screen›",
"caller_email":"‹Caller's email address›",
"customer_info":"‹Any custom information you want to display on the call screen›"
}
Call Summary POST » ‹Your Callback URL›
Callsavvy will send the following JSON data to your webhook URL via HTTP POST at the end of each call;
POST data (json)
{
"event": "callSummary",
"call_direction":"‹Direction of the call (Incoming or Outgoing)›",
"call_department":"‹ID of the department being called›",
"caller_number":"‹Caller's phone number›",
"recording_url":"‹URL to the call recording file›",
"call_duration":"‹Duration of the call in seconds›",
"call_status":"finished"
}
No response is expected from your server.
New Ticket POST » ‹Your Callback URL›
Callsavvy will send the following JSON data to your webhook URL via HTTP POST each time a new ticket is opened to your business;
POST data (json)
{
"event": "newTicketOpened",
"ticket_id":"‹ID of the new ticket›",
"ticket_department":"‹ID of the ticket department›",
"ticket_subject":"‹Subject of the ticket›",
"sender_email":"‹The sender's email address›",
"ticket_status":"New"
}
No response is expected from your server.
Ticket Escalation POST » ‹Your Callback URL›
Callsavvy will send the following JSON data to your webhook URL via HTTP POST each time a ticket escalated;
POST data (json)
{
"event": "ticketEscalated",
"ticket_id":"‹ID of the escalated ticket›",
"ticket_department":"‹ID of the ticket department›",
"last_ticket_reply":"‹Date and Time ticket was last replied (YYYY-MM-DD HH:MM:SS)›",
"ticket_subject":"‹Subject of the ticket›",
"sender_email":"‹The sender's email address›",
"ticket_status":"‹Status of the ticket›"
}
No response is expected from your server.
New Chat POST » ‹Your Callback URL›
Callsavvy will send the following JSON data to your webhook URL via HTTP POST each time a visitor starts a new live-chat with your business;
POST data (json)
{
"event": "newChat",
"chat_department":"ID of the chat department›",
"visitor_name":"‹The visitor's name›",
"visitor_email":"‹The visitor's email address›",
"visitor_phone":"‹The visitor's phone number›"
}
No response is expected from your server.
Ready to get started?
Sign-Up Now
