The realtime interface is based on socket.io, so that any compatible platform may listen in.

This document will focus on the javascript implementation into a webpage.

Other types of apps should take similar steps and connect to the endpoint: https://api.telecomx.dk

Include https://api.telecomx.dk/socket.io/socket.io.js - e.g.:

<script src="https://api.telecomx.dk/socket.io/socket.io.js"></script>

Connecting requires a token from a validated logon - see Login for documentation.

socket = io.connect(host);
socket.on('connect', function() {
  socket.emit('authenticate', { token: my_login_token, client: 'Application name', instanceId: 'unique-id-of-client', ip: '1.2.3.4' });
});
socket.on('authenticated', function () {
  socket.emit('subscribe', { type: 'event_type' });
});

client, instanceId and ip are not required, but recommended and helps when debugging issues.

You can subscribe to the following channels:

  // Admin users only
  socket.emit('subscribe', { type: 'ADMIN'); // Admin firehose
  socket.emit('subscribe', { type: 'ADMIN', types: [ 'CONFIG','CALL','REGISTER','PBX','REALTIME'] }); // Admin firehose for specific types
  socket.emit('subscribe', { type: 'ADMIN:CONFIG' }); // All configuration events
  socket.emit('subscribe', { type: 'ADMIN:CALL' }); // All call events for outbound/inbound calls
  socket.emit('subscribe', { type: 'ADMIN:REGISTER' }); // All register/unregister events for SIP trunks and SIP phones
  socket.emit('subscribe', { type: 'ADMIN:PBX' }); // All PBX events
  socket.emit('subscribe', { type: 'ADMIN:REALTIME' }); // All Realtime connect/disconnect events
 
  // Users with at least PERSONAL permission
  socket.emit('subscribe', { type: 'PBX', customer: '12345789012457890ABCD' }); // PBX events on customer
  socket.emit('subscribe', { type: 'PBX', customer: '12345789012457890ABCD', events: ['CALL_START','CALL_END'] }); // PBX events on customer, but only specific events
  socket.emit('subscribe', { type: 'CONFIG', customer: '12345789012457890ABCD' }); // Configurations events on customer
  socket.emit('subscribe', { type: 'CONFIG', customer: '12345789012457890ABCD', events: ['EMPLOYEE_CREATED','EMPLOYEE_UPDATED','EMPLOYEE_DELETED'] }); // Configurations events on customer, but only specific events
  socket.emit('subscribe', { type: 'CONFIG-NOT-IPTV', customer: '12345789012457890ABCD' }); // Configurations events on customer, excluding IPTV
 
  // Users with at least VIEWER permission
  socket.emit('subscribe', { type: 'REGISTER', customer: '12345789012457890ABCD' }); // SIP trunk and SIP phone register events on customer
  socket.emit('subscribe', { type: 'CALL', customer: '12345789012457890ABCD' }); // Call events for outbound/inbound calls on customer

You may also listen to the following event to handle when you are connected or disconnected:

socket.on('subscribed', function(data) { write('We are now subscribed to ' + data.type); });
socket.on('unsubscribed', function() { write('We are now unsubscribed'); });
socket.on('disconnect', function(data) { write('Disconnected!'); });

If the connection the the server is lost, Socket.IO will automatically reconnect when possible. Because we listen to connect and authenticated, we will automatically be authenticated and resume listening to the relevant events as soon as we are re-connected.

To be notified when an event is received, you listen for the type of event:

socket.on('CONFIG', function(event) { write('We got a config event'); });

The events event object contains 5 properties:

This both reports register events and authentication errors for both register and invite requests.

This reports the creation of call session on the SIP trunk servers. It is used internally to keep track of ongoing calls.

Events related to hosted PBX.

Between 2 realtime client requests and replies can be sent using this feature.

Both ends must listen to REQUEST and REPLY messages, using socketio.on('REQUEST', handler) handling.

A request is sent using socket.io emit into the room request with the following message payload:

Types of requests that are currently known:

Communicator requests only works if the sender has access to the recipient (e.g. same customer, reseller or admin). CommunicatorZeroTier requests are only accepted if sender and receiver is the same employee.

{
  to: {
    employee: '12345678901234567890ABCD',
    instanceId: 'cvh38ruvhbe3ugvbhehgviwhvhcienbvj'
  },
  request: 'CommunicatorGetStatus',
  replyTo: {
    employee: '12345678901234567890AAAA',
    instanceId: 'dbewiuvhegf84hrtfu849yi4hb3wui9gjfndf'
  }
}

Please use the socketio.emit('request', playload, response ⇒ {}) api to send the request, as the response object will hold the following:

A reply is sent using socket.io emit into the room reply with the following message playload:

Please consider that some requests may yield multiple replies, e.g. when requesting a stream or when sending a request to all of the clients an employee has.