CSTA TCP client API

This API uses XML over TCP like a classic physical telephony server. The client can be written in any programming language that supports creating a TCP socket.

How to use

tip

The TCP client support XML requests, responses and events. They follow the CSTA format in the ECMA-323 CSTA Standard.

1. Open a TCP socket.
2. Authentication: Login by sending a CSTA StartApplicationSession request in XML format (as a string) to the socket.
3. CSTA request, responses and CSTA events are received as strings from the TCP socket. You need to split up the received text into XML document strings and then deserialized into a typed object if needed.

.NET sample client

The C# sample client is written for .NET Core 6 using the NetCoreServer library available at nuget.

public class TcpClient : NetCoreServer.TcpClient
    {
        private const string MESSAGE_TERMINATOR = "\0";

        private readonly Action<object> _newMessageFunc;
        private readonly Serializer _serializer;
        private string _dataReceived = string.Empty;

        public TcpClient(Action<object> newMessageFunc, string address, int port) : base(address, port)
        {
            _newMessageFunc = newMessageFunc;
            _serializer = new Serializer();
        }

        public void SendAsync<T>(T message)
        {
            Console.WriteLine($"Sending {message.GetType()} message ");

            base.SendAsync(_serializer.Serialize(message) + MESSAGE_TERMINATOR);
        }

        protected override void OnConnected()
        {
            Console.WriteLine($"TcpClient connected");

            ReceiveAsync();

            base.OnConnected();
        }

        protected override void OnDisconnected()
        {
            Console.WriteLine($"TcpClient disconnected");

            base.OnDisconnected();
        }

        protected override void OnReceived(byte[] buffer, long offset, long size)
        {
            var chunk = Encoding.UTF8.GetString(buffer, (int)offset, (int)size);
            _dataReceived += chunk;

            while (_dataReceived.Contains(MESSAGE_TERMINATOR))
            {
                var index = _dataReceived.IndexOf(MESSAGE_TERMINATOR, StringComparison.Ordinal);
                var message = _dataReceived.Substring(0, index);
                _dataReceived = _dataReceived.Substring(index + 1);

                try
                {
                    var convertedMessage = _serializer.Deserialize(message);
                    _newMessageFunc(convertedMessage);
                }
                catch (Exception ex)
                {
                    // ARGH
                    Console.WriteLine($"Invalid XML document? Exception: {ex.Message}. XML = {message}");
                }
            }
        }

        protected override void OnError(SocketError error)
        {
            Console.WriteLine($"TCP client returned error code: '{error}'");
        }

Example XML requests

This example connects to the CSTA server and then sends a MakeCall request. Local number 200 calls 22334455.

Send TCP string:

StartApplicationSession request

<?xml version="1.0" encoding="utf-16"?>
<StartApplicationSession>
  <applicationInfo>
    <applicationSpecificInfo>
      <vendorData:userID>bill@uni-tel.dk</vendorData:userID>
        <vendorData:password>*******<vendorData:password>
        <vendorData:pbxDomain>22334455.pbx.one-connect.dk</vendorData:pbxDomain>
      </applicationSpecificInfo>
    </applicationInfo>
  <requestedSessionDuration>120</requestedSessionDuration>
</StartApplicationSession>

Wait for a response:

StartApplicationSession response

<StartApplicationSessionPosResponse xmlns="http://www.ecma.ch/standards/ecma-323/csta/ed6">
  <sessionID>HotFShcrHZWUfc6tMIjD0A</sessionID>
  <actualProtocolVersion>http://www.ecma.ch/standards/ecma-323/csta/ed6</actualProtocolVersion>
  <actualSessionDuration>120</actualSessionDuration>
</StartApplicationSessionPosResponse>

Send TCP string:

MakeCall request

<MakeCall>
  <callingDevice>200</callingDevice>
  <calledDirectoryNumber>22334455</calledDirectoryNumber>
  <autoOriginate>doNotPrompt</autoOriginate>
  <privateData>
    <requestID>155-a04dbfd1-ec67-4637-93b8-8248f13fe691</requestID>
  </privateData>
</MakeCall>

Wait for a response like

MakeCall response

<MakeCallResponse xmlns="http://www.ecma.ch/standards/ecma-323/csta/ed6">
  <privateData>
    <requestID>155-a04dbfd1-ec67-4637-93b8-8248f13fe691</requestID>
  </privateData>
  <callingDevice>
    <callID>N/A</callID>
    <deviceID>200</deviceID>
  </callingDevice>
  <callLinkageData>
    <globalCallData>
      <globalCallLinkageId>N/A</globalCallLinkageId>
    </globalCallData>
  </callLinkageData>
</MakeCallResponse>

Get access to uni-tel CSTA TCPI API

If you want to know more, feel free to contact us here. The contact form is in Danish only, but inquiries in English are most welcome.