In article Getting Started with Opaali API Part 2 we learned how to send a MT text message. Lets now see how to send a binary message. First, we’ll revisit the API Reference.

API Reference

The API Reference used an example of sending a binary message:

API Reference for Outbound Message Requests

I am not going to use this particular example, as I do not have a handset that can decode this message. In general, if a handset (=phone) cannot decode a message it will just show no evidence of the message having arrived at all (that is: if you make a mistake in the data of a binary message, it will seem like it was never sent and you will complain about it to opaali-tuki@teliacompany.com).

More API Reference

API Reference for Outbound Message Requests, continued

So it seems we need to construct a UDH (User Data Header) and Base64 encode the binary data payload.

Trust me, I know what I am doing!

If you want to send a binary text message you probably have a reason for doing this and know what kind of data to send and how to construct the message.

For a simple example, lets try sending a calendar appointment in vCalendar format to a compatible handset.

Back to the nineties!

Symbian based Nokia smartphones (like my old Nokia E5) supported Smart Messaging (see Wikipedia: Smart Messaging). If you Google for nokia smart messaging specification you can hopefully find the Smart Messaging Specification - Revision 3.0.0 from year 2000 (or even the 1.0.0 version from 1997!) which in chapter 3.5 tells us what we need to know:

Calendar information transfer is based on the Versit vCalendar specification. The vCalendar specification defines a format for electronic calendaring and scheduling. This format is suitable to be used as an interchange format between applications or systems, and it is independent of the method used to transport it.
...
The vCalendar reader is listening to on WDP port 9205 decimal (23F5 hexadecimal) or WTLS-secured WDP
port 9207 decimal (23F7 hexadecimal).

vCalendar has since been superceded by iCalendar (see Wikipedia: iCalendar) which is quite a similar format. But there is an example we can use in the Smart Messaging document:

If we save the example vCalendar message to a file example.vcal

BEGIN:VCALENDAR
VERSION:1.0
BEGIN:VEVENT
DESCRIPTION:Steering Group meeting in Portal
DTSTART:20000906T100000
DTEND:20000906T120000
END:VEVENT
END:VCALENDAR

we can see that the content as hex encoded matches what was in the Smart Messaging document (at least if you are using Windows which uses CR+LF as line endings):

$ xxd example.vcal
00000000: 4245 4749 4e3a 5643 414c 454e 4441 520d  BEGIN:VCALENDAR.
00000010: 0a56 4552 5349 4f4e 3a31 2e30 0d0a 4245  .VERSION:1.0..BE
00000020: 4749 4e3a 5645 5645 4e54 0d0a 4445 5343  GIN:VEVENT..DESC
00000030: 5249 5054 494f 4e3a 5374 6565 7269 6e67  RIPTION:Steering
00000040: 2047 726f 7570 206d 6565 7469 6e67 2069   Group meeting i
00000050: 6e20 506f 7274 616c 0d0a 4454 5354 4152  n Portal..DTSTAR
00000060: 543a 3230 3030 3039 3036 5431 3030 3030  T:20000906T10000
00000070: 300d 0a44 5445 4e44 3a32 3030 3030 3930  0..DTEND:2000090
00000080: 3654 3132 3030 3030 0d0a 454e 443a 5645  6T120000..END:VE
00000090: 5645 4e54 0d0a 454e 443a 5643 414c 454e  VENT..END:VCALEN
000000a0: 4441 520d 0a                             DAR..

$

UDH

The Smart Messaging Specification shows how to send smart messages in an old, text message compatible format. There is a reference to WDP which defines a binary format which uses UDH. Instructions for constructing a UDH can be found e.g. in 3GPP TS 23.040 V5.3.0 (2002-03) Technical Specification, but I think the easiest way for us is just to read this Wikipedia article: Wikipedia: User Data Header. We will use Application port addressing scheme, 16 bit address, the target port we already found out in the Smart Messaging document: 9205 decimal (23f5 hexadecimal).

Our UDH

To construct the binary message payload, we will first combine the hex representations of the UDH and the vCal message:

$ vcal_udh=06050423f50000

$ vcal_msg=$(cat example.vcal | xxd -p | tr -d "\n")

$

(the -p switch in xxd generates a plain hexdump which is folded into several lines, therefore we use tr to delete the line breaks)

Now we will concatenate the hex representations of the UDH and the vCal into a single string, decode the string into binary representation using xxd -r -p and base64 encode this using base64 (and still removing any line breaks so that we get a continuous string).

$ bin_msg=$(echo -n $vcal_udh$vcal_msg | xxd -r -p | base64 | tr -d "\n")

$ echo $bin_msg
BgUEI/UAAEJFR0lOOlZDQUxFTkRBUg0KVkVSU0lPTjoxLjANCkJFR0lOOlZFVkVOVA0KREVTQ1JJUFRJT046U3RlZXJpbmcgR3JvdXAgbWVldGluZyBpbiBQb3J0YWwNCkRUU1RBUlQ6MjAwMDA5MDZUMTAwMDAwDQpEVEVORDoyMDAwMDkwNlQxMjAwMDANCkVORDpWRVZFTlQNCkVORDpWQ0FMRU5EQVINCg==

API Console (again)

Now we can test whether we managed to encode the binary message correctly by using the API Console, which you can find in the developer portal at the Application Profile of your send application:

Sending a Binary Message using API Console

You only need to

• select outboundSMSBinaryMessage as messageType
• fill in recipient address
• paste the base64 encoded string we constructed (as a single line) into the message field
• fill in the default senderAddress (+358000000000)
• optionally set a meaningful senderName

When we click the Send! button we can see that the message was successfully sent:

Sending a Binary Message using API Console: response

(Notice that you don’t need to authenticate when using the API Console, it does it automatically for you.)

And if your phone supports receiving vCalendar messages you will find it on your phone:

(Note that this is an old Symbian phone - many of the current smartphones will not show you anything!)

Why don’t we do it on the command line?

In Getting Started with Opaali API Part 2 we learned how to send a MT text message from the command line. After retrieving a fresh access_token we can construct the send request for a binary message based on the request_body displayed in the API Console output:

{
  "outboundMessageRequest": {
    "senderAddress": "tel:+358000000000",
    "senderName": "JPLa",
    "address": [
      "tel:+358403219113"
    ],
    "outboundSMSBinaryMessage": {
      "message": "CwADqgICBQQj9QAAbiBQb3J0YWwNCkRUU1RBUlQ6MjAwMDA5MDZUMTAwMDAwDQpEVEVORDoyMDAwMDkwNlQxMjAwMDANCkVORDpWRVZFTlQNCkVORDpWQ0FMRU5EQVINCg=="
    }
  }
}

We need to practice some quotation-trickery so that we can store the binary message into shell variable bin_msg and have it correctly expanded:

$ echo $bin_msg
BgUEI/UAAEJFR0lOOlZDQUxFTkRBUg0KVkVSU0lPTjoxLjANCkJFR0lOOlZFVkVOVA0KREVTQ1JJUFRJT046U3RlZXJpbmcgR3JvdXAgbWVldGluZyBpbiBQb3J0YWwNCkRUU1RBUlQ6MjAwMDA5MDZUMTAwMDAwDQpEVEVORDoyMDAwMDkwNlQxMjAwMDANCkVORDpWRVZFTlQNCkVORDpWQ0FMRU5EQVINCg==

$ curl -s -k -d '{"outboundMessageRequest":{"senderAddress":"tel:+358000000000","senderName":"JPLa","address":["tel:+358403219113"],"outboundSMSBinaryMessage":{"message":"'"$bin_msg"'"}}}' "https://api.opaali.telia.fi/production/messaging/v1/outbound/tel%3A%2B358000000000/requests" --header "Content-Type:application/json" --header "Authorization: Bearer $access_token"
{
  "resourceReference" : {
    "resourceURL" : "https://api.opaali.telia.fi/production/messaging/v1/outbound/tel%3A%2B358000000000/requests/4d61a20a-f44d-478e-9153-9394e3f7d596"
  }
}
$

Stop! This is more than we can handle!

Those of you who have really paid attention may have noticed that our vCalendar message contains more than 160 characters…
That’s right! Opaali API fragments long messages, even binary messages, for you (…or it may be the SMSC API below Opaali API. We don’t know and shouldn’t even care! It is an implementation detail beyond our control.)

---

JPLa is a member of the Content Gateway (CGW) to Opaali migration team, specialising in programming related issues and API usage.

---

• ← Previous Post
• Next Post →