Help CenterThis document refers to older versions of API endpoints that may be deprecated now or in the future, and should be viewed as a historical reference only. Please refer to our official API Documentation website for the most accurate information.
Mango Voice provides the following documentation so that companies can easily and effectively integrate Mango Voice features into their own systems.
The documentation is divided into three categories:
Global APIs
Global APIs allow companies to access data relating to their entire PBX.
Learn more here
User APIs
User APIs allow companies to access data for a particular user that is part of their PBX.
Interactive Phone Platform
This Interactive Phone Platform documentation instructs companies on how to create their own API in order to integrate Mango Voice functionality into their own systems
Global PBX API
This API category uses unique tokens to authenticate requests. Using the methods in the Global API category, one can access any data for the entire PBX. Whereas the User API's will only allow access to data pertaining to that user.
Before using the Mango Voice Global APIs:
· Contact Mango Voice support to activate your API access.
· Upon activation Mango Voice will provide three unique identifier tokens for your PBX (labeled ident1, ident2, and ident3 respectively)
· These tokens must be used for any request to the Mango Voice Global APIs
Important: Tokens must be kept confidential. Exposing tokens to the public may result in data theft, loss, or corruption.
Learn about Global Authentication here
Global Authentication
Global Authentication uses 3 unique "identifier" tokens
First Steps
· Contact Mango Voice support to enable Integrations.
· Upon enabling, go to the Mango Voice Admin portal > Integrations > Authorization
· Generate auth token: ident1, ident2, and ident3 respectively- These will be returned as one combined auth token.
· These tokens must be used for any request to the Mango Voice Global APIs
Important: Tokens must be kept confidential. Exposing tokens to the public may result in data theft, loss, or corruption.
Note: You can remove and regenerate auth tokens at any time if you feel your auth tokens have been compromised.
Call Logs (CDR)
The Call Detail Record (CDR) API provides Mango Voice customers with access to the call logs and call recordings for their PBX.
First Steps
· Activate API for your PBX- Contact Mango Voice support to activate API access for your PBX. API access is granted per PBX.
· Obtain authorization credentials from Mango Voice- Mango Voice will supply you with 3 unique ident values. These values will authenticate all API requests to MangoVoice.
· Test and Validate API.
API Functionality
With this API users can:
· List CDRs for their PBX
· Get a count of CDRs for their PBX
· Get call recordings (if enabled)
Availability
· CDRs are available for up to 12 months (default value)
· Call Recordings are available for up to 6 months (default value)
Call Recordings
· Call recordings are made available through a temporary URL that may be used for up to 300 seconds.
· A new temporary URL may be retrieved by calling the API again.
List Call Detail Records
Purpose:
To return a list CDRs for a PBX (defaults to the last 30 days)
Request URL:
https://api.mangovoice.com/api/v1/cdr/<ident1>/<ident2>/<ident3>/list
*Replace ident1, ident2, and ident3 with the tokens provided by Mango Voice (See authentication page for instructions on how to get these tokens)
GET Call Detail Record Count
Purpose:
Provides a count of all CDRs for a PBX (defaults to the last 30 days)
Request URL:
https://api.mangovoice.com/api/v1/cdr/<ident1>/<ident2>/<ident3>/count
Filtering Results:
The following filters can be applied to the request URL of the above API calls:
Filter by extension number
· /extension/<ext>
o ext = the extension number you want to search for (101, 203, etc…)
Filter by daterange:
· /daterange/<date>
o date = date you want to filter by in the following format:
§ start_date=YYYY-MM-DD HH:mm:ss&end_date=YYYY-MM-DD HH:mm:ss
o Can filter by just date (YYYY-MM-DD) or you can include time (YYYY-MM-DD HH:MM:SS)
o Date and time are in UTC
o If only given start date it filters from the start date provided up to the current date
o If only given the end date it gives the last 30 days of call records from the end date
Filter by call direction:
· /direction/<dir>
o dir = the direction of the call (outbound, inbound, or internal)
Filter for Call Recording:
· /recording/<id>
o id = the id of the CDR you want the recording for
o This filter can only be used the List request URL
Filter by Call UUID:
· /call_uuid = the unique id of the call
· This filter can only be used with the List request URL
· Also returns the call recording for the CDR
Format
Json- to display in Json use ?format=json
Visual- to display formatted visually use ?format=api
Returns:
· id - the id of the call
· callflow - what happened during the call
· conference_id - if a conference call this will be the id (otherwise an empty string)
· duration - total time of the call
· source_number - the number that made the call
· destination_number - the number that was called
· call_time - the time the call was made
· call_direction - type of call (inbound, outbound, internal)
· call_uuid - the unique id for the call
· src_ext - the extension that called
· dst_ext - the extension that answered
· call_status - answered, hangup, rejected, voicemail
· temp_recording_url - used to get the call recording
Voicemail
Overview:
The purpose of this API is to allow access to all voicemails for a given PBX.
Base URL:
https://apiuser.mangovoice.com/api/v2/vm
List
This GET method retrieves voicemails for a given PBX, or an extension of that PBX if specified as a parameter.
Parameter ext=<ext>
Retrieve
This is a GET method that will return the data of a single voicemail referred to by the voicemail’s ID.
Update
This is a PUT method that will mark a single voicemail referred to by the voicemail’s ID as read.
Delete
This is a DELETE method that will delete a single voicemail referred to by the voicemail’s ID.
Note: All API responses will be a JSON string
If read_epoch is 0 that means the voicemail has not been listened to
Interactive Phone Platform
Interactive Phone Platform allows 3rd party integration for screens pops, additional call status notifications, and Click-2-Call functionality.
Call Events - 2 methods are available
1. Requires an Oauth approach with a RESTful API for notifications. The method provides the easiest user experience, but is the heaviest for your team to develop.
Current API - https://mangovoice.com/api-docs/interactive-phone-platform/
2. Uses Webhooks to send Call Events for a given Mango Extension. See Webhooks - Call Events
Click2Call
Enabling Click2Call allows users to click on a phone number inside of an application and have that call automatically call the customer and connect it to the agent's phone.
The following pages instruct organizations on building their own API or Webhook endpoints to integrate Mango Voice functionality within their own systems. Organizations wanting to integrate with Mango Voice must follow the guidelines within this document based on which functionality they want to incorporate.
Active Users
Mango Voice will use this API to retrieve the active users in the subscriber's system.
Request URL:
https://<base url>/mango/activeusers
Request Method:
GET
Parameters:
Call Answered
Mango Voice will use this API call to notify the subscriber when an inbound call has been answered.
Request URL:
https://<base url>/mango/callanswered
Request Method:
POST
Parameters:
Call Dialed
Mango Voice will use this API call to notify the subscriber on an outbound call when the destination phone rings or is about to ring.
Request URL:
https://<base url>/mango/calldialed
Request Method:
POST
Parameters:
Call Hangup (Inbound)
Mango Voice will use this API call to notify the subscriber when an inbound call has been hung-up.
Request URL:
https://<base url>/mango/callhangup
Request Method:
POST
Parameters:
Call Hangup (Outbound)
Mango Voice will use this API call to notify the subscriber when an outbound call has been hung-up.
Request URL:
https://<base url>/mango/callhangup
Request Method:
POST
Parameters:
Call Missed
Mango Voice will use this API call to notify the subscriber when an inbound call has been missed.
Request URL:
https://<base url>/mango/callmissed
Request Method:
POST
Parameters:
Call Ringing
Mango Voice will use this API call to notify the subscriber when an inbound call is ringing.
Request URL:
https://<base url>/mango/callringing
Request Method:
POST
Parameters:
Click2Call
Overview:
Enabling Click2Call allows users to click on a phone number inside of an application and have that call automatically call the customer and connect it to the agent's phone
Click2call call flow
1. Click to call request is made
2. MangoVoice Softswitch dials the Agent (extension) “A leg”
3. When Agent extension answers, Mango Softswitch will begin dialing the number requested in the api request “B leg”
4. Mango Bridges A leg and B leg
Request URL:
Use the clicktocallurl obtained from the Click2call Setup API
Example: https://apiuser.mangovoice.com/api/v2/iclicktocall/<auth token>
Note: auth token is a unique identifier for the subscriber's PBX that will be passed as part of the clicktocallurl in the above API
Request Method:
POST
Parameters:
Click2call Enable-Disable API Guide
The client will enable Click2Call per user from the Mango Voice Admin portal.
In order to use click2call:
1. Mango Voice will call an API provided by the subscriber to enable click2call. When calling this API Mango Voice will provide a click2call url as one of the parameters.
2. The subscriber will use the click2call url provided by Mango Voice whenever someone uses click2call within the subscriber's system in order to initialize the call.
Click2Call setup API
Mango Voice will call this API in order to enable or disable click2call for a user in the subscriber's system
Request URL
https://<base url>/callcontrol
Request Methods
POST - Enable click2call for a user
DELETE - Disable click2call for a user
Parameters:
You will need to store the clicktocallurl and clicktocallparam for use with using the Click2call API for Mango Voice. This will be unique per user.
Enable or Disable Integration
Mango Voice will use this API call to enable or disable integration with the subscriber's system.
Request URL:
https://<base url>/mango/integrate
Request Method:
POST - Enable the integration
DELETE - Disable the integration
Parameters:
Webhooks - Call Events
Using the Mango administration portal a user can enable Mango extensions to send call state notifications for both inbound and outbound calls to and from any Line Extension.
Call Event Notification are send via Webhooks. This method sends all notifications to a single webhook (callback url) with a Standardized JSON object.
The subscriber (the organization wanting to receive call event notifications) will first have to provide Mango Voice with a base URL (callback url).
EXAMPLE BASE URL:
https://example.com/mango-notifications
Request Method:
POST
Parameters:
