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 when you navigate to Settings -> API & Integration from from Callsavvy workplace. You need to be logged in as an Admin to access API credentials.
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 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 -> API & Integrations
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 -> API & Integrations
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 -> API & Integrations
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>
Embed Video Call Inline
This resource allows you to integrate Callsavvy's video meet feature on your app or website so your customers can initiate an instant video meet with your team right from your application with no codding.
To generate a customized plugin for your app, Login to your Callsavvy Dashboard, Go to Settings -> API & Integrations
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/video/{Your API Key Here}?p&c=Z3JlZW4%3D';
s1.charset='UTF-8';
s1.setAttribute('crossorigin','*');
s0.parentNode.insertAdjacentElement("beforeend", s1);
})();
</script>
Embed Calendar Inline
This resource allows you to integrate your business calendar on your app or website so your customers can schedule events with your business right from your application with no codding.
To generate a customized plugin for your app, Login to your Callsavvy Dashboard, Go to Settings -> API & Integrations
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/calendar/{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›",
"department_name": "‹The name of the department›",
"department_email": "‹Assigned email address›",
"department_agents": "‹Number of agents assigned to the department›"
}]
}
List Request Categories POST » /getCategories
This API allows you to fetch a list of all request categories 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": "getCategories",
"status":"success",
"data": [{
"category_id": "‹Unique ID of the category list item›",
"category_name": "‹The name of the category›"
}]
}
List Users 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 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
| 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. |
| category (string) | (optional) Pass a valid category ID here to only returned records belonging to the category. |
| 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)›",
"category": "‹Category assigned to the call›",
"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 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 Socials 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
| 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 SMS Message 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 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 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"
}
}
Send WhatsApp Message POST » /sendWhatsapp
This API allows you to send outbound WhatsApp messages from your account using any of your WhatsApp channels. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| uid (string) | (required) This is the UID fo the WhatsApp channel to send the message from. This can be gotten from the device under Settings -> Social Integrations . |
| recipient (string) | (required) Pass the recipient's WhatsApp number (in international format). Multiple recipients can be separated with commas (eg +2240099887,+447989987). You can can pass up-to 30 recipients with each API call. |
| message (string) | (required) This is the message content to be sent. |
Sample success response (json)
{
"resource": "sendWhatsapp",
"status":"success",
"data": {
"status": "sent | queued | failed"
}
}
List Virtual Meetings POST » /listMeetings
This API allows you to fetch a list of all virtual meetings created under your business. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| datetime (string) | (optional) Pass a valid timestamp (YYYY-MM-DD or YYYY-MM) to only returned meetings created within a given period. |
Sample success response (json)
{
"resource": "listMeetings",
"status":"success",
"data": [{
"meeting_id": "Tj6so93csvc3o3e834",
"title": "30 minutes call with Henry Ford",
"datetime": "2024-03-13 15:00:48",
"status": "Not Started | Started | Ended"
}]
}
Get Virtual Meeting POST » /getMeeting
This API allows you to fetch details of a given virtual meetings created under your business. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| meeting_id (string) | (required) This is the unique ID of the meeting to fetch. |
Sample success response (json)
{
"resource": "getMeeting",
"status":"success",
"data": {
"meeting_id": "Tj6so93csvc3o3e834",
"title": "30 minutes call with Henry Ford",
"datetime": "2024-03-13 15:00:48",
"host_agent_id": "3dv630v66v9w",
"start_link": "https://meet.getcallsavvy.com/meeting/Tj6so93csvc3o3e834?s=dv8683vydc739gsc",
"join_link": "https://meet.getcallsavvy.com/meeting/Tj6so93csvc3o3e834",
"status": "Not Started | Started | Ended"
]
}
Create Virtual Meeting POST » /createMeeting
This API allows you to create virtual meetings under your business. This endpoint is accessed by making a JSON Encoded HTTP POST request to
| Request Body Parameters | |
| title (string) | (required) This is the title or caption for the meeting. |
| host_agent_id (string) | (optional) Pass a valid agent_id to assign the dashboard host control features and rights to the user. |
Sample success response (json)
{
"resource": "createMeeting",
"status":"success",
"data": {
"meeting_id": "Tj6so93csvc3o3e834",
"title": "30 minutes call with Henry Ford",
"host_agent_id": "3dv630v66v9w",
"start_link": "https://meet.getcallsavvy.com/meeting/Tj6so93csvc3o3e834?s=dv8683vydc739gsc",
"join_link": "https://meet.getcallsavvy.com/meeting/Tj6so93csvc3o3e834",
"status": "Not Started"
]
}
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
