Call back service
MyVoipApp Support Team
Support@myvoipapp.com
Index
1. Introduction
We discuss the network topology below firstly.
In the callback service network, there are three kinds of basic network elements.
Application server (AS): ASs are responsible for user interface, billing and data storage. They indicates miniSipServer ( MSS ) to establish Callback connections.
miniSipServer (MSS): MSS is responsible for receiving instructions from ASs and initiate, maintain and release VOIP connections. And most important, MSS is responsible for maintaining Callback service.
Peer SIP Server (PSS): provided by VOIP providers. PSSs are responsible for VOIP connections and media gateways.
1.1 Service description
Callback service is a special service. The service is not initiated from one phone or client as normal but from an AS. AS will indicate MSS to establish VOIP connections with two user numbers and a maximum duration.
When MSS receives this command, MSS should establish a VOIP connection towards to user1 firstly. When the user answers the call, MSS will start a timer to monitor the call and begin to establish a VOIP connection towards to user2. When user2 answers the call, MSS should merge two call segments and establish connections between user1 and user2.
After the call is disconnect, MSS will response it to AS with the real duration.
Of course, during this process, AS can send command to MSS to cancel callback calls.
2. AS-MSS interface
Following figure describes a basic flow between AS and MSS.
This inner interface(IIF) is based on UDP socket. MSS will open a UDP socket to receive command and response inner status to the application server. By default, MSS uses UDP port 5080 to do it.
IIF is text-encoded message. An IIF message is either a request message from AS to MSS, or a response message from MSS to AS.
IIF message = Method: Parameters.
"Method" should be uppercase and "Parameters" should be lowercase.
2.1 Method
In current version, there are four methods: REQUEST, ACK, RELEASE and RESPONSE.
REQUEST message is used by AS to indicate MSS establish callback service.
ACK is a response message to indicate AS that MSS has parsed the REQUEST message and begin to establish call sections.
RELEASE message is used by AS to cancel current callback call.
RESPONSE is from MSS. It carries the real duration of current call.
2.2 Parameters
Parameters have two parts. One is parameter name and another is parameter value. They are always formatted as following.
Parameter = "parameter name=parameter value".
Parameters are separated with ';'
For an example, here is a demo parameters string. "id=1234;user1=100;user2=101". In this demo, there are three parameters: 'id', 'user1' and 'user2'.
Following sections define details parameters for IIF methods.
2.2.1 Parameters in REQUEST message
| Parameter | type | length | Description |
|---|---|---|---|
| id | string | less than 32 characters | Call section identity assigned by AS |
| user1 | string | less than 32 characters | User 1. The called party in the first call. |
| user2 | string | less than 32 characters | User 2. The called party in the second call. |
| caller1 | string | less than 32 characters | Optional parameter. With this parameter, MSS will set it as caller party number in the first call. |
| caller2 | string | less than 32 characters | Optional parameter. With this parameter, MSS will set it as caller party number in the second call. |
| duration | integer | >=0 | how many seconds current call section can process. |
| ann_id1 | string | 8 digits string | Optional parameter and indicates to play announcement to user 1 when it answers the call. The default "ann1" is 00080002. You can load your own audio file to MSS and play it to the user 1 with this paramter. |
| ann_id2 | string | 8 digits string |
Optional parameter and indicates to play announcement to user 2 when it answers the call. You can load your own audio file to MSS and play it to the user 2 with this paramter. |
| ann_digit2 | string | >0 | Optional parameter and indicates to play digit announcement to user 2 when it answers the call. |
| record_call | - | - | Optional parameter. If REQUEST message has this parameter, that means MSS should record current call-back call. |
For example:
REQUEST: id=1234;user1=100;user2=101;duration=3600;
It means AS request a CALLBACK service. The service or the call is identified by AS with call ID '1234'. In this request, the first called party is '100', and the second called party is '102'. After the first called party answers the call, the whole call process can continue about 3600 seconds.
2.2.2 Parameters in ACK message
| Parameter | type | length | Description |
|---|---|---|---|
| id | string | less than 32 characters | Call section identity. It is the same parameter in REQUEST message. |
| sid | integer | >0 | service identity assigned by MSS. |
| code | string | less than 32 characters | It indicates whether the request message is processed. There are only two values.ok or fail |
For example:
- ACK: id=1234;sid=5678;code=ok;
- ACK: id=1234;code=fail;
2.2.3 Parameters in RESPONSE message
| Parameter | type | length | Description |
|---|---|---|---|
| id | string | less than 32 characters | Call section identity. It is the same parameter in REQUEST message. |
| sid | integer | >0 | service identity assigned by MSS. It is the same parameter in ACK message. |
| real_duration | integer | - | It indicates how many seconds current call continues. |
For example:
RESPONSE: id=1234;sid=5678;real_duration=180;
It means both users have talk for about 180 seconds and then the call is released.
2.2.4 Parameters in RELEASE message
| Parameter | type | length | Description |
|---|---|---|---|
| id | string | less than 32 characters | Call section identity. It is the same parameter in REQUEST message. |
| sid | integer | >0 | service identity assigned by MSS. It is the same parameter in ACK message. |
For example:
RELEASE: id=1234;sid=5678;
It means AS requires MSS to release the callback call whose id is '1234' and sid is '5678'.
3. Configuration
There are three kinds of configurations we shall prepare for callback service.
- Callback service configuration; This is service configuration.
- External line configuration; this is configuration for establishing connection with PSS.
- Peer servers configuration; this is configuration for establishing connection with AS.
3.1 Callback service
Please click menu 'service->call back service', then below dialog shall be showed and configured.
| Item | Description |
|---|---|
| Local listen port* | This is the port which MSS will open to receive instructions from AS. When this item is updated or modified, we should restart MSS to enable it. |
| External line mode | It indicates whether MSS shall connect to VOIP providers with external line. |
| Default caller | It can be blank if 'external line mode' is selected, and then the caller number will be the external line number. But if 'external line mode' is un-selected, it means MSS will connect to VOIP providers' server as 'server to server' mode and the 'default caller' should not be blank or REQUEST message must include 'caller1'/'caller2' parameters since some VOIP providers' reject blank caller number. |
3.2 External line
In above configuration, if 'external line mode' is selected, then we must configuration external line to connect VOIP providers.
Please click menu "data->external lines" to continue this configuration. We have to mention that the external line must be "all local users can use this external line to make outgoing call", then CALLBACK service logic can use this external line to initiate outgoing call.
Please refer to MSS manual document for details.
3.3 Peer server
MSS will only receive the instruction form the servers which have been configured in "Peer server". Then, we must add AS host and port into "Peer server"
Please click menu "data->Peer servers" to continue this configuration. We have to mention that server host address and port shall be configured rightly; otherwise, MSS will reject the CallBack request instruction. Please refer to MSS manual document for details.
4. F.A.Q
4.1 Can you provide a demo application to send callback request to MSS?
Well, the key point is to open a UDP socket to send text strings. Please refer to attached 'callback.php.zip'. We write a demo application in PHP. This application only sends a demo command string to our MSS server and doesn't wait response messages. You can update it according to your requirements or rewrite it in other languages.