Table of Contents

API : PBX : SIP Phone Get

Introduction

This request will return the the specified SIP phone.

Request

URL https://api.telecomx.dk/pbx/sipphone/SIPPHONE_ID
Method GET
Access level VIEWER, MANAGER, OWNER, RESELLER, ADMIN.
Param SIPPHONE_ID Id of the SIP phone (24 hex-char string)

Query example

https://api.telecomx.dk/pbx/sipphone/1234567890ABCDEF12345678

Response

Json object
_id Id Unique id of the SIP phone.
pbxCluster Number Id of the PBX cluster the phone is on
1 - Production (default)
2 - Development
sipPhoneModel Id The model of SIP phone (from SipPhoneModels).
extension Id The extension the SIP phone belongs to, null if not yet assigned.
customer Id Id of customer the phone belongs to.
macAddress String 12-char MAC address of the SIP phone.
serial String Serial number, required for Grandstream devices.
product ObjectId Product of the SIP phone.
handsetIndex Number If the SIP phone supports multiple handsets (like a DECT base), this is the handsets position in the list of handsets. This is auto assigned when created and cannot be changed.
handsetAddress String If the SIP phone supports multiple handsets (like a DECT base) this is the handsets individual ID, similar to a MAC address - if applicable.
callWaiting Boolean True if call waiting is enabled, null if model does not support it (not used).
sidePanel String If the phone model supports side panels, this is the model that is used. Null if no side panels are used.
sidePanelCount Number If the phone model supports side panels, this is the number of panels that are attached to the phone.
softkeyConfigurationOnDevice Boolean True if soft keys are configured individual on the device, false if soft keys are configured on the user.
softkeyBlfBlindTransfer Boolean True if BLF type soft keys performs blind transfer instead of attended transfer (default).
headsetButton String If headset button is supported, this configures it:
speaker - activates the handsfree speaker
headset - activates the headset
speaker-headset - activates speaker and toggles between speaker and headset
headset-speaker - activates headset and toggles between headset and speaker.
dhsg Boolean True if the phone uses a DHSG headset.
displayBrightness Number Display brightness 0-15.
displayBrightnessIdle Number Display brightness when idle 0-15.
displayBackground String URL to fetch a picture to display in the background on supported phones.
displayFontColor String Font color on Mitel phones: LIGHT or DARK.
customConfig String Custom configuration data. For insertion into the generated configuration file for the phone. Do not use unless absolutely needed.
notes String Notes about the SIP phone.
Security settings
ip.mode String IP restriction mode:
OPEN - Phone can connect from any IP address. After initial connection (get config, registration or call) mode is changed to LOCKED and IP address is set.
LOCKED - Phone can only connect from the IP address in ip.address.
ROAMING - Phone can only connect from IP addresses in the countries listed in ip.countries.
ip.countries String If ip.mode is ROAMING, this is a comma list of ISO3166-2 country codes of countries where the SIP phone may connect from.
ip.address String The IP address the SIP phone may register/make calls/fetch config from, if mode is LOCKED.
username String Username for SIP authentication, auto-generated 32-char string.
password String Password for SIP authentication, auto-generated 32-char string.
instanceId String Optional ID of WebRTC instance (e.g. Communicator Desktop) that this phone belongs to.
Volume settings
ringer.volume Number Ringtone volume (if supported by model).
ringer.tone String Id of ringtone. If a built-in ringtone is used this is the index number of the tone. If a custom ringtone is used, this is the ID of the ringtone.
volume.handset.mic Number Handset microphone level (if supported by model).
volume.handset.speaker Number Handset speaker level (if supported by model).
volume.headset.mic Number Headset microphone level (if supported by model).
volume.headset.speaker Number Headset speaker level (if supported by model).
volume.handsfree.mic Number Handsfree microphone level (if supported by model).
volume.handsfree.speaker Number Handsfree speaker level (if supported by model).
Softkey settings
softkeys Array List of configured softkeys (if supported by model).
softkeys[].index Number Position of the softkey, 0-based.
softkeys[].function String Type of function the softkey performs:
SPEEDDIAL - Dial a number
BLF - Dial a co-worker and show busy status
LINE - Line key
DND - Enable/disable do-not-disturb
DNDOTHER - Enable/disable do-not-disturb on specific device
ADDRESSBOOK - Access the phones address book
REDIAL - Re-dials the last called number
VOICEMAIL - Calls voicemail
TRANSFER - Tranfer call
URL - Invokes a URL, possible returning an XML menu
HOLD - Puts the current call on hold
RECORD - Starts recording the call
MENU - Shows the phones menu
PICKUP - Pickup a ringing phone the group the phone belongs to
PICKUPGROUP - Pickup a ringing phone from a specific group
QUEUE - Join/leave a specific queue
SWITCH - a named on/off switch
PRESENCE - set presence state
softkeys[].value String Settings for the selected function:
SPEEDDIAL - phone number to call
BLF - id of extension to monitor/call
URL - URL to invoke (http://.…)
PICKUPGROUP - id of group to pickup call from
QUEUE - id of queue
SWITCH - name of the switch
DNDOTHER - id of device to toggle DND for
softkeys[].label String Text label to display next to the softkey (if supported by model).
Codec settings
codec.hdAudio Boolean True to allow HD audio codecs.
codec.video Boolean True to allow video codecs.
Network settings
network.dhcp Boolean True to assign IP address using DHCP (if supported by model).
network.ipAddress String IP address of SIP phone (if not using DHCP, and supported by model).
network.subnet String IP subnet mask (if not using DHCP, and supported by model).
network.gateway String IP address of default gateway (if not using DHCP, and supported by model).
network.dns1 String Primary DNS server (if not using DHCP, and supported by model).
network.dns2 String Secondary DNS server (if not using DHCP, and supported by model).
network.vlanId String Vlan ID 0-4094, default 0 (not used).
network.vlanPriority Number Vlan priority 0-7, default 0 (not used).
Purchase Info
orderId String Order ID of the SIP Phone, references to external economic system
date Date Date the phone was purchased
paymentOption String How the phone is purchased or financed: NONE, BOUGHT, RENTED OR SELF_OWNED
purchaseInfo.sidePanels Array List of sidepanels, and their financial information.
purchaseInfo.sidePanels[].serial String Serial number of side panel, must be unique across all SIP phones
purchaseInfo.sidePanels[].paymentOption String How the sidepanel is purchased or financed: NONE, BOUGHT, RENTED or SELF_OWNED
purchaseInfo.sidePanels[].orderId String Date the sidepanel was bought
purchaseInfo.sidePanels[].date Date When the sidepanel was bought/rented, etc.
purchaseInfo.sidePanels[].product ObjectId Product of this sidepanel, always has product type PBX_SIP_PHONE_SIDE_PANEL
Status (read-only)
status.configLoaded Date Date and time the configuration was most recently fetched (if supported by model).
status.configSaved Date Date and time the configuration was last saved.
status.online Boolean True if the phone is online.
status.expires Number Number of seconds until the phones registration expires, -1 if not online.
status.localIpAddress String Local IP address that phone is currently at (if available).
status.publicIpAddress String Public IP address that the phone is currently at (if available).
status.userAgent String The user agent string as presented by the phone.

Note that properties holding no value may be omitted from the object.

Example

{
  _id: '12345678901234567890ABCD',
  pbxCluster: 1,
  sipPhoneModel: '1234567890123457890AAAA',
  extension: '123457890123457890BBBB',
  customer: '1234567890123456780CCCC',
  macAddress: '4EE8A34B56F3',
  product: '1234567890ABCDEF12345678',
  handsetAddress: null,
  handsetIndex: null,
  callWaiting: true,
  notes: 'A note about the phone',
  softkeyConfigurationOnDevice: true,
  softkeyBlfBlindTransfer: false,
  ip: {
    mode: 'LOCKED',
    countries: '',
    address: '213.83.176.134'
  },
  username: '2yu9hjfy23iuhdwg9ewhufghuiweghui',
  password: 'g9ewhufg2yu9hjfy2whuiweghui3iuhd',
  instanceId: null,
  ringer: {
    volume: 4,
    tone: 2
  },
  volume: {
    handset: { mic: 5, speaker: 7 },
    headset: { mic: 5, speaker: 7 },
    handsfree: { mic: 3, speaker: 4 }
  },
  softkeys: [
    { index: 0, function: 'SPEEDDIAL', value: '112', label: 'Emergency' },
    { index: 1, function: 'BLF', value: '1234567890123457890FFFF', label: 'Hans Christian Anderson' }
  ],
  codec: { hdAudio: true, video: false },
  network: {
    dhcp: false,
    ipAddress: '192.168.1.10',
    subnet: '255.255.255.0',
    gateway: '192.168.1.1',
    dns1: '192.168.1.1',
    dns2: '8.8.8.8',
    vlanId: 0,
    vlanPriority: 5
  },
  status: {
    configLoaded: '2015-01-01T00:00:00Z',
    configSaved: '2015-01-01T00:00:00Z',
    online: true,
    expires: 2543,
    localIpAddress: '192.168.1.10',
    publicIpAddress: '213.83.176.134',
    userAgent: 'snom370/8.7.3.25'
  },
  purchaseInfo: {
    orderId: '7213',
    date: '2015-01-01-T00:00:00Z',
    paymentOption: 'BOUGHT',
    sidePanels: [
     {
        serial: '1234',
        paymentOption: "RENTED",
        date: '2015-01-01-T00:00:00Z',
        orderId: '1234678',
        product: '12345678901234567890ABCD'
     }, 
     {
        serial: '2341',
        paymentOption: "RENTED",
        date: '2015-01-01-T00:00:00Z',
        orderId: '98850',
        product: '12345678901234567890ABCD'
     }
    ]
  }
}

Errors

Error code Message Description
403 access_denied Insufficient access level
404 id SIP phone not found
500 internal_error <Unspecified>