NAV

Eqivo | Open Source Telephony API Platform

Eqivo is an open source telephony/real time communications API platform.

Eqivo started as a tribute project/reimplementation of the discontinued Plivo Framework, not to be confused with the cloud offering by the same company; there is no affiliation between the latter company and the Eqivo developers. For clarity, the original (now discontinued) project shall be referred to as the legacy framework.

To learn more about it, read the project's mission statement and its documentation, as archived by the Wayback Machine circa 2017.

Join us on the community chat or GitHub discussions.

It relies on FreeSWITCH for signalling (SIP, Verto, etc.) and media (RTP) handling. Eqivo sits between FreeSWITCH and your application and interacts with the latter by accepting inbound API calls as well as issuing outgoing webhook calls to your designated endpoints.

Being a reimplementation of the legacy Plivo framework, Eqivo can function as a drop-in replacement for most use cases. It also features several extensions, including M:N (Eqivo:FreeSWITCH) deployment configurations and answering machine detection.

Overview

Eqivo Diagram

Out of the box, the legacy framework was intended to be deployed alongside FreeSWITCH, seemingly at host level as containers were not as popular back then. Fast forward a decade later, Eqivo is optimized for container based deployments and breaks away from the 1-to-1 relationship with FreeSWITCH. Internally, Eqivo follows most (yet not all) design principles of the legacy framework. A great deal of terminology is also borrowed for the latter project.

Initiating Actions

In order to initiate various actions, your application will invoke the Eqivo RestAPI. It's backwards compatible and the interactions are fairly straightforward, all requests must:

Handling Events

Your application must expose endpoints Eqivo will invoke when certain events occur. For example, when an inbound call lands on a FreeSWITCH instance, Eqivo will hit a designated endpoint on your application expecting a well formatted XML response describing how the call in question should be handled. The RestXML implementation is backwards compatible.

Getting Started

Installation

OCI Container

docker pull rtckit/eqivo
docker run rtckit/eqivo

Container deployment is the recommended method for integrating Eqivo in your applications; ready-made OCI images are available on DockerHub. Configuration via environment variables is ideal for this approach, and orchestration systems such as Kubernetes can transparently handle secret management on your behalf.

For every release, there are two images available, the production one (using version tags) which contains only Eqivo and the PHP runtime and its dependencies. There is also a debug image (tagged with the -full suffix) which includes a complete Debian userland to facilitate troubleshooting.

Phar Package

Direct download:

curl -Ls https://github.com/rtckit/eqivo/releases/download/v0.6.2/eqivo.phar -o eqivo
chmod +x eqivo
sudo mv eqivo /usr/local/bin
eqivo

The project is also available as a standalone Phar package, in which case the environment must be properly configured, i.e.: PHP 8.1+ as well as required extensions (typically bundled with the PHP core).

During startup, Eqivo will check if its dependencies are met and it will complain if something is wrong.

PHIVE

You can also install Eqivo using PHIVE:

phive install eqivo

Git Repository

Lastly, you can clone the GitHub repository and launch Eqivo manually:

git clone https://github.com/rtckit/eqivo.git
cd eqivo
composer update
./bin/eqivo

Configuration

The default configuration values alone will not result in a meaningful Eqivo running instance. Furthermore, there is no boilerplate configuration template as each integrating application is unique. All options are documented in their respective chapter, however it is important to understand how Eqivo interacts with your application and FreeSWITCH so one can configure it properly.

Eqivo ⇆ FreeSWITCH

At least one running FreeSWITCH instance (aka core) must be configured, which consists of a host name, a port number, a password and an optional user name. It's important to note your network/firewall settings must allow Eqivo to connect to the configured host:port pair over TCP.

For the reverse control flow, Eqivo exposes a service (referred to as the outbound server) which intakes notifications from FreeSWITCH. outboundServerBindIp and outboundServerBindPort are defining the socket address pair where Eqivo is listening at and the network/firewall settings must ensure FreeSWITCH is allowed access to it.

Eqivo ⇆ Integrating application

Eqivo forwards various events by invoking webhooks managed by your application. These are either predefined (such as defaultAnswerUrl, defaultHangupUrl, recordUrl or callHeartbeatUrl) or set dynamically as API request parameters. The network/firewall settings must ensure Eqivo is able to access the configured webhooks.

For the reverse control flow, Eqivo exposes a service (referred to as the REST server) which intakes API requests from your application. restServerBindIp and restServerBindPort are defining the socket address pair where Eqivo is listening at and the network/firewall settings must ensure your application is allowed access to it.

Several common scenarios and a sample Docker Compose configuration are available in the rtckit/eqivo-sandbox repository.

Configuration

From a drop-in replacement perspective, Eqivo can function out of the box using legacy framework configuration files. It is however capable of more modern configuration intake facilitating both development as well as production deployment.

Eqivo is able to read configuration from static files (JSON and YAML format, resolving to the same schema), command line arguments and environment variables. Furthermore, one can mix these configuration channels as they see fit. For example when developing locally, one could set the EQIVO_VERIFY_PEER environment variable to false to bypass certificate validation yet retaining the baseline configuration which will eventually be used in production.

Sample configuration files can be found in the git repository: current YAML file, current JSON file and legacy configuration file.

daemonize

When enabled, Eqivo will run in background.

userName

Runs Eqivo as an alternate user.

groupName

Runs Eqivo as a member of an alternate group.

appPrefix

String used in naming custom FreeSWITCH variables. Set to plivo to mimic the legacy framework.

pidFile

Path to a file containing Eqivo's process identification number (or PID).

configFile

Path to a static configuration file. Please note the file's extension will determine how the file will be parsed. If it's .json or .yaml, the configuration file will be processes as per the usual. For any other extension, the file will be interpreted as being compatible with the format used by the legacy framework.

cores

cores:
    - eslHost: '127.0.0.1'
      eslPort: 8021
      eslPassword: 'secret'
    - eslHost: '2nd-freeswitch.example.com'
      eslPort: 8021
      eslUser: 'esluser' # if defined in event_socket.conf
      eslPassword: 'bfrx738'

One or more FreeSWITCH instances (or cores) which will work in tandem with Eqivo. Please note the legacy framework is designed to integrate against a single FreeSWITCH instance, so the legacy configuration file is not capable of defining more cores.

--core secret@127.0.0.1:8021 --core esluser:bfrx738@2nd-freeswitch.example.com:8021
export EQIVO_CORE_0=secret@127.0.0.1:8021
export EQIVO_CORE_1=esluser:bfrx738@2nd-freeswitch.example.com:8021

The corespec for CLI arguments and environment variables must be formatted as follows:

[user:]password@host:port

defaultHttpMethod

HTTP method Eqivo will employ when designated RestXML or notification endpoints are being invoked.

defaultAnswerUrl

URL to an endpoint exposed by your application responsible for providing RestXML for handling inbound calls.

defaultHangupUrl

URL to an endpoint where hangup notifications will be sent. If not set, the default answer URL will be used instead.

extraChannelVars

Additional FreeSWITCH channel variables to be appended to HTTP payloads when RestXML is requested or when notifications are being sent.

For legacy configuration files, CLI arguments and environment variables use a comma separated string instead of an array.

verifyPeer

Requires verification of TLS certificates presented by remote endpoints.

verifyPeerName

Requires verification of host names found in TLS certificates presented by remote endpoints.

restServerBindIp

IP address Eqivo's REST server will be bound to.

restServerBindPort

TCP port Eqivo's REST server will be bound to.

restServerAdvertisedHost

Unique identifier for each running REST server instance (defaults to machine's/container's host name). This is useful when multiple Eqivo instances sit behind a load balancer and your application needs to know which Eqivo instance handled the request.

restServerMaxHandlers

Number of concurrent request buffering handles for the REST server.

restServerMaxRequestSize

Maximum buffering size per REST request.

restServerLogLevel

REST server RFC 5424 logging verbosity level, can be one of DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT or EMERGENCY.

Please note the legacy LOG_TYPE property will be ignored, the logging output is limited to STDOUT.

restAllowedIps

List of IPs allowed to connect to the REST server. Unlike the legacy framework, Eqivo also accepts CIDR ranges.

For legacy configuration files, CLI arguments and environment variables use a comma separated string instead of an array.

restAuthId

User portion of the Basic Authentication required by the REST server.

restAuthToken

Password portion of the Basic Authentication required by the REST server. Also used for signing outgoing RestXML and notification requests.

recordUrl

URL where notifications will be sent when FreeSWITCH recordings are completed.

outboundServerBindIp

IP address the Outbound server will be bound to.

outboundServerBindPort

TCP port the Outbound server will be bound to.

outboundServerAdvertisedIp

IP address relayed to FreeSWITCH. Can be useful for more complex network layouts and/or when multiple Outbound servers are placed behind a load balancer.

outboundServerAdvertisedPort

TCP port relayed to FreeSWITCH. See outboundServerAdvertisedPort.

outboundServerLogLevel

Outbound server RFC 5424 logging verbosity level, can be one of DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT or EMERGENCY.

Please note the legacy LOG_TYPE property will be ignored, the logging output is limited to STDOUT.

inboundServerLogLevel

Inbound server RFC 5424 logging verbosity level, can be one of DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT or EMERGENCY.

Please note the legacy LOG_TYPE property will be ignored, the logging output is limited to STDOUT. Also, the Inbound server does not exist as a separate entity in the legacy framework, it's part of the REST server so it will follow the latter's configuration.

callHeartbeatUrl

URL to which call (session) FreeSWITCH heartbeat events will be sent to.

RestXML

Inherited from the legacy framework, RestXML refers to a small set of specialized XML elements describing how calls should be handled. In a way, you can think of RestXML being an evolved dialplan, one that's easier to program in dynamic contexts. On each occasion when Eqivo needs RestXML in order to control a call, it will fire an HTTP(S) request to a designated endpoint, typically via POST although GET is also possible.

<?xml version="1.0" encoding="UTF-8" ?>
<Response> 
    <Speak>Welcome!</Speak>
    <Speak>To whom do I have the pleasure of speaking with?</Speak>
    <Record action="https://example.com/endpoint/got_name/" fileName="caller_name" />
    <Speak>I'm sorry, I didn't get that!</Speak>
</Response>

The request's payload includes critical parameters such as identification for both the caller and the callee, FreeSWITCH node responsible for the call and even the Eqivo node handling it.

RestXML structures must present a parent <Response> node which contains the elements to be executed (top to bottom). Element names and attributes are case-sensitive.

Conference

The <Conference> element allows you to connect different individual call legs together via a conference room; mod_conference's documentation can shed more light over the under-the-hood mechanisms.

Important conference room characteristics:

Basic usage:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Conference>1912</Conference>
</Response>

Allow members in but don't kick off the conference yet:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Conference startConferenceOnEnter="false">1912</Conference>
</Response>

Conversely, for "moderator" users:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Conference startConferenceOnEnter="true" endConferenceOnExit="true">
        1912
    </Conference>
</Response>

Conference element attributes

muted

Whether a member can speak on the conference. If this attribute is set to true, the member will only be able to listen to people on the conference.

enterSound

Sets a sound to be played when a participant enters a room: none, a single beep or a double beep.

exitSound

Sets a sound to be played when a participant leaves a room: none, a single beep or a double beep.

startConferenceOnEnter

Whether or not the conference should start when the participant joins. Set to false when unprivileged members join moderated rooms.

endConferenceOnExit

Whether or not the conference should end when the participant leaves. Set to true when moderators members leave moderated rooms.

stayAlone

Whether the participant is allowed to be the sole member of a room. When set to false, they conference ends.

waitSound

Absolute URL returning RestXML describing the music-on-hold to be played for the conference. The RestXML must only consist of <Play> and <Wait> elements.

maxMembers

Maximum number of members to be allowed into the room.

timeLimit

Maximum lifetime of the conference room, in seconds. A value of 0 translates to an unlimited lifetime.

hangupOnStar

Whether the participant will exit the room if they press the * key.

recordFilePath

Path/URI to conference's recording file. When empty, the conference will be off the record.

recordFileFormat

Recording file format.

recordFileName

Recording file name, without extension. If empty but recordFilePath is present, a timestamp based filename will be generated.

action

Upon exiting the conference, fetch RestXML (for the remainder of the call) from the specified URL.

method

HTTP method to be used when action URL is being invoked.

callbackUrl

URL where DMTF or floor change events will be posted at.

callbackMethod

HTTP method to be used when callbackUrl URL is being invoked.

digitsMatch

Comma separated list of matching DMTF strings; when any of the defined patterns is received, callbackUrl endpoint will be invoked.

floorEvent

Whether floor-change events should be sent to callbackUrl.

Dial

The <Dial> element originates a new call leg; should it connect, it is bridged onto the original call leg. One or more <Number> elements must be nested within; the body of the <Number> element represents the destination (e.g. phone number) whereas its attributes dictate how to connected to the destination in question. Conversely, the <Dial> element attributes have a broader scope.

When multiple <Number> elements are present, the first connected destination is bridged and all other attempts are cancelled.

Basic usage:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Number gateways="sofia/gateway/pstntrunk/" gatewayCodecs="'PCMA,PCMU'">
            12025551234
        </Number>
    </Dial>
</Response>

Dial multiple destinations concurrently:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Number gateways="sofia/gateway/pstntrunk/" gatewayCodecs="'PCMA,PCMU'">
            12025551234
        </Number>
        <Number gateways="sofia/gateway/alttrunk/" gatewayCodecs="'PCMA,PCMU'">
            2025551234
        </Number>
        <Number gateways="user/" gatewayCodecs="'PCMA,PCMU'">
            2095
        </Number>
    </Dial>
</Response>

Dial element attributes

action

Upon connection failure or after the bridged call leg ends, fetch RestXML (for the remainder of the call) from the specified URL.

method

HTTP method to be used when action URL is being invoked.

hangupOnStar

Whether the originator can end the bridged call leg when they press the * key.

timeLimit

Maximum lifetime of the bridged call, in seconds.

timeout

How long to wait for call attempt(s) to succeed.

callerId

Caller ID to be presented to the remote party.

callerName

Caller Name to be presented to the remote party.

confirmSound

Absolute URL returning RestXML describing the media to be played once the remote call leg connects. The RestXML must only consist of <Play> and <Wait> elements.

confirmKey

DTMF tone the remote party must issue in order to bridge the call.

dialMusic

Absolute URL returning RestXML describing the media to be played to the originator until the call attempt(s) succeed. The RestXML must only consist of <Play> and <Wait> elements. Set to none for silence, an (empty) value will render a standard ringback tone

callbackUrl

URL where DMTF and connected/hangup events will be posted at.

callbackMethod

HTTP method to be used when callbackUrl URL is being invoked.

digitsMatch

Comma separated list of matching DMTF strings; when any of the defined patterns is received, callbackUrl endpoint will be invoked.

redirect

Set to false to ignore the RestXML returned by action URL and continue to the next element after <Dial>.

Number element attributes

sendDigits

Sequence of DTMF tones to be sent to the remote party as soon as it connects.

sendOnPreanswer

Whether to sent the sendDigits tones as early media, rather than after the call connects.

gateways

Comma separated list of FreeSWITCH endpoint prefixes (e.g. user/, sofia/gateway/<gateway name>/, verto.rtc/ etc.).

gatewayCodecs

Comma separated list of accepted codecs for each entry in the gateways attribute. Enclose multiple codec choices with single quotes, e.g. 'PCMU,PCMA','Opus'.

gatewayTimeouts

Comma separated list of timeouts for each entry in the gateways attribute.

gatewayRetries

Comma separated list of allowed tries for each entry in the gateways attribute.

extraDialString

Additional variables to be appended to the originate FreeSWITCH command.

GetDigits

The <GetDigits> element enables the collection of DTMF tones. As with the other elements, the collection rules are defined by the element's attributes. The media to be played during the collection can be represented by <Play>, <Speak> and <Wait> elements, nested within the <GetDigits> parent element.

4-digit PIN collection example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <GetDigits action="https://example.com/endpoint/got_digits/" numDigits="4">
        <Speak>
            Please enter your PIN followed by the pound sign.
        </Speak>
    </GetDigits>
    <Speak>I couldn't get that!</Speak>
</Response>

GetDigits element attributes

action

Upon successful collection or timeout, fetch RestXML (for the remainder of the call) from the specified URL. The request payload will include a Digits parameter containing the matched DTMF tones.

method

HTTP method to be used when action URL is being invoked.

timeout

How long to wait for DTMF tones, in seconds.

finishOnKey

Single DTMF tone which will end the collection.

numDigits

Total amount of tones to collect.

retries

Total collection attempts.

playBeep

Whether to play a brief beep sound after the nested media elements (if any) are done executing.

validDigits

Acceptable DTMF tones.

invalidDigitsSound

Path/URI to a media file to be played when receiving tones not allowed by validDigits.

GetSpeech

The <GetSpeech> element is a form of input collection via speech-to-text. As with the other elements, the collection rules are defined by the element's attributes. The media to be played during the collection can be represented by <Play>, <Speak> and <Wait> elements, nested within the <GetSpeech> parent element.

Yes/no confirmation example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <GetSpeech action="https://example.com/endpoint/got_speech/" grammar="pizza_yesno" timeout="10">
        <Speak>
            Would you like to proceed?
        </Speak>
    </GetSpeech>
    <Speak>I'm sorry, I didn't get that!</Speak>
</Response>

GetSpeech element attributes

action

Upon successful collection or timeout, fetch RestXML (for the remainder of the call) from the specified URL. The request payload will include a SpeechResult parameter containing the interpreted text.

method

HTTP method to be used when action URL is being invoked.

timeout

How long to wait for speech, in seconds.

engine

FreeSWITCH speech-to-text/ASR engine.

grammar

Speech-to-text/ASR grammar file to be used.

playBeep

Whether to play a brief beep sound after the nested media elements (if any) are done executing.

Hangup

The <Hangup> element ends a call.

Simple usage:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Hangup />
</Response>

Hangup in 30 seconds:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Hangup schedule="30" />
</Response>

Reject a call upon arrival

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Hangup reason="rejected" />
</Response>

Hangup element attributes

reason

Modifies the call's release call.

schedule

Schedules the hangup at a future point in time.

Play

The <Play> renders audio from supported static files (local to FreeSWITCH) as well as remote media (via http_cache) and even generated tones.

Simple usage:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play>http_cache://https://example.com/media/hello.wav</Play>
    <Play>/tmp/media/message_of_the_day.mp3</Play>
</Response>

Play element attributes

loop

Times to play the specified media.

PreAnswer

The <PreAnswer> allows the execution of other RestXML elements without answering a call, i.e. in early media state.

Simple usage:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <PreAnswer>
        <Play>/tmp/media/while_you_wait.wav</Play>
    </PreAnswer>
</Response>

The following elements are eligible for nesting within <PreAnswer>:

Record

The <Record> element captures the remote party's audio input and stores it in a given file/location. The recording rules are define by element's attributes.

4-digit PIN collection example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Speak>Please state your name after the beep</Speak>
    <Record action="https://example.com/endpoint/got_recording/" maxLength="15"></Record>
    <Speak>I couldn't get that!</Speak>
</Response>

Record element attributes

action

Upon element's completion, fetch RestXML (for the remainder of the call) from the specified URL. The request payload will include several parameters describing the recording: RecordingFileFormat, RecordingFilePath, RecordingFileName, RecordFile, RecordingDuration and Digits.

method

HTTP method to be used when action URL is being invoked.

redirect

Set to false to ignore the RestXML returned by action URL and continue to the next element after <Record>.

timeout

Maximum seconds of silence before considering the recording complete.

finishOnKey

Single DTMF tone which will end the recording.

maxLength

Maximum recording length.

playBeep

Whether to play a brief beep sound before recording commences.

filePath

Path/URI where the recording file will be stored at.

filePath

Path/URI where the recording file will be stored at.

fileFormat

Recording file format.

fileName

Recording file name, without extension. If empty, a timestamp based filename will be generated.

bothLegs

Whether to record both call legs, when a second remote call leg is bridged.

Redirect

The <Redirect> element diverts the call control to a new set of RestXML elements, to be returned by a designated URL.

Redirect element attributes

Sample usage:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Speak>Please hold while we're looking up your account</Speak>
    <Redirect>https://example.com/stage2/</Redirect>
</Response>

method

HTTP method to be used when the designated URL is being invoked.

SIPTransfer

The <SIPTransfer> element will either deflect (for answered calls) or redirect (for unanswered calls) the call leg in question to one or more remote SIP endpoints.

Sample usage:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <SIPTransfer>sip:2095@pbx.example.com</SIPTransfer>
</Response>

Speak

The <Speak> renders audio via text-to-speech.

Simple usage:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Speak>Hey there!</Speak>
</Response>

Speak element attributes

engine

Text-to-speech engine to be used (relative to FreeSWITCH).

voice

Text-to-speech voice to be used (relative to FreeSWITCH text-to-speech engine).

language

Text-to-speech voice to be used (relative to FreeSWITCH text-to-speech engine).

loop

Times to play the generated media.

type

Type of data to be synthesized. Refer to FreeSWITCH's say application.

method

How to interpret numerical values. Refer to FreeSWITCH's say application.

Wait

The <Wait> element will let the call flow silently for a given amount of seconds, following that any remaining RestXML elements will be executed.

Wait element attributes

Sample usage:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Speak>I will go quiet on you for 5 seconds</Speak>
    <Wait length="5" />
    <Speak>Okay, enough of that!</Speak>
</Response>

length

Amount of seconds

RestAPI

Eqivo's API can be employed to affect the way FreeSWITCH handles sessions. It can be split into two categories:

All API methods are documented below, an OpenApi spec is also available.

Call

API methods responsible for spawning and manipulating individual calls

/v0.1/BulkCall/

Code samples

## You can also use wget
curl -X POST /v0.1/BulkCall/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/BulkCall/

Initiates multiple concurrent outbound calls

Body parameter

Delimiter: <
From: "15551234567"
To: "15557654321"
Gateways: user/,sofia/gateway/PSTNgateway1/,sofia/gateway/PSTNgateway2/
AnswerUrl: https://example.com/answer/
RejectCauses: USER_BUSY,NO_ANSWER
CallerName: Bulk Test
ConfirmSound: https://example.com/confirm_sound/
ConfirmKey: "1"
HangupUrl: https://example.com/hangup/
RingUrl: https://example.com/ring/
ExtraDialString: bridge_early_media=true,hangup_after_bridge=true
GatewayCodecs: "'PCMA,PCMU','G729,PCMU','PCMA,G729'"
GatewayTimeouts: 10,30,20
GatewayRetries: 3,1,2
SendDigits: 1w2w3W#*@1500
SendOnPreanswer: false
TimeLimit: 90
HangupOnRing: 90
CoreUUID: 2e8e6275-7cfe-4e3c-a8d6-25316b4519c7

Parameters

Name In Type Required Description
Delimiter body string true Any character, except / and ,, which will be used as a separator within several parameters
From body string true Phone number to be used as Caller ID
To body string true Phone number to be called
Gateways body string true Comma separated FreeSWITCH gateway strings. When multiple gateways are specified, they will be tried sequentially (failover)
AnswerUrl body string true Fully qualified URL which will provide the RestXML once the call connects
RejectCauses body string false Comma separated reject causes
CallerName body string false Caller Name to be set for the call
ConfirmSound body string false Remote URL to fetch with POST HTTP request which must return a RestXML with Play, Wait and/or Speak Elements only (all others are ignored). This RESTXML is played to the called party when he answered
ConfirmKey body string false DTMF tone the called party must send to accept the call
HangupUrl body string false Fully qualified URL to which the call hangup notification will be POSTed. HangupCause is added to the usual call call notification parameters
RingUrl body string false Fully qualified URL to which the call ringing notification will be POSTed. RequestUUID and CallUUID is added to the usual call notification parameters
ExtraDialString body string false Additional channel variables to be added to the originate FreeSWITCH API call.
GatewayCodecs body string false List of codec(s) to be used for each gateway. Enclose codec groups in single quotes
GatewayTimeouts body string false List of maximum timeout amounts (in seconds) for each gateway
GatewayRetries body string false List of maximum retry counts for each gateway
SendDigits body string false DTMF tones to be sent when the call is answered. Each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
SendOnPreanswer body boolean false When set to true, DTMF tones will be sent as early media rather than when the call is answered
TimeLimit body integer false Schedules the call's hangup at a given time offset (in seconds) after the call is answered
HangupOnRing body integer false Schedules the call's hangup at a given time offset (in seconds) after the destination starts ringing
CoreUUID body string false Core UUID of the desired FreeSWITCH instance (an Eqivo extension)

Example responses

200 Response

{
  "Message": "BulkCalls Request Executed",
  "RequestUUID": [
    "fc92f3f4-3777-43ed-b269-5b4a0d474b12",
    "22f94a34-2890-4f18-ab99-5c47e25dd3c3",
    "d1337342-0225-465d-b7bb-1b5d88eb39d2"
  ],
  "Success": true,
  "RestApiServer": "localhost"
}

Responses

Status Meaning Description Schema
200 OK Response BulkCallResponse

/v0.1/Call/

Code samples

## You can also use wget
curl -X POST /v0.1/Call/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/Call/

Initiates an outbound call

Body parameter

From: "15551234567"
To: "15557654321"
Gateways: user/,sofia/gateway/PSTNgateway1/,sofia/gateway/PSTNgateway2/
AnswerUrl: https://example.com/answer/
CallerName: Test
HangupUrl: https://example.com/hangup/
RingUrl: https://example.com/ring/
ExtraDialString: bridge_early_media=true,hangup_after_bridge=true
GatewayCodecs: "'PCMA,PCMU','G729,PCMU','PCMA,G729'"
GatewayTimeouts: 10,30,20
GatewayRetries: 3,1,2
SendDigits: 1w2w3W#*@1500
SendOnPreanswer: false
TimeLimit: 90
HangupOnRing: 90
CoreUUID: 45521fc6-a4b3-42b6-96ad-9136256be216
MachineDetection: Enable
AsyncAMD: true
AsyncAmdStatusCallbackMethod: GET
AsyncAmdStatusCallback: string
MachineDetectionTimeout: 5
MachineDetectionSpeechThreshold: 2000
MachineDetectionSpeechEndThreshold: 1000
MachineDetectionSilenceTimeout: 3000

Parameters

Name In Type Required Description
From body string true Phone number to be used as Caller ID
To body string true Phone number to be called
Gateways body string true Comma separated FreeSWITCH gateway strings. When multiple gateways are specified, they will be tried sequentially (failover)
AnswerUrl body string true Fully qualified URL which will provide the RestXML once the call connects
CallerName body string false Caller Name to be set for the call
HangupUrl body string false Fully qualified URL to which the call hangup notification will be POSTed. HangupCause is added to the usual call call notification parameters
RingUrl body string false Fully qualified URL to which the call ringing notification will be POSTed. RequestUUID and CallUUID is added to the usual call notification parameters
ExtraDialString body string false Additional channel variables to be added to the originate FreeSWITCH API call.
GatewayCodecs body string false List of codec(s) to be used for each gateway. Enclose codec groups in single quotes
GatewayTimeouts body string false List of maximum timeout amounts (in seconds) for each gateway
GatewayRetries body string false List of maximum retry counts for each gateway
SendDigits body string false DTMF tones to be sent when the call is answered. Each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
SendOnPreanswer body boolean false When set to true, DTMF tones will be sent as early media rather than when the call is answered
TimeLimit body integer false Schedules the call's hangup at a given time offset (in seconds) after the call is answered
HangupOnRing body integer false Schedules the call's hangup at a given time offset (in seconds) after the destination starts ringing
CoreUUID body string false Core UUID of the desired FreeSWITCH instance (an Eqivo extension)
MachineDetection body string false Enables answering machine detection; optionally, it waits until the greeting message has been played back (an Eqivo extension)
AsyncAMD body boolean false When set to true, the call flow execution is blocked until answering machine detection is complete (an Eqivo extension)
AsyncAmdStatusCallbackMethod body string false HTTP method to be used when answering machine detection is completed (an Eqivo extension)
AsyncAmdStatusCallback body string false Fully qualified URL to which the answering machine detection result will be sent. AnsweredBy and MachineDetectionDuration are appended to the usual call notification parameters (an Eqivo extension)
MachineDetectionTimeout body integer false Amount of time (in seconds) allotted for answering machine detection assessment (an Eqivo extension)
MachineDetectionSpeechThreshold body integer false Speech activity/utterance threshold (in milliseconds, an Eqivo extension)
MachineDetectionSpeechEndThreshold body integer false Silence threshold (in milliseconds, an Eqivo extension)
MachineDetectionSilenceTimeout body integer false Initial silence threshold (in milliseconds, an Eqivo extension)

Enumerated Values

Parameter Value
MachineDetection Enable
MachineDetection DetectMessageEnd
AsyncAmdStatusCallbackMethod POST
AsyncAmdStatusCallbackMethod GET

Example responses

200 Response

{
  "Message": "Call Request Executed",
  "RequestUUID": "fc92f3f4-3777-43ed-b269-5b4a0d474b12",
  "Success": true,
  "RestApiServer": "localhost"
}

Responses

Status Meaning Description Schema
200 OK Response CallResponse

/v0.1/CancelScheduledHangup/

Code samples

## You can also use wget
curl -X POST /v0.1/CancelScheduledHangup/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/CancelScheduledHangup/

Cancels a scheduled hangup for a call

Body parameter

SchedHangupId: ea428fbd-ac9b-498c-8bb2-a36ac49f10fd

Parameters

Name In Type Required Description
SchedHangupId body string true Unique identifier returned when scheduled hangup was originally requested

Example responses

200 Response

{
  "Message": "Scheduled Hangup Cancelation Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response CancelScheduledHangupResponse

/v0.1/CancelScheduledPlay/

Code samples

## You can also use wget
curl -X POST /v0.1/CancelScheduledPlay/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/CancelScheduledPlay/

Cancels a scheduled playback request

Body parameter

SchedPlayId: ea428fbd-ac9b-498c-8bb2-a36ac49f10fd

Parameters

Name In Type Required Description
SchedPlayId body string true Unique identifier returned when scheduled playback was originally requested

Example responses

200 Response

{
  "Message": "Scheduled Play Cancelation Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response CancelScheduledPlayResponse

/v0.1/GroupCall/

Code samples

## You can also use wget
curl -X POST /v0.1/GroupCall/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/GroupCall/

Initiate multiple racing outbound calls

Body parameter

Delimiter: <
From: "15551234567"
To: "15557654321"
Gateways: user/,sofia/gateway/PSTNgateway1/,sofia/gateway/PSTNgateway2/
AnswerUrl: https://example.com/answer/
RejectCauses: USER_BUSY,NO_ANSWER
CallerName: Group Test
ConfirmSound: https://example.com/confirm_sound/
ConfirmKey: "1"
HangupUrl: https://example.com/hangup/
RingUrl: https://example.com/ring/
ExtraDialString: bridge_early_media=true,hangup_after_bridge=true
GatewayCodecs: "'PCMA,PCMU','G729,PCMU','PCMA,G729'"
GatewayTimeouts: 10,30,20
GatewayRetries: 3,1,2
SendDigits: 1w2w3W#*@1500
SendOnPreanswer: false
TimeLimit: 90
HangupOnRing: 90
CoreUUID: 46ae8cd9-c28e-447d-ba40-a09cba49d474

Parameters

Name In Type Required Description
Delimiter body string true Any character, except / and ,, which will be used as a separator within several parameters
From body string true Phone number to be used as Caller ID
To body string true Phone number to be called
Gateways body string true Comma separated FreeSWITCH gateway strings. When multiple gateways are specified, they will be tried sequentially (failover)
AnswerUrl body string true Fully qualified URL which will provide the RestXML once the call connects
RejectCauses body string false Comma separated reject causes
CallerName body string false Caller Name to be set for the call
ConfirmSound body string false Remote URL to fetch with POST HTTP request which must return a RestXML with Play, Wait and/or Speak Elements only (all others are ignored). This RESTXML is played to the called party when he answered
ConfirmKey body string false DTMF tone the called party must send to accept the call
HangupUrl body string false Fully qualified URL to which the call hangup notification will be POSTed. HangupCause is added to the usual call call notification parameters
RingUrl body string false Fully qualified URL to which the call ringing notification will be POSTed. RequestUUID and CallUUID is added to the usual call notification parameters
ExtraDialString body string false Additional channel variables to be added to the originate FreeSWITCH API call.
GatewayCodecs body string false List of codec(s) to be used for each gateway. Enclose codec groups in single quotes
GatewayTimeouts body string false List of maximum timeout amounts (in seconds) for each gateway
GatewayRetries body string false List of maximum retry counts for each gateway
SendDigits body string false DTMF tones to be sent when the call is answered. Each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
SendOnPreanswer body boolean false When set to true, DTMF tones will be sent as early media rather than when the call is answered
TimeLimit body integer false Schedules the call's hangup at a given time offset (in seconds) after the call is answered
HangupOnRing body integer false Schedules the call's hangup at a given time offset (in seconds) after the destination starts ringing
CoreUUID body string false Core UUID of the desired FreeSWITCH instance (an Eqivo extension)

Example responses

200 Response

{
  "Message": "GroupCall Request Executed",
  "RequestUUID": "fc01f3f4-4895-43ed-b269-5b4a0d474b12",
  "Success": true,
  "RestApiServer": "localhost"
}

Responses

Status Meaning Description Schema
200 OK Response GroupCallResponse

/v0.1/HangupAllCalls/

Code samples

## You can also use wget
curl -X POST /v0.1/HangupAllCalls/ \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/HangupAllCalls/

Hangs up all established calls

Example responses

200 Response

{
  "Message": "All Calls Hungup",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response HangupAllCallsResponse

/v0.1/HangupCall/

Code samples

## You can also use wget
curl -X POST /v0.1/HangupCall/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/HangupCall/

Hangs up a specific call

Body parameter

CallUUID: b0519011-6987-47c8-9270-a820e0978acd
RequestUUID: c059b96b-04d8-414b-920c-7b373bff916e

Parameters

Name In Type Required Description
CallUUID body string false Unique identifier of the call (when established); this parameter is mutually exclusive with RequestUUID
RequestUUID body string false Unique identifier of the API request (when the call is not established yet); this parameter is mutually exclusive with CallUUID

Example responses

200 Response

{
  "Message": "Hangup Call Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response HangupCallResponse

/v0.1/Play/

Code samples

## You can also use wget
curl -X POST /v0.1/Play/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/Play/

Plays media into a live call

Body parameter

CallUUID: e69b32da-3243-4ba6-a965-5d2f64a57d48
Sounds: /tmp/prompt.wav
Legs: both
Length: 90
Loop: true
Mix: false

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call to play media into
Sounds body string true Comma separated list of file paths/URIs to be played
Legs body string false Call leg(s) for which the media will be played; aleg refers to the initial call leg, bleg refers to the bridged call leg, if applicable.
Length body integer false Maximum amount of time (in seconds) to playback the media
Loop body boolean false Loops the media file(s) indefinitely
Mix body boolean false Whether the media should be mixed with the call's audio stream

Enumerated Values

Parameter Value
Legs aleg
Legs bleg
Legs both

Example responses

200 Response

{
  "Message": "Play Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response PlayResponse

/v0.1/PlayStop/

Code samples

## You can also use wget
curl -X POST /v0.1/PlayStop/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/PlayStop/

Interrupts media playback on a given call

Body parameter

CallUUID: 441afb63-85bc-49d4-9ac8-8459f9bf5e6b

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call

Example responses

200 Response

{
  "Message": "PlayStop Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response PlayStopResponse

/v0.1/RecordStart/

Code samples

## You can also use wget
curl -X POST /v0.1/RecordStart/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/RecordStart/

Initiates recording of a given call

Body parameter

CallUUID: 052d04e4-019a-45ff-a562-f74d4ae99ea2
FileFormat: wav
FilePath: /tmp/recordings
FileName: sample_recording
TimeLimit: 89

Parameters

Name In Type Required Description
CallUUID body string false Unique identifier of the call to be recorded
FileFormat body string false File format (extension)
FilePath body string false Directory path/URI where the recording file will be saved
FileName body string false Recording file name (without extension); if empty, a timestamp based file name will be generated
TimeLimit body integer false Maximum recording length, in seconds

Enumerated Values

Parameter Value
FileFormat wav
FileFormat mp3

Example responses

200 Response

{
  "Message": "RecordStart Executed",
  "RecordFile": "/tmp/recordings/sample.wav",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response RecordStartResponse

/v0.1/RecordStop/

Code samples

## You can also use wget
curl -X POST /v0.1/RecordStop/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/RecordStop/

Stops the recording of a given call

Body parameter

CallUUID: eacfa857-4001-4379-b79a-c7ef6d963bcb
RecordFile: /tmp/recording/sample.wav

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call
RecordFile body string true Full path to recording file, as returned by RecordStart; all shorthand is also available

Example responses

200 Response

{
  "Message": "RecordStop Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response RecordStopResponse

/v0.1/ScheduleHangup/

Code samples

## You can also use wget
curl -X POST /v0.1/ScheduleHangup/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ScheduleHangup/

Schedules a hangup for a specific call

Body parameter

CallUUID: f84fbadc-5df0-4c02-934b-aac0c1efb8ae
Time: 59

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call
Time body integer true Time (in seconds) after which the call in question will be hung up

Example responses

200 Response

{
  "Message": "ScheduleHangup Executed",
  "Success": true,
  "SchedHangupId": "21579000-0dca-4a75-bc1f-6eae8215a611"
}

Responses

Status Meaning Description Schema
200 OK Response ScheduleHangupResponse

/v0.1/SchedulePlay/

Code samples

## You can also use wget
curl -X POST /v0.1/SchedulePlay/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/SchedulePlay/

Schedules media playback for a specific call

Body parameter

CallUUID: e69b32da-3243-4ba6-a965-5d2f64a57d48
Sounds: /tmp/prompt.wav
Time: 29
Legs: both
Length: 90
Loop: true
Mix: false

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call to play media into
Sounds body string true Comma separated list of file paths/URIs to be played
Time body integer true Time (in seconds) after which the media will be playedback
Legs body string false Call leg(s) for which the media will be played; aleg refers to the initial call leg, bleg refers to the bridged call leg, if applicable.
Length body integer false Maximum amount of time (in seconds) to playback the media
Loop body boolean false Loops the media file(s) indefinitely
Mix body boolean false Whether the media should be mixed with the call's audio stream

Enumerated Values

Parameter Value
Legs aleg
Legs bleg
Legs both

Example responses

200 Response

{
  "Message": "Play Executed",
  "Success": true,
  "SchedPlayId": "b2d1da90-c364-42e4-818a-2eb90a474729"
}

Responses

Status Meaning Description Schema
200 OK Response SchedulePlayResponse

/v0.1/SendDigits/

Code samples

## You can also use wget
curl -X POST /v0.1/SendDigits/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/SendDigits/

Emits DMTF tones to a call

Body parameter

CallUUID: d4cd08fe-4245-490a-ae39-5b58c6addbe8
Digits: 1w2w3W#*@1500
Leg: both

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call to send DTMF to
Digits body string true DTMF tones to be sent; each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
Leg body string false Call leg(s) to which DTMFs will be sent; aleg refers to the initial call leg, bleg refers to the bridged call leg, if applicable.

Enumerated Values

Parameter Value
Leg aleg
Leg bleg
Leg both

Example responses

200 Response

{
  "Message": "SendDigits Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response SendDigitsResponse

/v0.1/SoundTouch/

Code samples

## You can also use wget
curl -X POST /v0.1/SoundTouch/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/SoundTouch/

Applies SoundTouch effects to a live call

Body parameter

CallUUID: b7054b68-0620-455a-8ac7-f8f126853b9d
AudioDirection: in
PitchSemiTones: 2
PitchOctaves: 0.5
Pitch: 4
Rate: 3
Tempo: 2

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call to send DTMF to
AudioDirection body string false Media stream to be altered, incoming or outgoing
PitchSemiTones body number(float) false Adjust the pitch in semitones
PitchOctaves body number(float) false Adjust the pitch in octaves
Pitch body number(float) false Adjust the pitch
Rate body number(float) false Adjust the rate
Tempo body number(float) false Adjust the tempo

Enumerated Values

Parameter Value
AudioDirection in
AudioDirection out

Example responses

200 Response

{
  "Message": "SoundTouch Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response SoundTouchResponse

/v0.1/SoundTouchStop/

Code samples

## You can also use wget
curl -X POST /v0.1/SoundTouchStop/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/SoundTouchStop/

Removes SoundTouch effects from a given call

Body parameter

CallUUID: fe372011-face-4bc2-bbcc-893d045bf67d

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call

Example responses

200 Response

{
  "Message": "SoundTouchStop Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response SoundTouchStopResponse

/v0.1/TransferCall/

Code samples

## You can also use wget
curl -X POST /v0.1/TransferCall/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/TransferCall/

Replaces the RestXML flow of a live call

Body parameter

CallUUID: 03694cf6-62b3-4f00-b0fc-6831ddcc2693
Url: https://example.org/restxml/endpoint/

Parameters

Name In Type Required Description
CallUUID body string true Unique identifier of the call
Url body string true Absolute URL which will return the updated RestXML flow

Example responses

200 Response

{
  "Message": "Transfer Call Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response TransferCallResponse

Conference

API methods responsible for managing conference rooms

/v0.1/ConferenceDeaf/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceDeaf/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceDeaf/

Blocks audio to one or more conference members

Body parameter

ConferenceName: Room402
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Deaf Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceDeafResponse

/v0.1/ConferenceHangup/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceHangup/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceHangup/

Kicks one or more conference members, without playing the kick sound

Body parameter

ConferenceName: Room402
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Hangup Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceHangupResponse

/v0.1/ConferenceHold/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceHold/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceHold/

Put one or more conference members on hold

Body parameter

ConferenceName: Room402
FilePath: /var/local/media/sample.wav
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
FilePath body string true Path/URI of the media file to be played as music-on-hold
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available however it is not capable of playing back the music-on-hold (i.e. use specific member IDs when MOH is necessary)

Example responses

200 Response

{
  "Message": "Conference Hold Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceHoldResponse

/v0.1/ConferenceKick/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceKick/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceKick/

Kicks one or more conference members

Body parameter

ConferenceName: Room402
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Kick Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceKickResponse

/v0.1/ConferenceList/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceList/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceList/

Returns a list of all established conferences

Body parameter

MemberFilter: 13,42
CallUUIDFilter: 872066e1-fd89-4c57-8733-93c113980bc9,55e4214a-604a-4b56-82e4-97834b0d524e
MutedFilter: "true"
DeafFilter: "true"

Parameters

Name In Type Required Description
MemberFilter body string false Restricts listed members to the provided values (comma separated member ID list)
CallUUIDFilter body string false Restricts listed calls to the provided values (comma separated call UUID list)
MutedFilter body boolean false Restricts listed members to muted ones
DeafFilter body boolean false Restricts listed members to deaf ones

Example responses

200 Response

{
  "Message": "Conference List Executed",
  "Success": true,
  "List": {
    "Room402": {
      "ConferenceMemberCount": "1",
      "ConferenceName": "Room402",
      "ConferenceRunTime": "79",
      "ConferenceUUID": "5105acbf-6d43-4d67-8536-19999924eba4",
      "Members": [
        {
          "Muted": false,
          "Deaf": false,
          "MemberID": "14",
          "CallNumber": "3985",
          "CallName": "DeskPhone985",
          "CallUUID": "8f72b48e-d97e-425a-a6e6-ae5a6a0dc231",
          "JoinTime": "79"
        }
      ]
    },
    "Room555": {
      "ConferenceMemberCount": "1",
      "ConferenceName": "Room555",
      "ConferenceRunTime": "28",
      "ConferenceUUID": "732fab2d-1bff-4b54-8d3e-bd937b8ff662",
      "Members": [
        {
          "Muted": false,
          "Deaf": false,
          "MemberID": "14",
          "CallNumber": "2002",
          "CallName": "GuestCenter2",
          "CallUUID": "f8a79c36-2567-479d-b4d9-08f4165f8767",
          "JoinTime": "28"
        }
      ]
    }
  }
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceListResponse

/v0.1/ConferenceListMembers/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceListMembers/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceListMembers/

Retrieves the member list for a given conference

Body parameter

ConferenceName: Room402
MemberFilter: 13,42
CallUUIDFilter: 872066e1-fd89-4c57-8733-93c113980bc9,55e4214a-604a-4b56-82e4-97834b0d524e
MutedFilter: "true"
DeafFilter: "true"

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference
MemberFilter body string false Restricts listed members to the provided values (comma separated member ID list)
CallUUIDFilter body string false Restricts listed calls to the provided values (comma separated call UUID list)
MutedFilter body boolean false Restricts listed members to muted ones
DeafFilter body boolean false Restricts listed members to deaf ones

Example responses

200 Response

{
  "Message": "Conference ListMembers Executed",
  "Success": true,
  "List": {
    "Room402": {
      "ConferenceMemberCount": "1",
      "ConferenceName": "Room402",
      "ConferenceRunTime": "79",
      "ConferenceUUID": "5105acbf-6d43-4d67-8536-19999924eba4",
      "Members": [
        {
          "Muted": false,
          "Deaf": false,
          "MemberID": "14",
          "CallNumber": "3985",
          "CallName": "DeskPhone985",
          "CallUUID": "8f72b48e-d97e-425a-a6e6-ae5a6a0dc231",
          "JoinTime": "79"
        }
      ]
    }
  }
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceListMembersResponse

/v0.1/ConferenceMute/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceMute/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceMute/

Blocks audio from one or more conference members

Body parameter

ConferenceName: Room402
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Mute Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceMuteResponse

/v0.1/ConferencePlay/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferencePlay/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferencePlay/

Plays media to one or all conference members

Body parameter

ConferenceName: Room402
FilePath: /var/local/media/sample.wav
MemberID: "13"

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
FilePath body string true Path/URI of the media file to be played
MemberID body string true ID of member to play media to; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Play Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferencePlayResponse

/v0.1/ConferenceRecordStart/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceRecordStart/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceRecordStart/

Initiates a conference recording

Body parameter

ConferenceName: Room402
FileFormat: wav
FilePath: /tmp/recordings
FileName: Room402Rec

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
FileFormat body string false File format (extension)
FilePath body string false Directory path/URI where the recording file will be saved
FileName body string false Recording file name (without extension); if empty, a timestamp based file name will be generated

Enumerated Values

Parameter Value
FileFormat wav
FileFormat mp3

Example responses

200 Response

{
  "Message": "Conference RecordStart Executed",
  "RecordFile": "/tmp/recordings/sample.mp3",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceRecordStartResponse

/v0.1/ConferenceRecordStop/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceRecordStop/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceRecordStop/

Stops a conference recording

Body parameter

ConferenceName: Room402
RecordFile: /tmp/recording/sample.wav

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
RecordFile body string true Full path to recording file, as returned by ConferenceRecordStart; all shorthand is also available

Example responses

200 Response

{
  "Message": "Conference RecordStop Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceRecordStopResponse

/v0.1/ConferenceSpeak/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceSpeak/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceSpeak/

Plays synthesized speech into a conference

Body parameter

ConferenceName: Room402
Text: The quick brown fox jumps over the lazy dog
MemberID: "13"

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
Text body string true Text to be synthesized
MemberID body string true ID of member to speak to; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Speak Executed",
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceSpeakResponse

/v0.1/ConferenceUndeaf/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceUndeaf/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceUndeaf/

Restores audio to one or more conference members

Body parameter

ConferenceName: Room402
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Undeaf Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceUndeafResponse

/v0.1/ConferenceUnhold/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceUnhold/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceUnhold/

Resume one or more members in the conference context

Body parameter

ConferenceName: Room402
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available too but it is not capable of stopping the music-oh-hold.

Example responses

200 Response

{
  "Message": "Conference Unhold Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceUnholdResponse

/v0.1/ConferenceUnmute/

Code samples

## You can also use wget
curl -X POST /v0.1/ConferenceUnmute/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {access-token}'

POST /v0.1/ConferenceUnmute/

Restores audio from one or more conference members

Body parameter

ConferenceName: Room402
MemberID: 13,42

Parameters

Name In Type Required Description
ConferenceName body string true Name of the conference in question
MemberID body string true List of comma separated member IDs to be affected; all shorthand is available too.

Example responses

200 Response

{
  "Message": "Conference Unmute Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Responses

Status Meaning Description Schema
200 OK Response ConferenceUnmuteResponse

Schemas

BulkCallParameters

{
  "Delimiter": "<",
  "From": "15551234567",
  "To": "15557654321",
  "Gateways": "user/,sofia/gateway/PSTNgateway1/,sofia/gateway/PSTNgateway2/",
  "AnswerUrl": "https://example.com/answer/",
  "RejectCauses": "USER_BUSY,NO_ANSWER",
  "CallerName": "Bulk Test",
  "ConfirmSound": "https://example.com/confirm_sound/",
  "ConfirmKey": "1",
  "HangupUrl": "https://example.com/hangup/",
  "RingUrl": "https://example.com/ring/",
  "ExtraDialString": "bridge_early_media=true,hangup_after_bridge=true",
  "GatewayCodecs": "'PCMA,PCMU','G729,PCMU','PCMA,G729'",
  "GatewayTimeouts": "10,30,20",
  "GatewayRetries": "3,1,2",
  "SendDigits": "1w2w3W#*@1500",
  "SendOnPreanswer": false,
  "TimeLimit": 90,
  "HangupOnRing": 90,
  "CoreUUID": "2e8e6275-7cfe-4e3c-a8d6-25316b4519c7"
}

Properties

Name Type Required Restrictions Description
Delimiter string true none Any character, except / and ,, which will be used as a separator within several parameters
From string true none Phone number to be used as Caller ID
To string true none Phone number to be called
Gateways string true none Comma separated FreeSWITCH gateway strings. When multiple gateways are specified, they will be tried sequentially (failover)
AnswerUrl string true none Fully qualified URL which will provide the RestXML once the call connects
RejectCauses string false none Comma separated reject causes
CallerName string false none Caller Name to be set for the call
ConfirmSound string false none Remote URL to fetch with POST HTTP request which must return a RestXML with Play, Wait and/or Speak Elements only (all others are ignored). This RESTXML is played to the called party when he answered
ConfirmKey string false none DTMF tone the called party must send to accept the call
HangupUrl string false none Fully qualified URL to which the call hangup notification will be POSTed. HangupCause is added to the usual call call notification parameters
RingUrl string false none Fully qualified URL to which the call ringing notification will be POSTed. RequestUUID and CallUUID is added to the usual call notification parameters
ExtraDialString string false none Additional channel variables to be added to the originate FreeSWITCH API call.
GatewayCodecs string false none List of codec(s) to be used for each gateway. Enclose codec groups in single quotes
GatewayTimeouts string false none List of maximum timeout amounts (in seconds) for each gateway
GatewayRetries string false none List of maximum retry counts for each gateway
SendDigits string false none DTMF tones to be sent when the call is answered. Each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
SendOnPreanswer boolean false none When set to true, DTMF tones will be sent as early media rather than when the call is answered
TimeLimit integer false none Schedules the call's hangup at a given time offset (in seconds) after the call is answered
HangupOnRing integer false none Schedules the call's hangup at a given time offset (in seconds) after the destination starts ringing
CoreUUID string false none Core UUID of the desired FreeSWITCH instance (an Eqivo extension)

CallParameters

{
  "From": "15551234567",
  "To": "15557654321",
  "Gateways": "user/,sofia/gateway/PSTNgateway1/,sofia/gateway/PSTNgateway2/",
  "AnswerUrl": "https://example.com/answer/",
  "CallerName": "Test",
  "HangupUrl": "https://example.com/hangup/",
  "RingUrl": "https://example.com/ring/",
  "ExtraDialString": "bridge_early_media=true,hangup_after_bridge=true",
  "GatewayCodecs": "'PCMA,PCMU','G729,PCMU','PCMA,G729'",
  "GatewayTimeouts": "10,30,20",
  "GatewayRetries": "3,1,2",
  "SendDigits": "1w2w3W#*@1500",
  "SendOnPreanswer": false,
  "TimeLimit": 90,
  "HangupOnRing": 90,
  "CoreUUID": "45521fc6-a4b3-42b6-96ad-9136256be216",
  "MachineDetection": "Enable",
  "AsyncAMD": true,
  "AsyncAmdStatusCallbackMethod": "GET",
  "AsyncAmdStatusCallback": "string",
  "MachineDetectionTimeout": 5,
  "MachineDetectionSpeechThreshold": 2000,
  "MachineDetectionSpeechEndThreshold": 1000,
  "MachineDetectionSilenceTimeout": 3000
}

Properties

Name Type Required Restrictions Description
From string true none Phone number to be used as Caller ID
To string true none Phone number to be called
Gateways string true none Comma separated FreeSWITCH gateway strings. When multiple gateways are specified, they will be tried sequentially (failover)
AnswerUrl string true none Fully qualified URL which will provide the RestXML once the call connects
CallerName string false none Caller Name to be set for the call
HangupUrl string false none Fully qualified URL to which the call hangup notification will be POSTed. HangupCause is added to the usual call call notification parameters
RingUrl string false none Fully qualified URL to which the call ringing notification will be POSTed. RequestUUID and CallUUID is added to the usual call notification parameters
ExtraDialString string false none Additional channel variables to be added to the originate FreeSWITCH API call.
GatewayCodecs string false none List of codec(s) to be used for each gateway. Enclose codec groups in single quotes
GatewayTimeouts string false none List of maximum timeout amounts (in seconds) for each gateway
GatewayRetries string false none List of maximum retry counts for each gateway
SendDigits string false none DTMF tones to be sent when the call is answered. Each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
SendOnPreanswer boolean false none When set to true, DTMF tones will be sent as early media rather than when the call is answered
TimeLimit integer false none Schedules the call's hangup at a given time offset (in seconds) after the call is answered
HangupOnRing integer false none Schedules the call's hangup at a given time offset (in seconds) after the destination starts ringing
CoreUUID string false none Core UUID of the desired FreeSWITCH instance (an Eqivo extension)
MachineDetection string false none Enables answering machine detection; optionally, it waits until the greeting message has been played back (an Eqivo extension)
AsyncAMD boolean false none When set to true, the call flow execution is blocked until answering machine detection is complete (an Eqivo extension)
AsyncAmdStatusCallbackMethod string false none HTTP method to be used when answering machine detection is completed (an Eqivo extension)
AsyncAmdStatusCallback string false none Fully qualified URL to which the answering machine detection result will be sent. AnsweredBy and MachineDetectionDuration are appended to the usual call notification parameters (an Eqivo extension)
MachineDetectionTimeout integer false none Amount of time (in seconds) allotted for answering machine detection assessment (an Eqivo extension)
MachineDetectionSpeechThreshold integer false none Speech activity/utterance threshold (in milliseconds, an Eqivo extension)
MachineDetectionSpeechEndThreshold integer false none Silence threshold (in milliseconds, an Eqivo extension)
MachineDetectionSilenceTimeout integer false none Initial silence threshold (in milliseconds, an Eqivo extension)

Enumerated Values

Property Value
MachineDetection Enable
MachineDetection DetectMessageEnd
AsyncAmdStatusCallbackMethod POST
AsyncAmdStatusCallbackMethod GET

CancelScheduledHangupParameters

{
  "SchedHangupId": "ea428fbd-ac9b-498c-8bb2-a36ac49f10fd"
}

Properties

Name Type Required Restrictions Description
SchedHangupId string true none Unique identifier returned when scheduled hangup was originally requested

CancelScheduledPlayParameters

{
  "SchedPlayId": "ea428fbd-ac9b-498c-8bb2-a36ac49f10fd"
}

Properties

Name Type Required Restrictions Description
SchedPlayId string true none Unique identifier returned when scheduled playback was originally requested

ConferenceDeafParameters

{
  "ConferenceName": "Room402",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available too.

ConferenceHangupParameters

{
  "ConferenceName": "Room402",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available too.

ConferenceHoldParameters

{
  "ConferenceName": "Room402",
  "FilePath": "/var/local/media/sample.wav",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
FilePath string true none Path/URI of the media file to be played as music-on-hold
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available however it is not capable of playing back the music-on-hold (i.e. use specific member IDs when MOH is necessary)

ConferenceKickParameters

{
  "ConferenceName": "Room402",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available too.

ConferenceListParameters

{
  "MemberFilter": "13,42",
  "CallUUIDFilter": "872066e1-fd89-4c57-8733-93c113980bc9,55e4214a-604a-4b56-82e4-97834b0d524e",
  "MutedFilter": "true",
  "DeafFilter": "true"
}

Properties

Name Type Required Restrictions Description
MemberFilter string false none Restricts listed members to the provided values (comma separated member ID list)
CallUUIDFilter string false none Restricts listed calls to the provided values (comma separated call UUID list)
MutedFilter boolean false none Restricts listed members to muted ones
DeafFilter boolean false none Restricts listed members to deaf ones

ConferenceListMembersParameters

{
  "ConferenceName": "Room402",
  "MemberFilter": "13,42",
  "CallUUIDFilter": "872066e1-fd89-4c57-8733-93c113980bc9,55e4214a-604a-4b56-82e4-97834b0d524e",
  "MutedFilter": "true",
  "DeafFilter": "true"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference
MemberFilter string false none Restricts listed members to the provided values (comma separated member ID list)
CallUUIDFilter string false none Restricts listed calls to the provided values (comma separated call UUID list)
MutedFilter boolean false none Restricts listed members to muted ones
DeafFilter boolean false none Restricts listed members to deaf ones

ConferenceMuteParameters

{
  "ConferenceName": "Room402",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available too.

ConferencePlayParameters

{
  "ConferenceName": "Room402",
  "FilePath": "/var/local/media/sample.wav",
  "MemberID": "13"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
FilePath string true none Path/URI of the media file to be played
MemberID string true none ID of member to play media to; all shorthand is available too.

ConferenceRecordStartParameters

{
  "ConferenceName": "Room402",
  "FileFormat": "wav",
  "FilePath": "/tmp/recordings",
  "FileName": "Room402Rec"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
FileFormat string false none File format (extension)
FilePath string false none Directory path/URI where the recording file will be saved
FileName string false none Recording file name (without extension); if empty, a timestamp based file name will be generated

Enumerated Values

Property Value
FileFormat wav
FileFormat mp3

ConferenceRecordStopParameters

{
  "ConferenceName": "Room402",
  "RecordFile": "/tmp/recording/sample.wav"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
RecordFile string true none Full path to recording file, as returned by ConferenceRecordStart; all shorthand is also available

ConferenceSpeakParameters

{
  "ConferenceName": "Room402",
  "Text": "The quick brown fox jumps over the lazy dog",
  "MemberID": "13"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
Text string true none Text to be synthesized
MemberID string true none ID of member to speak to; all shorthand is available too.

ConferenceUndeafParameters

{
  "ConferenceName": "Room402",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available too.

ConferenceUnholdParameters

{
  "ConferenceName": "Room402",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available too but it is not capable of stopping the music-oh-hold.

ConferenceUnmuteParameters

{
  "ConferenceName": "Room402",
  "MemberID": "13,42"
}

Properties

Name Type Required Restrictions Description
ConferenceName string true none Name of the conference in question
MemberID string true none List of comma separated member IDs to be affected; all shorthand is available too.

GroupCallParameters

{
  "Delimiter": "<",
  "From": "15551234567",
  "To": "15557654321",
  "Gateways": "user/,sofia/gateway/PSTNgateway1/,sofia/gateway/PSTNgateway2/",
  "AnswerUrl": "https://example.com/answer/",
  "RejectCauses": "USER_BUSY,NO_ANSWER",
  "CallerName": "Group Test",
  "ConfirmSound": "https://example.com/confirm_sound/",
  "ConfirmKey": "1",
  "HangupUrl": "https://example.com/hangup/",
  "RingUrl": "https://example.com/ring/",
  "ExtraDialString": "bridge_early_media=true,hangup_after_bridge=true",
  "GatewayCodecs": "'PCMA,PCMU','G729,PCMU','PCMA,G729'",
  "GatewayTimeouts": "10,30,20",
  "GatewayRetries": "3,1,2",
  "SendDigits": "1w2w3W#*@1500",
  "SendOnPreanswer": false,
  "TimeLimit": 90,
  "HangupOnRing": 90,
  "CoreUUID": "46ae8cd9-c28e-447d-ba40-a09cba49d474"
}

Properties

Name Type Required Restrictions Description
Delimiter string true none Any character, except / and ,, which will be used as a separator within several parameters
From string true none Phone number to be used as Caller ID
To string true none Phone number to be called
Gateways string true none Comma separated FreeSWITCH gateway strings. When multiple gateways are specified, they will be tried sequentially (failover)
AnswerUrl string true none Fully qualified URL which will provide the RestXML once the call connects
RejectCauses string false none Comma separated reject causes
CallerName string false none Caller Name to be set for the call
ConfirmSound string false none Remote URL to fetch with POST HTTP request which must return a RestXML with Play, Wait and/or Speak Elements only (all others are ignored). This RESTXML is played to the called party when he answered
ConfirmKey string false none DTMF tone the called party must send to accept the call
HangupUrl string false none Fully qualified URL to which the call hangup notification will be POSTed. HangupCause is added to the usual call call notification parameters
RingUrl string false none Fully qualified URL to which the call ringing notification will be POSTed. RequestUUID and CallUUID is added to the usual call notification parameters
ExtraDialString string false none Additional channel variables to be added to the originate FreeSWITCH API call.
GatewayCodecs string false none List of codec(s) to be used for each gateway. Enclose codec groups in single quotes
GatewayTimeouts string false none List of maximum timeout amounts (in seconds) for each gateway
GatewayRetries string false none List of maximum retry counts for each gateway
SendDigits string false none DTMF tones to be sent when the call is answered. Each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
SendOnPreanswer boolean false none When set to true, DTMF tones will be sent as early media rather than when the call is answered
TimeLimit integer false none Schedules the call's hangup at a given time offset (in seconds) after the call is answered
HangupOnRing integer false none Schedules the call's hangup at a given time offset (in seconds) after the destination starts ringing
CoreUUID string false none Core UUID of the desired FreeSWITCH instance (an Eqivo extension)

HangupAllCallsParameters

null

Properties

None

HangupCallParameters

{
  "CallUUID": "b0519011-6987-47c8-9270-a820e0978acd",
  "RequestUUID": "c059b96b-04d8-414b-920c-7b373bff916e"
}

Properties

Name Type Required Restrictions Description
CallUUID string false none Unique identifier of the call (when established); this parameter is mutually exclusive with RequestUUID
RequestUUID string false none Unique identifier of the API request (when the call is not established yet); this parameter is mutually exclusive with CallUUID

PlayParameters

{
  "CallUUID": "e69b32da-3243-4ba6-a965-5d2f64a57d48",
  "Sounds": "/tmp/prompt.wav",
  "Legs": "both",
  "Length": 90,
  "Loop": true,
  "Mix": false
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call to play media into
Sounds string true none Comma separated list of file paths/URIs to be played
Legs string false none Call leg(s) for which the media will be played; aleg refers to the initial call leg, bleg refers to the bridged call leg, if applicable.
Length integer false none Maximum amount of time (in seconds) to playback the media
Loop boolean false none Loops the media file(s) indefinitely
Mix boolean false none Whether the media should be mixed with the call's audio stream

Enumerated Values

Property Value
Legs aleg
Legs bleg
Legs both

PlayStopParameters

{
  "CallUUID": "441afb63-85bc-49d4-9ac8-8459f9bf5e6b"
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call

RecordStartParameters

{
  "CallUUID": "052d04e4-019a-45ff-a562-f74d4ae99ea2",
  "FileFormat": "wav",
  "FilePath": "/tmp/recordings",
  "FileName": "sample_recording",
  "TimeLimit": 89
}

Properties

Name Type Required Restrictions Description
CallUUID string false none Unique identifier of the call to be recorded
FileFormat string false none File format (extension)
FilePath string false none Directory path/URI where the recording file will be saved
FileName string false none Recording file name (without extension); if empty, a timestamp based file name will be generated
TimeLimit integer false none Maximum recording length, in seconds

Enumerated Values

Property Value
FileFormat wav
FileFormat mp3

RecordStopParameters

{
  "CallUUID": "eacfa857-4001-4379-b79a-c7ef6d963bcb",
  "RecordFile": "/tmp/recording/sample.wav"
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call
RecordFile string true none Full path to recording file, as returned by RecordStart; all shorthand is also available

ScheduleHangupParameters

{
  "CallUUID": "f84fbadc-5df0-4c02-934b-aac0c1efb8ae",
  "Time": 59
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call
Time integer true none Time (in seconds) after which the call in question will be hung up

SchedulePlayParameters

{
  "CallUUID": "e69b32da-3243-4ba6-a965-5d2f64a57d48",
  "Sounds": "/tmp/prompt.wav",
  "Time": 29,
  "Legs": "both",
  "Length": 90,
  "Loop": true,
  "Mix": false
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call to play media into
Sounds string true none Comma separated list of file paths/URIs to be played
Time integer true none Time (in seconds) after which the media will be playedback
Legs string false none Call leg(s) for which the media will be played; aleg refers to the initial call leg, bleg refers to the bridged call leg, if applicable.
Length integer false none Maximum amount of time (in seconds) to playback the media
Loop boolean false none Loops the media file(s) indefinitely
Mix boolean false none Whether the media should be mixed with the call's audio stream

Enumerated Values

Property Value
Legs aleg
Legs bleg
Legs both

SendDigitsParameters

{
  "CallUUID": "d4cd08fe-4245-490a-ae39-5b58c6addbe8",
  "Digits": "1w2w3W#*@1500",
  "Leg": "both"
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call to send DTMF to
Digits string true none DTMF tones to be sent; each occurrence of w implies a 0.5 seconds delay whereas W will apply a whole second delay. To alter the tone duration (by default, 2000ms), append @ and the length in milliseconds at the end of the string
Leg string false none Call leg(s) to which DTMFs will be sent; aleg refers to the initial call leg, bleg refers to the bridged call leg, if applicable.

Enumerated Values

Property Value
Leg aleg
Leg bleg
Leg both

SoundTouchParameters

{
  "CallUUID": "b7054b68-0620-455a-8ac7-f8f126853b9d",
  "AudioDirection": "in",
  "PitchSemiTones": 2,
  "PitchOctaves": 0.5,
  "Pitch": 4,
  "Rate": 3,
  "Tempo": 2
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call to send DTMF to
AudioDirection string false none Media stream to be altered, incoming or outgoing
PitchSemiTones number(float) false none Adjust the pitch in semitones
PitchOctaves number(float) false none Adjust the pitch in octaves
Pitch number(float) false none Adjust the pitch
Rate number(float) false none Adjust the rate
Tempo number(float) false none Adjust the tempo

Enumerated Values

Property Value
AudioDirection in
AudioDirection out

SoundTouchStopParameters

{
  "CallUUID": "fe372011-face-4bc2-bbcc-893d045bf67d"
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call

TransferCallParameters

{
  "CallUUID": "03694cf6-62b3-4f00-b0fc-6831ddcc2693",
  "Url": "https://example.org/restxml/endpoint/"
}

Properties

Name Type Required Restrictions Description
CallUUID string true none Unique identifier of the call
Url string true none Absolute URL which will return the updated RestXML flow

BulkCallResponse

{
  "Message": "BulkCalls Request Executed",
  "RequestUUID": [
    "fc92f3f4-3777-43ed-b269-5b4a0d474b12",
    "22f94a34-2890-4f18-ab99-5c47e25dd3c3",
    "d1337342-0225-465d-b7bb-1b5d88eb39d2"
  ],
  "Success": true,
  "RestApiServer": "localhost"
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
RequestUUID [string] true none Unique identifiers of each Call request (UUIDv4)
Success boolean true none Whether the request was successful or not
RestApiServer string true none API server which handled this request (an Eqivo extension)

Enumerated Values

Property Value
Message BulkCalls Request Executed
Message Mandatory Parameters Missing
Message This Delimiter is not allowed
Message BulkCalls should be used for at least 2 numbers
Message 'To' parameter length does not match 'Gateways' Length
Message AnswerUrl is not Valid
Message HangupUrl is not Valid
Message RingUrl is not Valid
Message Unknown Core UUID

CallResponse

{
  "Message": "Call Request Executed",
  "RequestUUID": "fc92f3f4-3777-43ed-b269-5b4a0d474b12",
  "Success": true,
  "RestApiServer": "localhost"
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
RequestUUID string true none Unique identifier of the Call request (UUIDv4)
Success boolean true none Whether the request was successful or not
RestApiServer string true none API server which handled this request (an Eqivo extension)

Enumerated Values

Property Value
Message Call Request Executed
Message Mandatory Parameters Missing
Message AnswerUrl is not Valid
Message HangupUrl is not Valid
Message RingUrl is not Valid
Message Unknown Core UUID

CancelScheduledHangupResponse

{
  "Message": "Scheduled Hangup Cancelation Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Scheduled Hangup Cancelation Executed
Message SchedHangupId Parameter must be present
Message Scheduled Hangup Cancelation Failed -- ID not found
Message Scheduled Hangup Cancelation Failed

CancelScheduledPlayResponse

{
  "Message": "Scheduled Play Cancelation Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Scheduled Play Cancelation Executed
Message SchedPlayId Parameter must be present
Message Scheduled Play Cancelation Failed -- ID not found
Message Scheduled Play Cancelation Failed

ConferenceDeafResponse

{
  "Message": "Conference Deaf Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Deaf Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Deaf Failed -- Conference not found

ConferenceHangupResponse

{
  "Message": "Conference Hangup Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Hangup Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Hangup Failed -- Conference not found

ConferenceHoldResponse

{
  "Message": "Conference Hold Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Hold Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Hold Failed -- Conference not found

ConferenceKickResponse

{
  "Message": "Conference Kick Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Kick Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Kick Failed -- Conference not found

ConferenceListResponse

{
  "Message": "Conference List Executed",
  "Success": true,
  "List": {
    "Room402": {
      "ConferenceMemberCount": "1",
      "ConferenceName": "Room402",
      "ConferenceRunTime": "79",
      "ConferenceUUID": "5105acbf-6d43-4d67-8536-19999924eba4",
      "Members": [
        {
          "Muted": false,
          "Deaf": false,
          "MemberID": "14",
          "CallNumber": "3985",
          "CallName": "DeskPhone985",
          "CallUUID": "8f72b48e-d97e-425a-a6e6-ae5a6a0dc231",
          "JoinTime": "79"
        }
      ]
    },
    "Room555": {
      "ConferenceMemberCount": "1",
      "ConferenceName": "Room555",
      "ConferenceRunTime": "28",
      "ConferenceUUID": "732fab2d-1bff-4b54-8d3e-bd937b8ff662",
      "Members": [
        {
          "Muted": false,
          "Deaf": false,
          "MemberID": "14",
          "CallNumber": "2002",
          "CallName": "GuestCenter2",
          "CallUUID": "f8a79c36-2567-479d-b4d9-08f4165f8767",
          "JoinTime": "28"
        }
      ]
    }
  }
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not
List object true none List of established conferences

Enumerated Values

Property Value
Message Conference List Executed
Message Conference List Failed to parse result

ConferenceListMembersResponse

{
  "Message": "Conference ListMembers Executed",
  "Success": true,
  "List": {
    "Room402": {
      "ConferenceMemberCount": "1",
      "ConferenceName": "Room402",
      "ConferenceRunTime": "79",
      "ConferenceUUID": "5105acbf-6d43-4d67-8536-19999924eba4",
      "Members": [
        {
          "Muted": false,
          "Deaf": false,
          "MemberID": "14",
          "CallNumber": "3985",
          "CallName": "DeskPhone985",
          "CallUUID": "8f72b48e-d97e-425a-a6e6-ae5a6a0dc231",
          "JoinTime": "79"
        }
      ]
    }
  }
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not
List object true none List of established conferences

Enumerated Values

Property Value
Message Conference ListMembers Executed
Message ConferenceName Parameter must be present
Message Conference ListMembers Failed to parse result
Message Conference ListMembers Failed -- Conference not found

ConferenceMuteResponse

{
  "Message": "Conference Mute Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Mute Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Mute Failed -- Conference not found

ConferencePlayResponse

{
  "Message": "Conference Play Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Play Executed
Message ConferenceName Parameter must be present
Message FilePath Parameter must be present
Message MemberID Parameter must be present
Message Conference Play Failed -- Conference not found
Message Conference Play Failed

ConferenceRecordStartResponse

{
  "Message": "Conference RecordStart Executed",
  "RecordFile": "/tmp/recordings/sample.mp3",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
RecordFile string true none Directory path/URI where the recording file will be saved
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference RecordStart Executed
Message ConferenceName Parameter must be present
Message FileFormat Parameter must be
Message Conference RecordStart Failed
Message Conference RecordStart Failed -- Conference not found

ConferenceRecordStopResponse

{
  "Message": "Conference RecordStop Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference RecordStop Executed
Message ConferenceName Parameter must be present
Message RecordFile Parameter must be present
Message Conference RecordStop Failed
Message Conference RecordStop Failed -- Conference not found

ConferenceSpeakResponse

{
  "Message": "Conference Speak Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Speak Executed
Message ConferenceName Parameter must be present
Message Text Parameter must be present
Message MemberID Parameter must be present
Message Conference Speak Failed -- Conference not found
Message Conference Speak Failed

ConferenceUndeafResponse

{
  "Message": "Conference Undeaf Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Undeaf Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Undeaf Failed -- Conference not found

ConferenceUnholdResponse

{
  "Message": "Conference Unhold Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Unhold Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Unhold Failed -- Conference not found

ConferenceUnmuteResponse

{
  "Message": "Conference Unmute Executed",
  "Members": [
    "13",
    "42"
  ],
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Members [string] false none List of affected members
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Conference Unmute Executed
Message ConferenceName Parameter must be present
Message MemberID Parameter must be present
Message Conference Unmute Failed -- Conference not found

GroupCallResponse

{
  "Message": "GroupCall Request Executed",
  "RequestUUID": "fc01f3f4-4895-43ed-b269-5b4a0d474b12",
  "Success": true,
  "RestApiServer": "localhost"
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
RequestUUID string true none Unique identifier of the Call request (UUIDv4)
Success boolean true none Whether the request was successful or not
RestApiServer string true none API server which handled this request (an Eqivo extension)

Enumerated Values

Property Value
Message GroupCall Request Executed
Message Mandatory Parameters Missing
Message This Delimiter is not allowed
Message GroupCall should be used for at least 2 numbers
Message 'To' parameter length does not match 'Gateways' Length
Message AnswerUrl is not Valid
Message HangupUrl is not Valid
Message RingUrl is not Valid
Message ConfirmSound is not Valid
Message Unknown Core UUID
Message GroupCall Request Failed

HangupAllCallsResponse

{
  "Message": "All Calls Hungup",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message All Calls Hungup
Message Hangup Call Failed

HangupCallResponse

{
  "Message": "Hangup Call Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Hangup Call Executed
Message CallUUID or RequestUUID Parameter must be present
Message Both CallUUID and RequestUUID Parameters cannot be present
Message Hangup Call Failed

PlayResponse

{
  "Message": "Play Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Play Executed
Message CallUUID Parameter Missing
Message Sounds Parameter Missing
Message Legs Parameter is Invalid
Message Length Parameter must be a positive integer
Message Sounds Parameter is Invalid
Message Play Failed -- Call not found
Message Play Failed

PlayStopResponse

{
  "Message": "PlayStop Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message PlayStop Executed
Message CallUUID Parameter Missing
Message PlayStop Failed -- Call not found
Message PlayStop Failed

RecordStartResponse

{
  "Message": "RecordStart Executed",
  "RecordFile": "/tmp/recordings/sample.wav",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
RecordFile string true none Directory path/URI where the recording file will be saved
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message RecordStart Executed
Message CallUUID Parameter must be present
Message FileFormat Parameter must be
Message RecordStart Failed: invalid TimeLimit
Message RecordStart Failed -- Call not found
Message RecordStart Failed

RecordStopResponse

{
  "Message": "RecordStop Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message RecordStop Executed
Message CallUUID Parameter must be present
Message RecordFile Parameter must be present
Message RecordStop Failed -- Call not found
Message RecordStop Failed

ScheduleHangupResponse

{
  "Message": "ScheduleHangup Executed",
  "Success": true,
  "SchedHangupId": "21579000-0dca-4a75-bc1f-6eae8215a611"
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not
SchedHangupId string true none Unique identifier of the scheduled hangup request (UUIDv4)

Enumerated Values

Property Value
Message ScheduleHangup Executed
Message CallUUID Parameter must be present
Message Time Parameter must be present
Message Time Parameter must be > 0!
Message ScheduleHangup Failed -- Call not found
Message ScheduleHangup Failed

SchedulePlayResponse

{
  "Message": "Play Executed",
  "Success": true,
  "SchedPlayId": "b2d1da90-c364-42e4-818a-2eb90a474729"
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not
SchedPlayId string true none Unique identifier of the scheduled playback request (UUIDv4)

Enumerated Values

Property Value
Message Play Executed
Message CallUUID Parameter Missing
Message Sounds Parameter Missing
Message Time Parameter Missing
Message Time Parameter must be > 0
Message Legs Parameter is Invalid
Message Length Parameter must be a positive integer
Message Sounds Parameter is Invalid
Message Play Failed -- Call not found
Message Play Failed

SendDigitsResponse

{
  "Message": "SendDigits Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message SendDigits Executed
Message CallUUID Parameter Missing
Message Digits Parameter Missing
Message Invalid Leg Parameter
Message SendDigits Failed -- Call not found
Message SendDigits Failed

SoundTouchResponse

{
  "Message": "SoundTouch Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message SoundTouch Executed
Message CallUUID Parameter Missing
Message AudioDirection Parameter Must be 'in' or 'out'
Message PitchSemiTones Parameter must be float
Message PitchSemiTones Parameter must be between -14 and 14
Message PitchOctaves Parameter must be float
Message PitchOctaves Parameter must be between -1 and 1
Message Pitch Parameter must be float
Message Pitch Parameter must be > 0
Message Rate Parameter must be float
Message Rate Parameter must be > 0
Message Tempo Parameter must be float
Message Tempo Parameter must be > 0
Message SoundTouch Failed -- Call not found
Message SoundTouch Failed

SoundTouchStopResponse

{
  "Message": "SoundTouchStop Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message SoundTouchStop Executed
Message CallUUID Parameter Missing
Message SoundTouchStop Failed -- Call not found
Message SoundTouchStop Failed

TransferCallResponse

{
  "Message": "Transfer Call Executed",
  "Success": true
}

Properties

Name Type Required Restrictions Description
Message string true none Response message
Success boolean true none Whether the request was successful or not

Enumerated Values

Property Value
Message Transfer Call Executed
Message CallUUID Parameter must be present
Message Url Parameter must be present
Message Url is not Valid
Message Transfer Call Failed -- Call not found
Message Transfer Call Failed

CallNotificationParameters

{
  "RestApiServer": "localhost",
  "CoreUUID": "b14e0893-98ef-44b6-8e4b-e4bcf937bfa9",
  "CallUUID": "7ff22856-357e-4b77-812c-22d28cbb8982",
  "CallStatus": "in-progress",
  "ALegUUID": "8dd5a1e0-6621-4a07-98b3-e033b014fba7",
  "ALegRequestUUID": "5a4ef7cf-dc08-4cd3-a9d0-6d1555ba3309",
  "CallerName": "Alice",
  "From": "15557654321",
  "To": "15551234567",
  "ScheduledHangupId": "8f4a3488-3283-408b-bf6f-b957d5d4cf00",
  "ForwardedFrom": "15551239876",
  "Direction": "outbound",
  "MachineDetectionDuration": "19",
  "AnsweredBy": "human"
}

Properties

Name Type Required Restrictions Description
RestApiServer string true none Eqivo Rest API server which controls the call (Eqivo extension)
CoreUUID string true none FreeSWITCH's instance unique identifier (Eqivo extension)
CallUUID string true none Call's unique identifier, assigned by FreeSWITCH
CallStatus string true none Call's current status
ALegUUID string false none A leg call's unique identifier, assigned by FreeSWITCH
ALegRequestUUID string false none A leg call request's unique identifier
CallerName string true none Caller name set for the call
From string true none Caller ID set for the call
To string true none Called phone number
ScheduledHangupId string false none Unique identifier of the scheduled hangup task
ForwardedFrom string false none Original call destination (before diversion)
Direction string true none Call's direction
MachineDetectionDuration integer false none Actual answering machine detection assessment duration (in milliseconds)
AnsweredBy string false none Answering actor, when answering machine detection is enabled

Enumerated Values

Property Value
CallStatus ringing
CallStatus early-media
CallStatus answer
CallStatus in-progress
CallStatus completed
Direction inbound
Direction outbound
AnsweredBy machine_start
AnsweredBy machine_end_beep
AnsweredBy machine_end_other
AnsweredBy human
AnsweredBy unknown

Errors

Error Code Meaning
400 Bad Request -- Request is invalid
401 Unauthorized -- Basic authentication failed and/or requestor IP address is not in part of an allowed range
404 Not Found -- Unknown API method
405 Method Not Allowed -- Unsupported method (only POST is supported)
500 Internal Server Error -- Failure internal to Eqivo, most likely a bug

Security

While the legacy framework did not explicitly outline any specific security notes, the same principles apply here too. Below is a non-exhaustive checklist one should follow:

API Tokens

By default, the application requires Basic authentication on all API requests. Generating token pairs with high complexity/good entropy is crucial.

Rotating tokens periodically is definitely good practice; running Eqivo as a container will make token rotation much easier, and if using an orchestrating framework, chances are it already comes with a secure secrets manager.

Allowed IP/CIDR

By default, Eqivo requires a list of IP addresses and/or CIDR ranges allowed to make API calls; make sure these are indeed limited only to machines entitled to access the Eqivo API.

Under no circumstances Eqivo should be ever publicly exposed!

RestXML Requests

When Eqivo fires RestXML requests to your endpoints, it includes a X-EQIVO-SIGNATURE header which is essentially a HMAC digest hash calculated as follows:

You should validate the signature header on all incoming requests to make sure they are trustworthy.

Input Sanitation

The Eqivo API should be invoked only with cleansed payloads. This is further crucial for parameters which originate from user input, e.g. Phone Numbers, Caller Names etc.

Source code on GitHub