Dialplan API¶

The dialplan handles the routing of incoming calls.

/api/dialplan/v2¶

The dialplan v2 is a replacement for the old dialplan routing implementation.

GET /api/dialplan/v2¶

Get list of dialplan objects

Response body example

{
    "dialplan" : [
        {
            "uuid": "a4a33462-c88a-42f7-be35-ae06775fde6e",
            "description": "A description text"
        },
        {
            "uuid": "b6774686-2bc5-4af0-9dbf-33f4427adbd9",
            "description": "Holidays"
        },
        {
            "uuid": "84126d2c-b2d7-4e39-8455-fc4788515928",
            "description": "Busy season"
        }
    ]
}

POST /api/dialplan/v2¶

Creates a new dialplan.

Request body example

{
    "dialplan" : {
        "description": "A description text",
        "ringtone": {
            "announcement": "91e85f5c-b9eb-11e1-8b7e-0024e8f90cc0",
            "mix": true
        },
        "profiles": [
            {
                "filter": {
                    "caller": "\+49221.*|\+4830123456|anonymous",
                    "time": {
                        "weekdays": ["MON","TUE","WED","THU","FRI","SAT","SUN"],
                        "time_start": "07:30",
                        "time_end": "13:00",
                        "time_zone": "Europe/Berlin"
                    }
                },
                "linear": {
                    "timeout" : 7,
                    "targets": [
                        {
                            "target": "joe_05",
                            "timeout": 5,
                            "clip_number": "+492216698980"
                        },
                        {
                            "target": "+491771234567",
                            "timeout": 4
                        }
                    ]
                }
            },
            {
                "filter": {
                    "time": {
                        "date": "11.06.2015",
                        "time_start": "07:30",
                        "time_end": "13:00",
                        "time_zone": "Europe/Berlin"
                    }
                },
                "parallel": {
                    "timeout" : 10,
                    "clip_number": "+492216698980",
                    "targets": [
                        "joe_04",
                        "+491771234567"
                    ]
                }
            },
            {
                "cyclic": {
                    "timeout": 7,
                    "targets": [
                        {
                            "target": "joe_08",
                            "timeout": 4
                        },
                        {
                            "target": "+491771234567",
                            "timeout": 5,
                            "clip_number": "+492216698980"
                        }
                    ]
                }
            },
            {
                "pin": {
                    "code" : 1337,
                    "timeout": 20,
                    "onStart": [
                        {
                            "play": {
                                "announcement": "b6774686-2bc5-4af0-9dbf-33f4427adbd9"
                            }
                        }
                    ],
                    "onSuccess": [
                        {
                            "record" : {
                                "announcement": "b6774686-2bc5-4af0-9dbf-33f4427adbd9"
                            }
                        }
                    ],
                    "onFail": [
                        {
                            "reject" : {}
                        }
                    ],
                    "onTimeout": [
                        {
                            "reject" : {}
                        }
                    ],
                }
            },
            {
                "play": {
                    "announcement": "b6774686-2bc5-4af0-9dbf-33f4427adbd9"
                }
            },
            {
                "record": {
                    "announcement": "b6774686-2bc5-4af0-9dbf-33f4427adbd9"
                }
            }
        ]
    }
}

JSON Parameters:

description –
^.{0,200}$

optional: a short description of this dialplan
ringtone – optional: The section to configure a “custom ringback tone”
ringtone.announcement –
UUID

optional: announcement to be played during the connection process
ringtone.mix –
true|false

optional: if true, a ringing tone is mixed with the ringtone.announcement
profiles –
optional: first to last element in this list will be evaluated. The elements of profiles contain a filter and an action object. The action object is mandatory it will be executed. Only one action object in a profile element is allowed.

Possible action’s:
- reject: will hang up the call.
- play: will play the given announcement.
- record: will start mailbox recording.
- parallel: will originate calls to all targets in parallel.
- linear: will originate calls to all targets in a sequential way. if a target is busy or timeouts the next will be connected. The starting point is the first list element.
- cyclic: originate calls to all targets in a sequential way. if a target is busy or timeouts the next will be connected. The starting point will be choosen by Round-robin scheduling.
- pin: will generate a pin code request.
  - code: the string of DTMF symbols to gain access. The pin code check will run when the recorded DTMF count matches the length of the given code.
  - timeout: optional field with the default value of 0(never). The timeout to enter all DTMF symbols.
  - onStart: optional field with an array of profile actions. The actions will be executed after DTMF recording has started. The given array must not contain any pin-profile.
  - onSuccess: an array of profile actions. The actions will be executed when the user input matches the code.
  - onFail: optional field with an array of profile actions. The actions will be executed when the input doesn’t match. If this field is missing or has an empty array, the next profile action starts.
  - onTimeout: optional field with an array of profile actions. The actions will be executed when the timeout is reached. The timeout stops when the recorded DTMF count matches the given code length. If this field is missing or has an empty array, the next profile action starts.
filter – optional: if the filter object isn’t present or is present and the all criteria matches the action object will be executed
caller –
regular expression (max. 500 characters)

optional: if the regex doesn’t match the next rule in the profiles will be evaluated. Examples: “anonymous” matches calls with clir enabled. “+49.*” matches calls for Germany. “+4922112345” exact match
time – optional: You can define a time range and/or a date and/or date range and/or weekdays. if the field date is present, the fields weekdays, date_start and date_end should not be used.
date –
dd.MM.yyyy

optional: if the current day doesn’t match the given date the next rule in the profiles will be evaluated.
date_start –
dd.MM.yyyy

optional: if the current day doesn’t follow the given date the next rule in the profiles will be evaluated.
date_end –
dd.MM.yyyy

optional: if the current day doesn’t precede the given date the next rule in the profiles will be evaluated. date_end should not precede date_start
weekdays – optional: if the current day doesn’t match the given list of weekdays the next rule in the profiles will be evaluated.
time_start –
hh:mm

optional: the start time of this time filter. The server timezone is UTC.
time_end –
hh:mm

optional: the end time of this time filter. If time_start is not earlier than the time_end, then the time_end refers to the following day.
time_zone –
^.{2,32}$

optional: the time zone of this time filter. If time_zone is not set it will default to UTC.
(parallel|linear|cyclic).clip_number –
^\+[0-9]{3,20}$

optional: custom CLIP number of this action.
(parallel|linear|cyclic).timeout – optional: the timeout in seconds of this action. The default value is 0. if set to lower than 1 this action won’t stop until network disconnect.
parallel.targets – mandatory: must be present with at least one target.
(linear|cyclic).targets – mandatory: must be present with at least one element. Elements are objects with a target and a timeout.
target –
^\+[0-9]{3,20}$|^[a-z0-9]{2,20}_[0-9]{2}$

optional: the phone number or the SIP account target. The solucon SIP accounts must be owned by this account.
(linear|cyclic).targets.timeout – optional: the timeout in seconds of the ringing action. The default value is 0. if set to lower than 1 the ringing won’t stop until network disconnect.

Response body example

{
    "uuid": "6e33d20f-2052-4e1e-9109-868c06bc5a17"
}

The UUID of the newly created dialplan is returned.

Status:	wrong-announcement: This announcement is not a valid announcement accessible from the user

GET /api/dialplan/v2/(uuid)¶

Get dialplan uuid

Response body example

{
    "dialplan" : {
        "description": "Busy season",
        "profiles": [
            {
                "reject": {}
            }
        ]
    }
}

For a description of the JSON fields see POST /api/dialplan/v2

Status:	wrong-dialplan: The given UUID does not match to a dialplan accessible by the current user

POST /api/dialplan/v2/(uuid)¶

Modifies dialplan uuid

Request body example

{
    "dialplan" : {
        "description": "Holidays",
        "profiles": [
            {
                "record": {
                    "announcement" : "b6774686-2bc5-4af0-9dbf-33f4427adbd9"
                }
            }
        ]
    }
}

Response body example

{}

For a description of the JSON fields see POST /api/dialplan/v2

Status:	wrong-dialplan: The given UUID does not match to a dialplan accessible by the current user wrong-announcement: This announcement is not a valid announcement accessible from the user

DELETE /api/dialplan/v2/(uuid)¶

Delete the dialplan uuid

Response body example

{}

Status:	wrong-dialplan: The given UUID does not match to a dialplan accessible by the current user

When the dialplan is active in :http:get:’/api/phone’ it will be removed there as well. This will end in a unintended number configuration.

/api/dialplan¶

GET /api/dialplan¶

Get the configuration of the user’s dialplan.

Response body example

{
    "announcement": "1de1227a-4f34-11e0-ab6e-0024e8f90cc1",
    "mix_ringtone": false,
    "clip_number": "+492216698980",
    "dial_prefix": "+492216698",
    "clir_enable": false,
    "cti_via": "+492216698777",
    "action": "none",
    "phone": "+492216698999",
    "sip": "joe_01",
    "phone_pool": {
        "+492216698991": true,
        "+492216698992": false
    },
    "sip_pool": [
        "joe_08",
        "joe_13"
    ],
    "callreverse_enable": false,
    "timeout": {
        "timeout": 20,
        "action": "record"
    },
    "unavailable": {
        "action": "redirect",
        "phone": "+492216698998",
        "sip": "joe_01"
    },
    "busy": {
        "action": "sip",
        "sip": "joe_07"
    }
}

The sip and phone fields can exist independently of the selection action. E.g. if the action is sip, a phone number can be configured for the respective session, however it will not be used. Each entry in the phone_pool section is either active (value true, the number will be dialled if the dialplan gets called) or inactive (value false).

POST /api/dialplan¶

Modify the user’s dialplan configuration

Request body example

{
    "announcement": "91e85f5c-b9eb-11e1-8b7e-0024e8f90cc0",
    "mix_ringtone": true,
    "clip_number": "+492216698888",
    "dial_prefix": "+492216698",
    "clir_enable": false,
    "cti_via": "+492216698777",
    "action": "none",
    "phone": "+492216698001",
    "sip": "joe_01",
    "phone_pool": {
        "add": {
            "+492216698990": false,
            "+492216698995": true
        },
        "delete": [
            "+492216698992"
        ]
    },
    "sip_pool": {
        "add": [
            "joe_01",
            "joe_03"
        ],
        "delete": [
            "joe_02"
        ]
    },
    "callreverse_enable": false,
    "timeout": {
        "timeout": 20,
        "action": "record"
    },
    "unavailable": {
        "action": "redirect",
        "phone": "+492216698993"
    },
    "busy": {
        "action": "sip",
        "sip": "joe_01"
    }
}

JSON Parameters:

announcement –
UUID

optional: announcement to be played during the connection process
mix_ringtone –
true|false

optional: if true, a ringing tone is mixed with the announcement (“custom ringback tone”)
action –
none|redirect|reject|sip|record

optional: the action to proceed with if the condition is reached
phone –
^\+[0-9]{3,20}$

optional: the phone number target for action redirect
sip –
^[a-z0-9]{2,20}_[0-9]{2}$

optional: the SIP account target for action sip
dial_prefix –
^\+[0-9]{3,20}$

optional: prefix for quick dialing
clip_number –
^\+[0-9]{3,20}$

optional: custom CLIP number
clir_enable –
true|false

optional: to enable / disable CLIR feature
cti_via –
^\+[0-9]{3,20}$

optional: the user’s phone number to receive callback calls on
callreverse_enable –
true|false

optional: if true, enables the call-reverse function

Response body example

{}

Status:	wrong-announcement: The given announcement does not match an announcement accessible by the current user wrong-sip: The given SIP account is not one of the current user’s SIP accounts

All fields and structures in this request are optional.

If entries listed in the add section of the phone_pool refer to existing phone numbers, they are overwritten.

To delete the announcement, phone, dial_prefix, clip_number, cti_via or sip fields, an empty string value can be given for these fields.

In the case of timeout or unavailable, the action none is not possible.

If present, the dial_prefix specifies a phone number that will be prepended to the original dialed number if the user (SIP account) dials a short number (quick dialing).

If present, the clip_number will specify the phone number that is transmitted as the calling line identification for outgoing calls made by a SIP account (PSTN CLIP feature).

If clir_enable is true, the transmission of the calling line identification is suppressed (PSTN CLIR feature).

If callreverse_enable is true, a call to the user’s dialplan will activate the call-reverse function as an additional target just like the targets in the phone_pool and sip_pool.

POST /api/dialplan/callthrough¶

Initiate a call-through function

Request body example

{
    "phone": "+492216698001",
    "filter": "+492118271982"
}

JSON Parameters:
	phone – `^([a-zA-Z0-9]{2,20})\|(\+[0-9]{3,20})$` optional: the target (e.g. a phone number) to call in the call-through function. filter – `^\+[0-9]{3,20}$` optional: a phone number that has to match to trigger the call-through function.

Response body example

{}

All fields and structures in this request are optional.

When this API method is called, a new call-through process is started. The system saves the given phone and optional filter numbers. When the user’s dialplan is called from an external number that matches the filter, or when the short-dialling code *98 is dialled from one of the user’s SIP accounts, the call will be connected to the destination phone.

There can only be one active call-through process per user. The process state is reset when the call-through is initiated or with any subsequent call to this API method. If this method is called without the phone field, an outstanding call-through request is cleared. Outstanding call-through requests will also time out after an appropriate time interval (typically 1-2 minutes).

POST /api/dialplan/callback¶

Initiate a callback call

Request body example

{
    "from": "+492118271982",
    "to": "+492216698711"
}

JSON Parameters:
	from – `^\+[0-9]{3,20}$` the originating phone number to – `^([a-zA-Z0-9]{2,20})\|(\+[0-9]{3,20})$` the destination target (e.g. a phone number)

Response body example

{}

Status:	wrong-phone: The given `from` number does not match any of the user’s phone numbers or the `dialplan_enable` flag is not set on the phone number no-via: No `cti_via` field is set in the user’s dial plan access-denied: The user has no permissions to use the callback feature

This API call initiates a call back procedure. First, a call is iniated towards the user’s cti_via phone number (see GET /api/dialplan and POST /api/dialplan). When the user answers the call, the given to number will be called and bridged to the first call. The from number will used as an originating caller number on both call legs.

The callback feature will utilize the clip_number, clir_number and cti_via values of the user’s dialplan.

POST /api/dialplan/callreverse¶

Set the filter for an ongoing call-reverse function

Request body example

{
    "filter": "+492118271982"
}

JSON Parameters:
	filter – `^\+[0-9]{3,20}$` a phone number that has to match to trigger the call-reverse function.

Response body example

{}

Status:	no-callreverse: There is no active call-reverse process

This API method should be called if an ongoing call-reverse process has previously been signalled to the user with a dialplan_callreverse event. A phone number can be set as a filter, and if this phone number calls the user’s dialplan number, the incoming call-reverse call will be connected to this call.

Dialplan API¶

/api/dialplan/v2¶

/api/dialplan¶

Table of Contents

Related Topics

API email update