### Forward call to multiple destinations

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Example of ringing multiple destinations simultaneously using the Forward action.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
            <Number>022129191999</Number>
        </Target>
    </Forward>
</Response>
```

--------------------------------

### Forward call to one VoIP destination

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Example of forwarding an incoming call to a specific SIP URI.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
        </Target>
    </Forward>
</Response>
```

--------------------------------

### Test HungUp Event with cURL

Source: https://github.com/placetel/call-control-notify-api/blob/main/examples/README.md

Use this cURL command to test the HungUp event endpoint. This example includes the 'type' parameter, which can be 'accepted' or other values.

```bash
curl -X POST --data "event=HungUp&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&type=accepted" http://localhost:3000
```

--------------------------------

### Forward call to one external number

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Example of forwarding an incoming call to a single external phone number.

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

--------------------------------

### Node.js/Express Webhook Handler

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Set up an Express.js server to receive Placetel call events. It logs event details and responds with XML for incoming calls, forwarding them to specified numbers with music on hold.

```javascript
var express = require('express');
var bodyParser = require('body-parser');
var xml = require('xml');

var app = express();
app.use(bodyParser.urlencoded({extended: false}));

app.post('/', function (request, response) {
  var event = request.body.event;
  var call_id = request.body.call_id;
  var from = request.body.from;
  var to = request.body.to;

  console.log('event: ' + event);
  console.log('call_id: ' + call_id);
  console.log('from: ' + from);
  console.log('to: ' + to);

  // Only handle incoming calls for call control
  if (event === 'IncomingCall') {
    response.set('Content-Type', 'application/xml');

    // Forward to multiple destinations with music on hold
    response.send(
      xml({
        Response: [
          {
            Forward: [{
              _attr: {
                music_on_hold: true
              }
            },
              {
                Target: [
                  {Number: "022129191999"},
                  {Number: "7777abcdefg@fpbx.de"}
                ]
              }]
          }
        ]
      })
    );
  } else {
    response.end();
  }
});

app.listen(3000, function() {
  console.log('Placetel webhook server listening on port 3000');
});
```

--------------------------------

### Play Prompt and Hangup

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Plays a pre-recorded audio prompt to the caller and then hangs up. The prompt must be uploaded to your Placetel account first.

```APIDOC
## Play Prompt and Hangup

### Description
Play a pre-recorded audio prompt to the caller and then hang up. The prompt must be uploaded to your Placetel account first.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Parameters
#### Request Body Attributes
- **id** (string) - Required - The ID of the audio prompt to play.

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Prompt id="123" />
</Response>
```

### Response Example
(The provided XML is the response itself)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Prompt id="123" />
</Response>
```
```

--------------------------------

### Simulate Call Accepted Event with cURL

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

This cURL command simulates a call accepted event, providing details about which SIP peer answered the call.

```bash
# Simulate a call accepted event
curl -X POST \
  --data "event=CallAccepted&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&peer=7777abcdefg@fpbx.de&direction=in" \
  http://localhost:3000

# POST parameters received:
# event=CallAccepted
# from=017312345678 (caller's number)
# to=022129191999 (called number)
# peer=7777abcdefg@fpbx.de (SIP peer that answered)
# call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447
# direction=in
```

--------------------------------

### Simulate Incoming Call Event with cURL

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Use this cURL command to simulate an incoming call event. It sends POST data including caller number, destination, call ID, and direction.

```bash
# Simulate an incoming call event
curl -X POST \
  --data "event=IncomingCall&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&direction=in" \
  http://localhost:3000

# POST parameters received:
# event=IncomingCall
# from=017312345678 (caller's number, or "anonymous")
# to=022129191999 (your Placetel number)
# call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447
# direction=in
```

--------------------------------

### Implement WebSocket Call Log Listener

Source: https://github.com/placetel/call-control-notify-api/blob/main/examples/node/websockets/index.html

Connects to a WebSocket server on the current host with an incremented port to receive and log call events. Requires an HTML element with the ID 'calls' to display the log entries.

```javascript
window.onload = function () { (function () { var log = function (el) { return function (message) { var listItem = document.createElement('li'); var text = document.createTextNode( new Date() + ' - ' + message.event + ': ' + message.from + ' → ' + message.to); listItem.appendChild(text); el.appendChild(listItem) } }(document.getElementById('calls')); var port = parseInt(location.port) + 1; var ws = new WebSocket('ws://' + location.hostname + ':' + port); ws.onopen = function () { document.title = 'online' }; ws.onclose = function () { document.title = 'offline' }; ws.onmessage = function (message) { log(JSON.parse(message.data)) } })() }
```

--------------------------------

### Call Control API - Handling Incoming Calls

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

This API endpoint is queried by Placetel to determine how to handle an incoming call. Your XML response dictates the call's next action.

```APIDOC
## POST /api/callback

### Description
Placetel sends a POST request to this endpoint to ask how to handle an incoming call. Your XML response determines the call's routing.

### Method
POST

### Endpoint
/api/callback

### Parameters
#### Request Body
- **event** (string) - Required - The event type, should be "IncomingCall".
- **from** (string) - Required - The calling number.
- **to** (string) - Required - The called number.
- **call_id** (string) - Required - The unique ID of the call.
- **direction** (string) - Required - The direction of the call, should be "in".

### Request Example
```json
{
  "event": "IncomingCall",
  "from": "0123456789",
  "to": "0987654321",
  "call_id": "f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447",
  "direction": "in"
}
```

### Response
#### Success Response (200)
- **XML Response** (XML) - Required - Your response in XML format dictates the call handling. See 'Your XML response' section for available options (Forward, Reject, Hangup, Prompt, Group, RoutingPlan, Queue).

#### Response Example (Forward)
```xml
<Response>
  <Forward>
    <Number>0987654321</Number>
  </Forward>
</Response>
```

#### Response Example (Reject)
```xml
<Response>
  <Reject/>
</Response>
```

#### Response Example (Hangup)
```xml
<Response>
  <Hangup/>
</Response>
```

#### Response Example (Prompt)
```xml
<Response>
  <Prompt>
    <Say>Please wait while we connect you.</Say>
    <Number>0987654321</Number>
  </Prompt>
</Response>
```

#### Response Example (Group)
```xml
<Response>
  <Group>
    <Name>Sales</Name>
  </Group>
</Response>
```

#### Response Example (RoutingPlan)
```xml
<Response>
  <RoutingPlan>
    <Name>MyCustomPlan</Name>
  </RoutingPlan>
</Response>
```

#### Response Example (Queue)
```xml
<Response>
  <Queue>
    <Name>SupportQueue</Name>
  </Queue>
</Response>
```
```

--------------------------------

### POST /incoming-call-routing

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Endpoint to handle incoming call routing instructions via XML.

```APIDOC
## POST /incoming-call-routing

### Description
Processes XML instructions to determine how to handle an incoming call when routing is set to 'External API'.

### Method
POST

### Request Body
- **Response** (XML) - Required - Root element containing actions like Forward, Reject, Hangup, Prompt, Group, RoutingPlan, or Queue.

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

--------------------------------

### PHP/Slim Framework Webhook Handler

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

PHP endpoint using the Slim Framework to process Placetel webhooks. It logs event data and returns an XML response for incoming calls, including forwarding and voicemail options.

```php
<?php
use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;

require __DIR__ . '/../vendor/autoload.php';

$app = new \Slim\App;

$app->post('/incoming_event', function (Request $request, Response $response) {
    $data = $request->getParsedBody();

    // Log event details
    error_log("Event: " . $data['event']);
    error_log("Call ID: " . $data['call_id']);
    error_log("From: " . $data['from']);
    error_log("To: " . $data['to']);

    // Handle incoming calls with XML response
    if ($data['event'] === 'IncomingCall') {
        $xml = '<?xml version="1.0" encoding="UTF-8"?>
        <Response>
            <Forward music_on_hold="true" voicemail="true" voicemail_announcement="4711" voicemail_as_attachment="true" forward_announcement="7684">
                <Target ringtime="60">
                    <Number>7777acbdef@fbpx.de</Number>
                </Target>
            </Forward>
        </Response>';

        $response = $response->withHeader('Content-Type', 'application/xml');
        $response->getBody()->write($xml);
    }

    return $response;
});

$app->run();

// Run with: php -S 0.0.0.0:8080 -t public public/index.php

```

--------------------------------

### Ruby/Sinatra Webhook Handler

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

A Sinatra application to handle Placetel webhooks. It logs incoming call details and generates an XML response for 'IncomingCall' events, forwarding calls with music on hold.

```ruby
require 'sinatra'
require 'builder'

set :bind, '0.0.0.0'
set :port, 3000

post '/' do
  logger.info "event: #{params[:event]}"
  logger.info "call_id: #{params[:call_id]}"
  logger.info "from: #{params[:from]}"
  logger.info "to: #{params[:to]}"

  # Only respond with XML for incoming calls
  if params[:event] == 'IncomingCall'
    headers 'Content-Type' => 'application/xml'
    xml = Builder::XmlMarkup.new(indent: 4)
    xml.instruct!

    # Forward to multiple destinations with music on hold
    xml.Response {
      xml.Forward(music_on_hold: true) {
        xml.Target {
          xml.Number('022129191999')
          xml.Number('7777abcdefg@fpbx.de')
        }
      }
    }
  end
end
```

--------------------------------

### Test CallAccepted Event with cURL

Source: https://github.com/placetel/call-control-notify-api/blob/main/examples/README.md

Use this cURL command to test the CallAccepted event endpoint. This includes the 'peer' parameter specific to this event.

```bash
curl -X POST --data "event=CallAccepted&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&peer=7777abcdefg@fpbx.de" http://localhost:3000
```

--------------------------------

### Forward with Music on Hold and Announcement

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Plays music on hold instead of the standard ringtone and plays an announcement before connecting the call. The `forward_announcement` attribute specifies the prompt ID.

```APIDOC
## Forward with Music on Hold and Announcement

### Description
Play music on hold instead of the standard ringtone and play an announcement before connecting the call. The `forward_announcement` attribute specifies the prompt ID from your Placetel account.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Parameters
#### Request Body Attributes
- **music_on_hold** (boolean) - Optional - Set to `true` to play music on hold.
- **forward_announcement** (string) - Optional - The ID of the announcement prompt to play before connecting.

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward music_on_hold="true" forward_announcement="7684">
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
        </Target>
    </Forward>
</Response>
```

### Response Example
(The provided XML is the response itself)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward music_on_hold="true" forward_announcement="7684">
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
        </Target>
    </Forward>
</Response>
```
```

--------------------------------

### Play prompt by ID and hang up

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Plays a pre-defined prompt identified by its ID and then hangs up the call. The `id` attribute is required.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Prompt id="123" />
</Response>
```

--------------------------------

### Route to Routing Plan

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Delegates call handling to an existing routing plan configured in Placetel. Optionally provides a Forward fallback if no routing object is active.

```APIDOC
## Route to Routing Plan

### Description
Delegate call handling to an existing routing plan configured in Placetel. If no routing object is active, optionally provide a Forward fallback.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Parameters
#### Request Body Attributes
- **id** (string) - Required - The ID of the routing plan.

### Request Body Examples

#### Simple routing plan
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <RoutingPlan id="123" />
</Response>
```

#### Routing plan with fallback
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <RoutingPlan id="123">
        <Forward>
            <Target>
                <Number>7777abcdefg@fpbx.de</Number>
                <Number>022129191999</Number>
            </Target>
        </Forward>
    </RoutingPlan>
</Response>
```

### Response Example
(The provided XML is the response itself)
```

--------------------------------

### Test IncomingCall Event with cURL

Source: https://github.com/placetel/call-control-notify-api/blob/main/examples/README.md

Use this cURL command to test the IncomingCall event endpoint. Ensure your local server is running on port 3000.

```bash
curl -X POST --data "event=IncomingCall&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447" http://localhost:3000
```

--------------------------------

### Send call to a routing plan with fallback

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Routes a call to a specified routing plan and includes a fallback mechanism using the `<Forward>` element if the plan does not resolve.

```xml
<Response>
  <RoutingPlan id="123">
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
            <Number>022129191999</Number>
        </Target>
    </Forward>
  </RoutingPlan>
</Response>
```

--------------------------------

### Reject call with busy reason

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Rejects an incoming call and sets the reason to 'busy'. This can be used to simulate a busy line.

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

--------------------------------

### Forward call with music on hold and announcement

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Forwards a call to a VoIP destination while playing music on hold and a pre-recorded announcement. Ensure the announcement ID is valid.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward music_on_hold="true" forward_announcement="7684">
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
        </Target>
    </Forward>
</Response>
```

--------------------------------

### Python Webhook Handler for Placetel Events

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

A Python HTTP server that processes Placetel call events. It returns routing instructions in XML format for incoming calls. Ensure the server is accessible over the network.

```python
"""
Placetel webhook handler - Run with: python events.py
"""

from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs

ROUTING_XML = """<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward music_on_hold="true" voicemail="true" voicemail_announcement="4711" forward_announcement="7684">
        <Target ringtime="60">
            <Number>7777acbdef@fbpx.de</Number>
        </Target>
    </Forward>
</Response>"""

class PlacetelHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        post_data = self.rfile.read(content_length).decode('utf-8')
        params = parse_qs(post_data)

        event = params.get('event', [''])[0]
        call_id = params.get('call_id', [''])[0]
        from_number = params.get('from', [''])[0]
        to_number = params.get('to', [''])[0]

        print(f"Event: {event}")
        print(f"Call ID: {call_id}")
        print(f"From: {from_number}")
        print(f"To: {to_number}")

        self.send_response(200)

        if event == 'IncomingCall':
            self.send_header('Content-Type', 'application/xml')
            self.end_headers()
            self.wfile.write(ROUTING_XML.encode('utf-8'))
        else:
            self.end_headers()

if __name__ == '__main__':
    server = HTTPServer(('0.0.0.0', 8080), PlacetelHandler)
    print('Placetel webhook server running on port 8080')
    server.serve_forever()

```

--------------------------------

### Route to Routing Plan

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Delegates call handling to a configured routing plan, with optional fallback forwarding.

```xml
<!-- Simple routing plan -->
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <RoutingPlan id="123" />
</Response>

<!-- Routing plan with fallback -->
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <RoutingPlan id="123">
        <Forward>
            <Target>
                <Number>7777abcdefg@fpbx.de</Number>
                <Number>022129191999</Number>
            </Target>
        </Forward>
    </RoutingPlan>
</Response>
```

--------------------------------

### Incoming Call Event

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

This webhook is triggered when a new inbound call arrives. It provides details about the caller, destination, and call ID.

```APIDOC
## POST /webhooks/incoming-call

### Description
Receives notifications for incoming calls.

### Method
POST

### Endpoint
`/webhooks/incoming-call`

### Parameters
#### Query Parameters
- **event** (string) - Required - The event type, should be 'IncomingCall'.
- **from** (string) - Required - The caller's number, or 'anonymous'.
- **to** (string) - Required - Your Placetel number.
- **call_id** (string) - Required - A unique identifier for the call.
- **direction** (string) - Required - Indicates the call direction, should be 'in'.

### Request Example
```bash
curl -X POST \
  --data "event=IncomingCall&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&direction=in" \
  http://your-webhook-url.com
```

### Response
#### Success Response (200)
An empty response or a simple acknowledgment is expected.

#### Response Example
(No specific response body is defined for this event notification.)
```

--------------------------------

### Prompt API

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

API to play a prompt by its ID and then hang up the call.

```APIDOC
## Prompt API

### Description
Play a prompt by its ID and hang up the call.

### Method
POST (Implied by XML structure, actual HTTP method not specified)

### Endpoint
/api/call-control/prompt (Hypothetical endpoint based on context)

### Parameters
#### Request Body
- **Prompt** (XML) - The element to play a prompt.
  - **id** (string) - Required. The ID of the prompt to play, e.g., `"123"`.

### Request Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Prompt id="123" />
</Response>
```

### Response
#### Success Response (200)
- **Status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Simulate Outgoing Call Event with cURL

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Simulate an outgoing call event using cURL. This command sends data about the call, including caller ID, destination, SIP peer, and call ID.

```bash
# Simulate an outgoing call event
curl -X POST \
  --data "event=OutgoingCall&from=022129191999&to=017312345678&peer=7777abcdefg@fpbx.de&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&direction=out" \
  http://localhost:3000

# POST parameters received:
# event=OutgoingCall
# from=022129191999 (caller ID)
# to=017312345678 (destination number)
# peer=7777abcdefg@fpbx.de (SIP user making the call)
# call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447
# direction=out
```

--------------------------------

### Java Spark Framework Webhook Handler for Placetel

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

A Java endpoint using the Spark Framework to handle Placetel webhooks. It processes incoming call events and returns XML for call forwarding. Ensure the Spark application is running and accessible.

```java
import spark.Request;
import spark.Response;
import javax.servlet.MultipartConfigElement;
import static spark.Spark.*;

public class PlacetelWebhook {
    public static void main(String[] args) {
        port(3000);

        post("/event", (Request request, Response response) -> {
            request.attribute("org.eclipse.jetty.multipartConfig", new MultipartConfigElement("/temp"));

            String event = request.queryParams("event");
            String callId = request.queryParams("call_id");
            String from = request.queryParams("from");
            String to = request.queryParams("to");

            System.out.println("Event: " + event);
            System.out.println("Call ID: " + callId);
            System.out.println("From: " + from);
            System.out.println("To: " + to);

            if ("IncomingCall".equals(event)) {
                response.type("application/xml");
                return "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
                       "<Response>" +
                       "  <Forward music_on_hold=\"true\">" +
                       "    <Target ringtime=\"60\">" +
                       "      <Number>7777abcdefg@fpbx.de</Number>" +
                       "    </Target>" +
                       "  </Forward>" +
                       "</Response>";
            }

            return "ok";
        });
    }
}

```

--------------------------------

### Security - Basic Authentication

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Secure your API endpoint using Basic Authentication.

```APIDOC
## Security - Basic Authentication

### Description
You can protect your API endpoint by configuring Basic Authentication credentials in the Placetel Webportal.

### Configuration
In your Placetel external API settings, provide the URL in the format: `https://admin:password@your.end.point/callback`

Replace `admin` with your username and `password` with your password.
```

--------------------------------

### Queue API

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

API to send a call to a Contact Center Queue.

```APIDOC
## Queue API

### Description
Send a call to a Contact Center Queue.

### Method
POST (Implied by XML structure, actual HTTP method not specified)

### Endpoint
/api/call-control/queue (Hypothetical endpoint based on context)

### Parameters
#### Request Body
- **Queue** (XML) - The element to send a call to a queue.
  - **id** (string) - Required. The ID of the queue, e.g., `"123"`.

### Request Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Queue id="123" />
</Response>
```

### Response
#### Success Response (200)
- **Status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Verify Request Signature in Ruby

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Use HMAC-SHA256 to verify the authenticity of incoming POST requests by comparing the calculated signature with the X-PLACETEL-SIGNATURE header.

```ruby
require 'openssl'
secret = 'THE_SECRET'
payload = 'POSTED_PAYLOAD'

digest = OpenSSL::Digest.new('sha256')
signature = OpenSSL::HMAC.hexdigest(digest, secret, payload)
```

```ruby
2.5.1 :005 > digest = OpenSSL::Digest.new('sha256')
 => #<OpenSSL::Digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855>
2.5.1 :006 > signature = OpenSSL::HMAC.hexdigest(digest, secret, payload)
 => "a16d490518344c33afa96158d115b48a26a250da6b8c6bc1d6dedb0a47d13eaa"
```

--------------------------------

### Route to Group

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Sends the call to a predefined group of users with customizable ring behavior, backup handling, and voicemail options.

```APIDOC
## Route to Group

### Description
Send the call to a predefined group of users with customizable ring behavior, backup handling, and voicemail options.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Parameters
#### Request Body Attributes
- **id** (string) - Required - The ID of the group.
- **ringtime** (integer) - Optional - The duration in seconds to ring the group.
- **backup_behaviour** (string) - Optional - Defines behavior when no user answers (e.g., `mailbox`).
- **voicemail_announcement** (string) - Optional - The ID of the announcement prompt for voicemail.
- **voicemail_as_attachment** (boolean) - Optional - Set to `true` to send voicemail as an email attachment.
- **forward_announcement** (string) - Optional - The ID of the announcement prompt to play before forwarding.
- **music_on_hold** (boolean) - Optional - Set to `true` to play music on hold.

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Group
        id="123"
        ringtime="40"
        backup_behaviour="mailbox"
        voicemail_announcement="456"
        voicemail_as_attachment="true"
        forward_announcement="789"
        music_on_hold="true"
    />
</Response>
```

### Response Example
(The provided XML is the response itself)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Group
        id="123"
        ringtime="40"
        backup_behaviour="mailbox"
        voicemail_announcement="456"
        voicemail_as_attachment="true"
        forward_announcement="789"
        music_on_hold="true"
    />
</Response>
```
```

--------------------------------

### Call Accepted Event

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Sent when an incoming call is answered. Provides information about the SIP peer that accepted the call.

```APIDOC
## POST /webhooks/call-accepted

### Description
Receives notifications when an incoming call is answered.

### Method
POST

### Endpoint
`/webhooks/call-accepted`

### Parameters
#### Query Parameters
- **event** (string) - Required - The event type, should be 'CallAccepted'.
- **from** (string) - Required - The caller's number.
- **to** (string) - Required - The called number.
- **call_id** (string) - Required - A unique identifier for the call.
- **peer** (string) - Required - The SIP peer that answered the call.
- **direction** (string) - Required - Indicates the call direction, should be 'in'.

### Request Example
```bash
curl -X POST \
  --data "event=CallAccepted&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&peer=7777abcdefg@fpbx.de&direction=in" \
  http://your-webhook-url.com
```

### Response
#### Success Response (200)
An empty response or a simple acknowledgment is expected.
```

--------------------------------

### Forward Call to VoIP/SIP Destination

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Forwards calls to a SIP destination using the username@server format. Requires SIP username and server details from Placetel portal.

```APIDOC
## Forward Call to VoIP/SIP Destination

### Description
Forward calls to a SIP destination using the username@server format. Find the SIP username and server on your destination's settings page in the Placetel portal.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
        </Target>
    </Forward>
</Response>
```

### Response Example
(The provided XML is the response itself)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
        </Target>
    </Forward>
</Response>
```
```

--------------------------------

### Send call to a routing plan

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Directs a call to a routing plan for evaluation. If no routing object is active, the call will end. A fallback can be specified.

```xml
<Response>
  <RoutingPlan id="123" />
</Response>
```

--------------------------------

### Route to Group

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Routes calls to a predefined user group with custom ring, backup, and voicemail settings.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Group
        id="123"
        ringtime="40"
        backup_behaviour="mailbox"
        voicemail_announcement="456"
        voicemail_as_attachment="true"
        forward_announcement="789"
        music_on_hold="true"
    />
</Response>
```

--------------------------------

### HMAC Signature Verification

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Details on how to verify the authenticity of incoming webhooks using HMAC-SHA256 signature.

```APIDOC
## HMAC Signature Verification

### Description
Verify the authenticity of incoming webhooks by comparing the `X-PLACETEL-SIGNATURE` header with a locally computed HMAC-SHA256 signature.

### Method
Server-side verification process.

### Parameters
#### Request Headers
- **X-PLACETEL-SIGNATURE** (string) - Required - The signature provided by Placetel.

#### Shared Secret
- **secret** (string) - Required - Your shared secret obtained from Placetel settings.

### Process
1. Obtain the raw payload of the incoming POST request.
2. Obtain your shared secret.
3. Compute the HMAC-SHA256 hash of the payload using your shared secret.
4. Compare the computed hash with the value in the `X-PLACETEL-SIGNATURE` header.

### Request Example (Ruby)
```ruby
require 'openssl'

# Your shared secret from Placetel settings
secret = 'your_shared_secret_here'

# The raw POST payload received
payload = 'call_id=4a4cbb39578170aed9a2761a7bec8c7e704a541f52291ef603d6f5f152980c3c&direction=in&event=CallAccepted&from=0123456789&to=0987654321'

# Calculate HMAC-SHA256 signature
digest = OpenSSL::Digest.new('sha256')
calculated_signature = OpenSSL::HMAC.hexdigest(digest, secret, payload)

# Compare with the signature from X-PLACETEL-SIGNATURE header
# Assuming 'request' is your web framework's request object
received_signature = request.env['HTTP_X_PLACETEL_SIGNATURE']

if calculated_signature == received_signature
  puts "Signature valid - request is authentic"
else
  puts "Signature mismatch - reject request"
end
```

### Example Calculation
- **Secret**: `12345`
- **Payload**: `call_id=4a4cbb39578170aed9a2761a7bec8c7e704a541f52291ef603d6f5f152980c3c&direction=in&event=CallAccepted&from=0123456789&to=0987654321`
- **Computed Signature**: `a16d490518344c33afa96158d115b48a26a250da6b8c6bc1d6dedb0a47d13eaa`
```

--------------------------------

### Simulate Call Hangup Event with cURL

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Simulate a call hangup event using cURL. This includes the hangup cause, call duration, and direction of the call.

```bash
# Simulate a hangup event
curl -X POST \
  --data "event=HungUp&from=017312345678&to=022129191999&call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447&type=accepted&duration=125&direction=in" \
  http://localhost:3000

# POST parameters received:
# event=HungUp
# from=017312345678
# to=022129191999
# call_id=f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447
# type=accepted (voicemail|missed|blocked|accepted|busy|canceled|unavailable|congestion)
# duration=125 (seconds, 0 for unanswered calls)
# direction=in
```

--------------------------------

### Send call to a queue

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Routes an incoming call to a Contact Center Queue identified by its ID. This is used for managing call distribution in a contact center environment.

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

--------------------------------

### Route to Contact Center Queue

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Sends calls to a Contact Center queue for professional call distribution. Requires the Contact Center option to be booked in your Placetel account.

```APIDOC
## Route to Contact Center Queue

### Description
Send calls to a Contact Center queue for professional call distribution. This feature requires the Contact Center option to be booked in your Placetel account.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Parameters
#### Request Body Attributes
- **id** (string) - Required - The ID of the Contact Center queue.

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Queue id="123" />
</Response>
```

### Response Example
(The provided XML is the response itself)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Queue id="123" />
</Response>
```
```

--------------------------------

### Routing Plan API

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

API to send a call to a routing plan, with an optional fallback.

```APIDOC
## Routing Plan API

### Description
Send a call to a routing plan, which will be evaluated as usual. If no routing object is active, the call will be ended. A fallback can be provided.

### Method
POST (Implied by XML structure, actual HTTP method not specified)

### Endpoint
/api/call-control/routing-plan (Hypothetical endpoint based on context)

### Parameters
#### Request Body
- **RoutingPlan** (XML) - The element to send a call to a routing plan.
  - **id** (string) - Required. ID of the routing plan, e.g., `"123"`.
  - **Forward** (XML) - Optional. Fallback configuration if no routing object is active.
    - **Target** (XML) - Represents a destination for the fallback.
      - **Number** (string) - The phone number or SIP address for the fallback destination.

### Request Example
```xml
<Response>
  <RoutingPlan id="123">
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
            <Number>022129191999</Number>
        </Target>
    </Forward>
  </RoutingPlan>
</Response>
```

### Response
#### Success Response (200)
- **Status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Reject Call API

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

API to reject an incoming call or simulate a busy signal.

```APIDOC
## Reject Call

### Description
Reject an unwanted call or pretend to be busy.

### Method
POST (Implied by XML structure, actual HTTP method not specified)

### Endpoint
/api/call-control/reject (Hypothetical endpoint based on context)

### Parameters
#### Request Body
- **Reject** (XML) - The element to reject a call.
  - **reason** (string) - Optional. The reject reason for the call, e.g., `"busy"`.

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

### Response
#### Success Response (200)
- **Status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Incoming Call Notification

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

This endpoint receives POST requests with details about incoming calls.

```APIDOC
## POST /api/callback

### Description
Receives notifications for incoming calls from the Placetel system.

### Method
POST

### Endpoint
/api/callback

### Parameters
#### Request Body
- **event** (string) - Required - The event type, should be "IncomingCall".
- **from** (string) - Required - The calling number (e.g., "022129191999" or "anonymous").
- **to** (string) - Required - The called number (e.g., "022129191999").
- **call_id** (string) - Required - The unique ID of the call, a hex presentation of a SHA256 hash.
- **direction** (string) - Required - The direction of the call, should be "in".

### Request Example
```json
{
  "event": "IncomingCall",
  "from": "0123456789",
  "to": "0987654321",
  "call_id": "f4591ba315d81671d7a06c2a3b4f963dafd119de39cb26edd8a6476676b2f447",
  "direction": "in"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Reject call

Source: https://github.com/placetel/call-control-notify-api/blob/main/README.md

Rejects an incoming call. This is a basic rejection without any specific reason.

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

--------------------------------

### Forward Call to Multiple Destinations Simultaneously

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Rings multiple destinations at the same time. The first destination to answer receives the call.

```APIDOC
## Forward Call to Multiple Destinations Simultaneously

### Description
Ring multiple destinations at the same time. The first destination to answer receives the call.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
            <Number>022129191999</Number>
        </Target>
    </Forward>
</Response>
```

### Response Example
(The provided XML is the response itself)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target>
            <Number>7777abcdefg@fpbx.de</Number>
            <Number>022129191999</Number>
        </Target>
    </Forward>
</Response>
```
```

--------------------------------

### Forward Call with Sequential Ring Groups

Source: https://context7.com/placetel/call-control-notify-api/llms.txt

Configures cascading ring groups with different timeouts. After the first group's ringtime expires, the call moves to the next target group.

```APIDOC
## Forward Call with Sequential Ring Groups

### Description
Configure cascading ring groups with different timeouts. After the first group's ringtime expires, the call moves to the next target group.

### Method
POST (Implicit)

### Endpoint
Not specified.

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target ringtime="30">
            <Number>7777abcdefg@fpbx.de</Number>
            <Number>022129191999</Number>
        </Target>
        <Target ringtime="45">
            <Number>7777xyzabcd@fpbx.de</Number>
            <Number>7777aabbccd@fpbx.de</Number>
            <Number>022199998560</Number>
        </Target>
    </Forward>
</Response>
```

### Response Example
(The provided XML is the response itself)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Forward>
        <Target ringtime="30">
            <Number>7777abcdefg@fpbx.de</Number>
            <Number>022129191999</Number>
        </Target>
        <Target ringtime="45">
            <Number>7777xyzabcd@fpbx.de</Number>
            <Number>7777aabbccd@fpbx.de</Number>
            <Number>022199998560</Number>
        </Target>
    </Forward>
</Response>
```
```