About conference services
The Conference Web Services APIs allow the administrator to send commands to the FreeSwitch platform.
Base URL
The base URL for the Conference web services is:
https://\{user id}:{password}@{admin config host name}/sipxconfig/rest/my/conference/{conference-name}
For the above URL you can use the /{command}&{arg 1}&{arg 2}... URL with the PUT HTTP method to send the desired commands and arguments to FreeSwitch.
Available FreeSwitch commands and arguments
Command name | Command details | Usage |
---|---|---|
bgdial | <endpoint_module_name>/<destination> <callerid number> <callerid name> | |
deaf | Make a conference member deaf. | <[member_id|all]|last> |
dial | Dial a destination via a specific endpoint. For more information, click here. | <endpoint_module_name>/<destination> <callerid number> <callerid name> |
dtmf | Send DTMF to any member of the conference. | <[member_id|all|last]> <digits> |
energy | Adjusts the conference energy level for a specific member. | <member_id|all|last> [<newval>] |
hup | Kick without the kick sound. | conference <confname> hup <[member_id|all|last]> |
kick | Kicks a specific member form a conference. | <[member_id|all|last]> |
list | Lists all or a specific conference members. For more information, click here. | conference list [delim <string>] |
conference <confname> list [delim <string>] | ||
lock | Lock a conference so no new members will be allowed to enter. | lock |
mute | Mutes a specific member in a conference. | <[member_id|all]|last> |
norecord | <[filename|all]> | |
nopin | Removes a pin for a specific conference. | nopin |
pin | Sets or changes a pin number for a specific conference. Note: if you set a conference pin and then issue a command like | <pin#> |
play | Play an audio file in a conference to all members or to a specific member. You can stop that same audio with the Stop command below. | <file_path> [async|<member_id>] |
record | <filename> | |
relate | Mute or Deaf a specific member to another member. For more information, click here. | <member_id> <other_member_id> [nospeak|nohear|clear] |
say | Write a message to all members in the conference. | <text> |
saymember | Write a messaget to a specific member in a conference. | <member_id> <text> |
stop | Stops any queued audio from playing. | <[current|all|async|last]> [<member_id>] |
transfer | Transfer a member from one conference to another conference. To transfer a member to another extension use the api transfer command with the uuid of their session. | <conference_name> <member id> [...<member id>] |
unmute | Unmute a specific member of a conference. | <[member_id|all]|last> |
undeaf | Allow a specific member to hear the conference.. | <[member_id|all]|last> |
unlock | Unlock a conference so that new members can enter. | unlock |
volume_in | Adjusts the input volume for a specific conference member. | <member_id|all|last> [<newval>] |
volume_out | Adjusts the output volume for a specific conference member. | <member_id|all|last> [<newval>] |
xml_list |
Specific response codes:
Error 404 - when {confName} not found
Error 403 - when authenticated user is not owner of {confName}
Error 400 - when no {command} is specified or the command is incorect
Dial Additional Information
If the caller ID values are not set, the variables set in the conference.conf.xml are used. Specifically, the value for caller-id-number is used for the number and the value for caller-id-name is used for the name.
If the conference is dynamically created as a result of this API and the caller-id-number and caller-id-number is not provided in the API call then the number and name will be "00000000" and respectively "FreeSWITCH".
Example:
conference testconf dial {originate_timeout=30}sofia/default/1000@softswitch 1234567890 FreeSWITCH_Conference
The above API call will dial out of a conference named "testconf" to the user located at the specified endpoint with a 30 second timeout. The endpoint will see the call as coming from "FreeSWITCH_Conference" with a caller id of 1234567890.
Note: The values provided in the dial string overwrite the caller-id-number and caller-id-name variables provided at the end of the API call.
Click here for the list of dial string options available.
List Additional Information
The output generated by the system is named by default with the following format:
<conference name> (<member_count> member[s][locked]),
where locked can represent either the locked or unlockes status of the conference.
The following items are a separated list in CSV format for each conference leg:
Item | Description |
ID of participant | |
Register string of participants | |
UUID of participants call leg | |
Caller ID number | |
Caller ID name | |
Status | Options are:
|
Volume In | |
Volume Out | |
Energy Level |
Relate Additional Information
Examples:
- conference my_conf relate 1 2 nospeak: Member 1 may now no longer speak to member 2, i.e. member 2 now cannot hear member 1.
- conference my_conf relate 1 2 clear: Member 1 may now speak to member 2 again
- conference my_conf relate 1 2 nohear: Member 1 now cannot hear member 2
- confernce my_conf relate 1 2 clear: Member 1 can now hear member 2 again
Examples
Lock a conference with name "WeeklyTeamConf":
curl --digest -k -X PUT https://200:123@localhost/sipxconfig/rest/my/conference/WeeklyTeamConf/lock
Invite user in conference given username:
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/invite\&401
Invite user in conference given instant message ID:
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/inviteim\&401im
Other examples:
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/xml_list
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/kick\&all
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/record
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/record\&stop
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/record\&status
curl --digest -k https://400:123@gerula-dev.buc.ro/sipxconfig/rest/my/conference/Conf400/record\&duration
Sample PHP click to call code:
<?php
$to="101";//Number to dial
$from="5001";//userid in sipx
$pass="1234";//sipx pin (NOT SIP password)
//replace sipx.gcgov.local with your sipx server
$url = "http://sipx.gcgov.local:6667/callcontroller/".$from."/".$to."?isForwardingAllowed=true";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, $from.":".$pass);
$result = curl_exec($ch);
curl_close($ch);
?>
Sample contact information:
<contact-information>
<jobTitle>Data Entry Assistant</jobTitle>
<jobDept>Data Management Services</jobDept>
<companyName>Museum of Science</companyName>
<homeAddress>
<city>NY</city>
</homeAddress>
<officeAddress>
<street>1 Science Park</street>
<city>Boston</city>
<country>US</country>
<state>MA</state>
<zip>02114</zip>
</officeAddress>
<imId>myId</imId>
<emailAddress>john.doe@example.com</emailAddress>
<useBranchAddress>false</useBranchAddress>
<avatar>https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=80&d=G</avatar>
<firstName>John</firstName>
<lastName>Doe</lastName>
</contact-information>