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 credentials. You can find your API credentials 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; https://api.getcallsavvy.com/v1/‹resource URI›

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 credentials 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-->

Then customize and paste the following HTML code where you want the call button to appear

<button id="callservy_call_button" displayed_caller_id="optional-business-number-to-call-with" number_to_call="optional-number-call-including-country-code" > Call </button>

Your call button ID must be set to exactly callservy_call_button for the plugin to work. All calls initiated using the plugin will be queued to the selected department. To initiate a call to a specific phone number, simply set the destination number (including country code) using the number_to_call attribute on your call button. If there are multiple numbers assigned to your business, you can also specify which one to use as the caller ID using the displayed_caller_id attribute on your call button

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 https://api.getcallsavvy.com/v1/getSummary

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 https://api.getcallsavvy.com/v1/getDepartments

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 https://api.getcallsavvy.com/v1/getAgents

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 https://api.getcallsavvy.com/v1/getTickets

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 timestamp (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 given support-ticket. This endpoint is accessed by making a JSON Encoded HTTP POST request to https://api.getcallsavvy.com/v1/getTicketConversation

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 https://api.getcallsavvy.com/v1/createTicket

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 https://api.getcallsavvy.com/v1/replyTicket

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 https://api.getcallsavvy.com/v1/getCalls

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 timestamp (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 https://api.getcallsavvy.com/v1/getChats

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 timestamp (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 Messengers POST » /getMessangers

This API allows you to fetch a list of all requests your business received via messenges such as facebook, whatsapp, etc. This endpoint is accessed by making a JSON Encoded HTTP POST request to https://api.getcallsavvy.com/v1/getMessangers

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 timestamp (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 messenger 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 https://api.getcallsavvy.com/v1/sendSMS. Please note that successful messages sent using this API will be deducted from your available SMS balance.

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 https://api.getcallsavvy.com/v1/sendRobocall. Please note that successful calls initiated using this API will be deducted from your available local or international call units, depending on the call destination.

Request Body Parameters
call_type (string) (required) This is the type of call content to broadcast. 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.

Chatbot Response Request POST » ‹Your Callback URL›

Callsavvy will send the following URL-Form Encoded data to your webhook URL via HTTP POST each time a chatbot or auto-responder event needs to get response from your server;

POST data (url-form-encoded)
]
    "event": "chatbotCallback",
    "original_message":"‹The message content that triggered the bot",
    "sender_name":"‹The message sender's name›",
    "bot_name":"‹The name you set for the chatbot which triggered the event›",
    "department":"‹The name of the originating department if applicable›",
    "business_name":"‹Your business name on Callsavvy›"
]

A valid Text or HTML response expected from your server.

Ready to get started?

Sign-Up Now