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

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:

• employ RFC 7617 Basic authentication, the Authorization header must be included in every request;
• use POST method for all calls. Parameters must be application/x-www-form-urlencoded endcoded;
• expect a JSON response for successful requests as well as application-level errors.

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.

• Type: bool (default: false)
• Legacy configuration file property: n/a
• Command line argument: --daemon
• Environment variable: EQIVO_DAEMONIZE

userName

Runs Eqivo as an alternate user.

• Type: string
• Legacy configuration file property: rest_server.USER
• Command line argument: --user <user>
• Environment variable: EQIVO_USER

groupName

Runs Eqivo as a member of an alternate group.

• Type: string
• Legacy configuration file property: rest_server.GROUP
• Command line argument: --group <group>
• Environment variable: EQIVO_GROUP

appPrefix

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

• Type: string (default: eqivo)
• Legacy configuration file property: n/a
• Command line argument: --app-prefix <prefix>
• Environment variable: EQIVO_APP_PREFIX

pidFile

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

• Type: string (default: /tmp/eqivo.pid)
• Legacy configuration file property: n/a
• Command line argument: --pidfile <path>
• Environment variable: EQIVO_PID_FILE

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.

• Type: string
• Legacy configuration file property: n/a
• Command line argument: --config <path>
• Environment variable: _n/a_

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.

• Type: array (default: [])
• Legacy configuration file properties:
  • rest_server.FS_INBOUND_ADDRESS
  • rest_server.FS_INBOUND_PASSWORD
• Command line argument: --core <corespec> (can be used multiple times)
• Environment variable: EQIVO_CORE_0, EQIVO_CORE_1 and so forth

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

• Type: string (default: POST)
• Legacy configuration file property: common.DEFAULT_HTTP_METHOD
• Command line argument: --default-http-method <method>
• Environment variable: EQIVO_DEFAULT_HTTP_METHOD

defaultAnswerUrl

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

• Type: string
• Legacy configuration file property: common.DEFAULT_ANSWER_URL
• Command line argument: --default-answer-url <url>
• Environment variable: EQIVO_DEFAULT_ANSWER_URL

defaultHangupUrl

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

• Type: string
• Legacy configuration file property: common.DEFAULT_HANGUP_URL
• Command line argument: --default-hangup-url <url>
• Environment variable: EQIVO_DEFAULT_HANGUP_URL

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.

• Type: array (default: [])
• Legacy configuration file property: common.EXTRA_FS_VARS
• Command line argument: --extra-channel-vars <list>
• Environment variable: EQIVO_EXTRA_CHANNEL_VARS

verifyPeer

Requires verification of TLS certificates presented by remote endpoints.

• Type: bool (default: true)
• Legacy configuration file property: n/a
• Command line argument: --verify-peer <bool>
• Environment variable: EQIVO_VERIFY_PEER

verifyPeerName

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

• Type: bool (default: true)
• Legacy configuration file property: n/a
• Command line argument: --verify-peer-name <bool>
• Environment variable: EQIVO_VERIFY_PEER_NAME

restServerBindIp

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

• Type: string (default: 0.0.0.0)
• Legacy configuration file property: IP portion of rest_server.HTTP_ADDRESS
• Command line argument: IP portion of --rest-bind-address <ip:port>
• Environment variable: IP portion of EQIVO_REST_BIND_ADDRESS

restServerBindPort

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

• Type: int (default: 8088)
• Legacy configuration file property: port portion of rest_server.HTTP_ADDRESS
• Command line argument: port portion of --rest-bind-address <ip:port>
• Environment variable: port portion of EQIVO_REST_BIND_ADDRESS

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.

• Type: string
• Legacy configuration file property: n/a
• Command line argument: --rest-advertised-host <host>
• Environment variable: EQIVO_REST_ADVERTISED_HOST

restServerMaxHandlers

Number of concurrent request buffering handles for the REST server.

• Type: int (default: 1024)
• Legacy configuration file property: n/a
• Command line argument: --rest-max-handlers <int>
• Environment variable: EQIVO_REST_MAX_HANDLERS

restServerMaxRequestSize

Maximum buffering size per REST request.

• Type: int (default: 16384)
• Legacy configuration file property: n/a
• Command line argument: --rest-max-request-size <int>
• Environment variable: EQIVO_REST_MAX_REQUEST_SIZE

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.

• Type: string (default: DEBUG)
• Legacy configuration file property: rest_server.LOG_LEVEL
• Command line argument: --rest-log-level <level>
• Environment variable: EQIVO_REST_LOG_LEVEL

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.

• Type: array (default: [])
• Legacy configuration file property: rest_server.ALLOWED_IPS
• Command line argument: --rest-allowed-ips <list>
• Environment variable: EQIVO_REST_ALLOWED_IPS

restAuthId

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

• Type: string
• Legacy configuration file property: common.AUTH_ID
• Command line argument: --rest-auth-id <secret>
• Environment variable: EQIVO_REST_AUTH_ID

restAuthToken

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

• Type: string
• Legacy configuration file property: common.AUTH_TOKEN
• Command line argument: --rest-auth-token <secret>
• Environment variable: EQIVO_REST_AUTH_TOKEN

recordUrl

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

• Type: string
• Legacy configuration file property: rest_server.RECORD_URL
• Command line argument: --record-url <url>
• Environment variable: EQIVO_RECORD_URL

outboundServerBindIp

IP address the Outbound server will be bound to.

• Type: string (default: 0.0.0.0)
• Legacy configuration file property: IP portion of outbound_server.FS_OUTBOUND_ADDRESS
• Command line argument: IP portion of --outbound-bind-address <ip:port>
• Environment variable: IP portion of EQIVO_OUTBOUND_BIND_ADDRESS

outboundServerBindPort

TCP port the Outbound server will be bound to.

• Type: int (default: 8084)
• Legacy configuration file property: port portion of outbound_server.FS_OUTBOUND_ADDRESS
• Command line argument: port portion of --outbound-bind-address <ip:port>
• Environment variable: port portion of EQIVO_OUTBOUND_BIND_ADDRESS

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.

• Type: string (default: 127.0.0.1)
• Legacy configuration file property: n/a
• Command line argument: IP portion of --outbound-advertised-address <ip:port>
• Environment variable: IP portion of EQIVO_OUTBOUND_ADVERTISED_ADDRESS

outboundServerAdvertisedPort

TCP port relayed to FreeSWITCH. See outboundServerAdvertisedPort.

• Type: int
• Legacy configuration file property: n/a
• Command line argument: port portion of --outbound-advertised-address <ip:port>
• Environment variable: port portion of EQIVO_OUTBOUND_ADVERTISED_ADDRESS

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.

• Type: string (default: DEBUG)
• Legacy configuration file property: outbound_server.LOG_LEVEL
• Command line argument: --outbound-log-level <level>
• Environment variable: EQIVO_OUTBOUND_LOG_LEVEL

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.

• Type: string (default: DEBUG)
• Legacy configuration file property: rest_server.LOG_LEVEL
• Command line argument: --inbound-log-level <level>
• Environment variable: EQIVO_INBOUND_LOG_LEVEL

callHeartbeatUrl

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

• Type: string
• Legacy configuration file property: rest_server.CALL_HEARTBEAT_URL
• Command line argument: --call-heartbeat-url <url>
• Environment variable: EQIVO_CALL_HEARTBEAT_URL

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:

• naming of conference rooms is up to your application's use case;
• capacity (maximum amount of participants) can be controlled via FreeSWITCH, yet capped by system's resources;
• conferences don't effectively start until at least two members are present;
• whilst alone, music-on-hold can be played back;
• when members enter and exit, notification sounds can be played.

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.

• Type: bool
• Default: false

enterSound

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

• Type: one of (empty), beep:1, beep:2
• Default: (empty)

exitSound

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

• Type: one of (empty), beep:1, beep:2
• Default: (empty)

startConferenceOnEnter

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

• Type: bool
• Default: true

endConferenceOnExit

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

• Type: bool
• Default: false

stayAlone

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

• Type: bool
• Default: true

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.

• Type: string (URL serving RestXML)

maxMembers

Maximum number of members to be allowed into the room.

• Type: int (> 0)
• Default: 200

timeLimit

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

• Type: int (>= 0)
• Default: 0

hangupOnStar

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

• Type: bool
• Default: false

recordFilePath

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

• Type: string (URL or path)
• Default: (empty)

recordFileFormat

Recording file format.

• Type: one of wav or mp3
• Default: mp3

recordFileName

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

• Type: string
• Default: (empty)

action

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

• Type: string (absolute URL)

method

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

• Type: one of POST or GET
• Default: POST

callbackUrl

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

• Type: string (absolute URL)

callbackMethod

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

• Type: one of POST or GET
• Default: POST

digitsMatch

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

• Type: string
• Example: #11,000,9

floorEvent

Whether floor-change events should be sent to callbackUrl.

• Type: bool
• Default: false

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.

• Type: string (absolute URL)
• Default: (empty)

method

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

• Type: one of POST or GET
• Default: POST

hangupOnStar

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

• Type: bool
• Default: false

timeLimit

Maximum lifetime of the bridged call, in seconds.

• Type: int (> 0)
• Default: 14400

timeout

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

• Type: int (> 0)
• Default: (indefinite)

callerId

Caller ID to be presented to the remote party.

• Type: string

callerName

Caller Name to be presented to the remote party.

• Type: string

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.

• Type: string (URL serving RestXML)

confirmKey

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

• Type: string (DTMF tone)

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

• Type: string (URL serving RestXML)
• Default: (empty)

callbackUrl

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

• Type: string (absolute URL)

callbackMethod

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

• Type: one of POST or GET
• Default: POST

digitsMatch

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

• Type: string
• Example: #11,000,9

redirect

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

• Type: bool
• Default: true

Number element attributes

sendDigits

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

• Type: string

sendOnPreanswer

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

• Type: bool
• Default: false

gateways

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

• Type: string

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'.

• Type: string

gatewayTimeouts

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

• Type: string

gatewayRetries

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

• Type: string

extraDialString

Additional variables to be appended to the originate FreeSWITCH command.

• Type: string

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.

• Type: string (absolute URL)
• Default: (empty)

method

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

• Type: one of POST or GET
• Default: POST

timeout

How long to wait for DTMF tones, in seconds.

• Type: int (> 0)
• Default: 5

finishOnKey

Single DTMF tone which will end the collection.

• Type: string
• Default: #

numDigits

Total amount of tones to collect.

• Type: int (> 0)
• Default: 99

retries

Total collection attempts.

• Type: int (> 0)
• Default: 1

playBeep

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

• Type: bool
• Default: false

validDigits

Acceptable DTMF tones.

• Type: string
• Default: 1234567890*#

invalidDigitsSound

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

• Type: string

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.

• Type: string (absolute URL)
• Default: (empty)

method

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

• Type: one of POST or GET
• Default: POST

timeout

How long to wait for speech, in seconds.

• Type: int (> 0)
• Default: 5

engine

FreeSWITCH speech-to-text/ASR engine.

• Type: string
• Default: pocketsphinx

grammar

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

• Type: string

playBeep

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

• Type: bool
• Default: false

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.

• Type: one of rejected or busy

schedule

Schedules the hangup at a future point in time.

• Type: int (> 0)
• Default: (empty)

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.

• Type: int (> 0)
• Default: 1

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

• <Speak>
• <Play>
• <Wait>
• <GetDigits>
• <GetSpeech>
• <Redirect>
• <SIPTransfer>

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.

• Type: string (absolute URL)
• Default: (empty)

method

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

• Type: one of POST or GET
• Default: POST

redirect

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

• Type: bool
• Default: true

timeout

Maximum seconds of silence before considering the recording complete.

• Type: int (> 0)
• Default: 15

finishOnKey

Single DTMF tone which will end the recording.

• Type: string
• Default: 1234567890*#

maxLength

Maximum recording length.

• Type: int (> 0)
• Default: 60

playBeep

Whether to play a brief beep sound before recording commences.

• Type: bool
• Default: true

filePath

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

• Type: string

filePath

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

• Type: string

fileFormat

Recording file format.

• Type: one of wav or mp3
• Default: mp3

fileName

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

• Type: string
• Default: (empty)

bothLegs

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

• Type: bool
• Default: false

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.

• Type: one of POST or GET
• Default: POST

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).

• Type: string
• Default: flite

voice

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

• Type: string
• Default: slt

language

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

• Type: string
• Default: en

loop

Times to play the generated media.

• Type: int (> 0)
• Default: 1

type

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

• Type: string

method

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

• Type: string

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

• Type: int (> 0)
• Default: 1

RestAPI

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

• Call oriented methods
• Conference oriented methods

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

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

/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

Enumerated Values

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

/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

Example responses

200 Response

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

Responses

/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

Enumerated Values

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Enumerated Values

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Enumerated Values

Example responses

200 Response

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

Responses

/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

Enumerated Values

Example responses

200 Response

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

Responses

/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

Enumerated Values

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

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

/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

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

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Enumerated Values

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

/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

Example responses

200 Response

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

Responses

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

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

Enumerated Values

CancelScheduledHangupParameters

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

Properties

CancelScheduledPlayParameters

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

Properties

ConferenceDeafParameters

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

Properties

ConferenceHangupParameters

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

Properties

ConferenceHoldParameters

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

Properties

ConferenceKickParameters

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

Properties

ConferenceListParameters

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

Properties

ConferenceListMembersParameters

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

Properties

ConferenceMuteParameters

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

Properties

ConferencePlayParameters

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

Properties

ConferenceRecordStartParameters

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

Properties

Enumerated Values

ConferenceRecordStopParameters

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

Properties

ConferenceSpeakParameters

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

Properties

ConferenceUndeafParameters

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

Properties

ConferenceUnholdParameters

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

Properties

ConferenceUnmuteParameters

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

Properties

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

HangupAllCallsParameters

null

Properties

None

HangupCallParameters

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

Properties

PlayParameters

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

Properties

Enumerated Values

PlayStopParameters

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

Properties

RecordStartParameters

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

Properties

Enumerated Values

RecordStopParameters

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

Properties

ScheduleHangupParameters

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

Properties

SchedulePlayParameters

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

Properties