API Documentation

Introduction

Callservy API is designed for developers to easily integrate Callservy 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 Callservy 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 Callservy 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 Callservy 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 Callservy 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

Callservy API URL is made up of the Base URL and the Resource URI. A complete API URL will look like this; https://api.callservy.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.callservy.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


Available API Resources

Get Business Summary POST » /getSummary

This API allows you to retrieve current status your business resource on Callservy. This endpoint is accessed by making a JSON Encoded HTTP POST request to https://api.callservy.com/v1/getSummary

Request Body Parameters
This resource requires no request body

Sample success response (json)
{
    "resource": "getSummary",
    "status":"success",
    "data": [{
       "assigned_number": "‹Assigned business Callservy phone number›",
       "account_status": "‹Current status of your business on Callservy›,"
       "business_id": "‹Unique ID of your business on Callservy›",
       "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.callservy.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.callservy.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.callservy.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 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 https://api.callservy.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.callservy.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.callservy.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 requests your business received via live-chat. This endpoint is accessed by making a JSON Encoded HTTP POST request to https://api.callservy.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 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›",
       "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.callservy.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 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 https://api.callservy.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 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 SMS POST » /sendSMS

This API allows you to send outbound 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.callservy.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.00",
       "status": "sent | queued | failed"
    }
}


Callservy Webhooks

Caller Information POST » ‹Your Callback URL›

Callservy 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›

Callservy 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›

Callservy 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›

Callservy 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›

Callservy 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