The following document describes the Call Control- and Notify-API by Placetel.

⚠️ This is still in beta and might change in the near future.

1. Setup
2. Our POST request
   1. Incoming call
   2. Call accepted
   3. Call hangup
3. Your XML response
   1. Forward
   2. Reject
   3. Hangup
   4. Queue
4. Code examples
5. Security
6. FAQ
7. Contributing

This API is part of our PROFI product line and comes in two operating modes:

1. a simple notification API, which is enabled per number and notifies your API endpoint about an incoming call, when the call is accepted and when the call ended
2. an advanced call control mechanism, set up in the routing of each number, which asks your API endpoint how to handle an incoming call

To enable both APIs, go to Settings → External APIs in your PBX and provide the URL of your API endpoint.

To enable call notification for a number use the checkboxes at Settings → Exsternal APIs or the the Checkbox in the Miscellaneous-tab in the routing settings of each number.

Change the routing of your number to External API. The amount of retries to contact your API can be raised up to 10, we wait for 100ms after each retry.

Select a backup routing plan, which will be used in case of an error and an announcement, which will be played before processing your response.

We will send a POST request with an application/x-www-form-urlencoded payload to your API endpoint for every event. Each event will have an call id to identify the call it belongs to. This call id will be a hex presentation of a SHA256 hash

Depending on the type of request it contains the following parameters:

Your XML response is used to determine what to do with the incoming call. We only process your response when the routing for your number is set to External API. Make sure your response's Content-Type header is set to application/xml.

Currently, we support the following responses for incoming calls:

^* Only available with Contact Center option booked.

Forward to one or multiple targets. Attributes for Forward are

Attributes for each Target.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>022129191999</Number>
        </Target>
    </Forward>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>[email protected]</Number>
        </Target>
    </Forward>
</Response>

Find the SIP username and server on the settings page of your SIP destination.

Ringing the same time.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>[email protected]</Number>
            <Number>022129191999</Number>
        </Target>
    </Forward>
</Response>

Ringing 30 sec on the first two destinations and 45 sec on the second three destinations.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target ringtime="30">
            <Number>[email protected]</Number>
            <Number>022129191999</Number>
        </Target>
        <Target ringtime="45">
            <Number>[email protected]</Number>
            <Number>[email protected]</Number>
            <Number>022199998560</Number>
        </Target>
    </Forward>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward music_on_hold="true" forward_announcement="7684">
        <Target>
            <Number>[email protected]</Number>
        </Target>
    </Forward>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward voicemail="true" voicemail_announcement="4"/>
</Response>

Reject an unwanted call or pretend to be busy.

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

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Reject reason="busy" />
</Response>

A simple hangup.

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

Send call to a Contact Center Queue.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Queue queue_id="123" />
</Response>

• Ruby
• Node.js
• PHP
• Python
• Java

Want to add your example? Open a pull request!

For HTTP Basic Authentication include your username and passwort within your API URL. For example: https://username:[email protected].

The API itself is provided free of charge; the usual connection charges may apply.

For improvements, feature requests or bug reports, please use GitHub Issues or send us a pull request.