Table of Contents

API : PBX : Trunk Create

Introduction

A trunk is an entrypoint into the PBX from the outside world. A trunk holds one or more public numbers that leads into the PBX.

The trunks task is to receive the calls and send them into the next dialplan item that shall handle the call.

A trunk may also be in FAX mode, where it instead acts as a fax receiver, sender or both.

Request

This request will create a trunk. All properties are optional except for customer and name.

URL https://api.telecomx.dk/pbx/trunk
Method POST
Access level MANAGER or OWNER if user belongs to the customer.
RESELLER if customer belongs to the reseller.
ADMIN.
Body customer Id Id of the customer the trunk belongs to.
name String Name/description of the trunk.
number String [optional] The phone number to dial to reach this trunk locally. Null if not used.
startAudio Id [optional] A sound item to playback when the trunk is entered.
redirect String [optional] Number to redirect to when execution starts. Used to quickly circumvent the trunk. Null if not used.
notes String Notes about the trunk.
numbers Array Array of phone numbers (E.164 format) that are handled by the trunk, Fixed line and mobile phones marked for PBX usage can be used.
selectable Boolean True if the numbers on this trunk may be used by employees for outbound number presentation.
language String Language to use for voice prompts against the caller: da or en.
ringtone Number If an alternative ringtone should be used on supported SIP phones, this is the index of it (1-19). 0 for silent ringtone, -1 to not override it.
musicOnHold Id Id of music on hold class to set, null if not used.
goto Id Id of dialplan item to send inbound calls to.
numberBlacklist Id [optional] Id of the number blacklist to check the callers number against, null if not used. See Number blacklists.
foreignNumbers Array [optional] Foreign phone numbers - numbers the customer does NOT own on the platform but has the right to present - that users may select as caller ID on outgoing calls. Array of { number, description }: number in strict E.164 (+ and 8-15 digits, not starting with 0; danish numbers +45 and 8 digits starting 2-9), description optional, max 64 characters. Duplicates are removed, max 100 numbers. A number the customer owns on the platform (on any SIP or mobile account) is refused when it is added. The array replaces the whole list, null clears it. Only RESELLER and up may set it - for lower users the values are ignored, and the hovednummer gets an empty list and no group. A presented foreign number is shown to the called party (From), but the call is still identified to the network (P-Asserted-Identity) by a number the customer owns - typically the extension's direct number, else the PBX default number.
foreignNumbersGroup Id [optional] Id of the PBX group whose member extensions may present the foreign numbers (controllers do not count). Null = every extension of the customer. If the group is later deleted nobody may present the numbers until another group (or null) is chosen. Only RESELLER and up may set it.
Fax
fax.mode String Fax mode:
OFF - used as normal trunk.
RECEIVE - receive fax only.
SEND - Send fax only.
BOTH - send and receive fax.
fax.retension Number Number of days to keep received faxes, 1-90 days, 0 to not store faxes and only e-mail them. Only used when fax.mode is not off.
fax.email String E-mail address to send received faxes to. Only used when fax.mode is not OFF.

Request body example

{
  customer: '12345678901234567890DDDD',
  name: 'Primary fax trunk CPH',
  number: '800',
  startAudio: null,
  redirect: null,
  notes: 'Faxing only',
  numbers: [
    '+4570305051',
    '+4570305052'
  ],
  selectable: false,
  language: 'da',
  ringtone: -1,
  musicOnHold: null,
  goto: null,
  pbx: {
    mode: 'BOTH',
    retension: 7,
    email: 'info@telecomx.dk'
  }
}

Response

JSON object
_id Id Unique id of the extension.
type String Always 'TRUNK'.
name String Name of the trunk.
number String The phone number to dial to reach this trunk, null if it is not dial-able.
startAudio Id A sound item to playback when the trunk is entered, null if not used.
redirect String Number to redirect to when execution starts. Used to quickly circumvent the trunk.
notes String Notes about the trunk.
numbers Array Array of phone numbers (E.164 format) that are handled by the trunk, Fixed line and mobile phones marked for PBX usage can be used.
selectable Boolean True if the numbers on this trunk may be used by employees for outbound number presentation.
language String Language to use for voice prompts against the caller: da or en.
ringtone Number If an alternative ringtone should be used on supported SIP phones, this is the index of it (1-19). 0 for silent ringtone, -1 to not override it.
musicOnHold Id Id of music on hold class to set, null if not used.
numberBlacklist Id Id of the number blacklist to check the callers number against, null if calls are not blacklist filtered. A caller whose number is on the list is rejected with busy. See Number blacklists.
goto Id Id of dialplan item to send inbound calls to.
foreignNumbers Array Foreign phone numbers (not owned by the customer) that users may present as caller ID on outgoing calls: { number, description }, description null if none. Maintained by RESELLER and up. Presented in From only - P-Asserted-Identity stays a number the customer owns.
foreignNumbersGroup Id Id of the PBX group whose member extensions may present the foreign numbers, null = every extension of the customer. A group that has been deleted lets nobody present them.
Fax
fax.mode String Fax mode:
OFF - used as normal trunk.
RECEIVE - receive fax only.
SEND - Send fax only.
BOTH - send and receive fax.
fax.retension Number Number of days to keep received faxes, 1-90 days, 0 to not store faxes and only e-mail them. Only used when fax.mode is not off.
fax.email String E-mail address to send received faxes to. Only used when fax.mode is not OFF.

Example

{
  _id: '12345678901234567890ABCD',
  name: 'Primary fax trunk CPH',
  number: '800',
  startAudio: null,
  redirect: null,
  notes: 'Faxing only',
  numbers: [
    '+4570305051',
    '+4570305052'
  ],
  selectable: false,
  language: 'da',
  ringtone: -1,
  musicOnHold: null,
  goto: null,
  pbx: {
    mode: 'BOTH',
    retension: 7,
    email: 'info@telecomx.dk'
  }
}

Errors

Error code Message Description
404 customer Customer not found or not active
422 name Name must be at least 3 characters
409 number Number is in use by another dialplan item
422 number Number is invalid, only 0-9 is allowed and no public service numbers
422 redirect Redirect number is invalid, only + 0-9, # and * is allowed
404 redirect Redirect number is local but does not point to an existing dialplan item
404 startAudio Start audio file not found
404 musicOnHold The music on hold class does not exist
404 goto Dialplan item not found
409 numbers One or more numbers are not available
409 numbers One or more numbers are already in use
422 retension Retension must be between 0 and 90 days
422 fax.mode Invalid mode, use OFF, RECEIVE, SEND or BOTH
422 fax.email Not a valid e-mail address
422 ringtone Invalid ringetone
422 language Invalid language, use en or da
422 foreignNumbers Foreign numbers must be a list / A hovednummer may have at most 100 foreign numbers
422 foreignNumbers[n] Each foreign number must be an object with a number and an optional description
422 foreignNumbers[n].number <number> is not a valid phone number in E.164 format (e.g. +4512345678)
422 foreignNumbers[n].number The customer owns <number> - add it as a normal number on a hovednummer instead of as a foreign number
422 foreignNumbers[n].description Description must be a text / Description may be at most 64 characters
404 foreignNumbersGroup The PBX group does not exist, is deleted or is not a group of the customer (checked when the group is set or changed)
404 numberBlacklist The number blacklist does not exist
403 access_denied Insufficient access level
500 internal_error <Unspecified>