Welcome to the Socket Server Connection Program

The Socket Server program allows you to send messages through the SkyTel Web Site as well as check the delivery status of Two-Way messages by using a URL and a little cgi programming.

To use this feature, you connect to www.skytel.com using a specific URL. This URL contains arguments that instruct our server to perform messaging functions on your behalf. Our server then instructs your browser to load a URL on your server to display the results. Using this functionality, you can create your own messaging forms and host them on your site.

The input arguments are described below:

  • cmd=[send|status|profile|coverage] : (Required) This argument lets our server know if you are sending a message, or checking the delivery status of a previously sent message, or checking the profile of a pin (device type), or checking the coverage information.
  • to=<PIN:USAGECODE,TYPE> : (Required for send, status and profile commands) This argument indicates the PIN or MailID of the messaging unit, the USAGE Code if required as well as the type of unit. The USAGE Code is a 4 digit code which is optional (if the pin doesnot require one). The TYPE should be a "1" for SkyWord® pagers, a "2" for SkyTel 2-Way pagers, and a "4" for SkyWord® Plus pagers. Up to 50 "to" arguments can be used to send to multiple units.
  • msg=<text> : (Required when sending a message.) This argument contains the text of your message. Note that all non-alphanumeric characters should be converted to their ASCII hexadecimal values. For example, spaces should be converted to "%20" before calling the URL.
  • zip=<ZIP> : (Required when checking the coverage.) This argument contains the zipcode of the area you want to check the coverage for.
  • reply=<PIN,TYPE> : (Optional) Can be used to direct the reply of Two-Way pagers to other devices. The TYPE tells the server if the device to be replied to is a SkyWord®, Two-Way, an Email address or SkyWord® Plus pager. The values for TYPE are 1,2,3, and 4, respectively.
  • mcr=<mcr_text> : (Optional) Allows you to specify your own multiple choice responses when sending to a Two-Way messaging unit. Note that, like the "msg" argument, you must convert all non-alphanumeric characters to their ASCII hexadecimal values before calling the URL. You can have up to 15 mcrs.
  • sender_id=<Sender ID/Name> : (Optional) This argument should be set to the sender's name or signature. If supplied, this value will be appended to the message and will appear as the sender's id when the customer's inbox is downloaded using the Access software packages. As with the mcr and msg arguments, you should convert all non-alphanumeric characters to their ASCII hexadecimal values.
  • claim=<claim #> : (Required when checking delivery status.) This is the value of the confirmation number as returned by our server for Two-Way messages.
  • success_url=<URL> : If you do not want to create a CGI program to handle the response of our server program, simply use this argument to specify a static HTML file on your server. If the command you issue completes successfully on our end, we will load this URL.
  • error_url=<URL> : Like the success_url, you can use this argument to tell us what static HTML page you want us to load if your command does not complete successfully.
  • cgi_url=<URL> : If you wish to develop your own CGI program to process the response of our server program, specify the URL for this program in this argument (See below for more information pertaining to the use of "cgi_url").
  • date=xx/xx/xxxx : The "date" argument is one of the required arguments for future delivery that specifies the date on which the message should be delivered. For instance, if a message needed to be delivered on January 30, 2000, then date=1/30/2000 would be the proper format for this argument.
  • time=xx:xx : The "time" argument is another requirement for future delivery. The time is specified in 24 hour format. If a message needed to be delivered on January 30, 2000 at 13:20, then the proper format for the time argument would be time=13:20. Adjustments for daylight savings time are made automatically.
  • timezone=(eastern|mountain|central|pacific) : The "timezone" argument is optional for future delivery. If the message is being sent from a timezone other than CST/CDT, then this argument will ensure the time for the particular timezone specified is used.

The output arguments of the server program are described below:

  • return_code=<code> : This argument represents the exit status of our server program. If this value is less than zero, an error occurred and your command was not completed successfully. (See "return_text" below to find out what went wrong.) If the value is zero, your SkyWord® or SkyWord® Plus message was successfully received, or the status check was successful, depending on the command you issued. If "return_code" is greater than 0, then it is the confirmation number for your Two-Way message which was sent successfully.
  • return_text=<text> : This is the text response of the command you issued. If an error occurred, it describes the error. If the command was successful, it is either the confirmation number or the status of a Two-Way message.
  • All input arguments : All of the arguments passed to the ss_paging.cgi script are also returned to the script listed in the cgi_url argument. Knowing the input arguments will allow you to provide more information to your user. For example, you can display the message that was sent as well as the recipients of the message.

Here is an example showing the proper use of the Socket Server Program:

The following URL will send the message "This is a test message." to Two-Way units 1230023, 1230024 and 1230025 which is a pin with Usage Code 1234. If any of the recipients respond, the response will be sent to SkyTel 2-Way unit 1230026. The message includes two multiple choice responses created by the sender. The CGI script response.cgi at your_server.domain will handle the result of the command.

  • http://www.skytel.com/cgi-bin/ss_paging.cgi?cmd=send&to=1230023,2&to=1230024,2&to=1230025:1234,2 &msg=This%20is%20a%20test%20message.&reply=1230026,2&mcr=MCR1&mcr=MCR2 &cgi_url=http://your_server.domain/response.cgi

We hope you enjoy this new feature!  Please let us know what you think by sending your comments to the webmaster.