Sonera CStream Messaging Web Service API with Python and SUDS

0.00 avg. rating (0% score) - 0 votes

In this article I will show you how to use the Sonera CStream Messaging Web Service API to send an SMS using Python, and a library called  SUDS. The CStream API is two-way service for both sending and receiving messages. You obviously need to pay for the service to get access. After you have your credentials, you can start using the service.

The SUDS is a lightweight SOAP Python client for exploring and using web services. A recent version can be installed on Debian based distros with “sudo apt-get install python-suds”, or on almost anything with “pip install suds”.

The one thing good to know before starting out, is that the Sonera web service uses WS Security for authentication, which is found in the suds.wsse module.

Let’s start hacking in iPython:

At this point you should see a lot of debug messages on the screen. Thats the SUDS querying the WSDL schema and finding out what’s possible. You can take a look at it if it you are interested, but there is a better way to explore the metadata.

The list of available methods and and data types is what we are interested in.

The three methods there match the API specification. The names are pretty much self-explanatory:

  • Send() sends text messages
  • GetMessageStatus() queries the status of sent messages
  • GetIncomingMessages() retrieves incoming messages

To invoke those methods, we must be able to create data in specified types. To send an SMS, we need to create an SmsData object, wrapped in a Data object. We can have SUDS create them for us:

That shows what the Data should look like. Let’s also create an SmsPayload object:

According to the specification, the message attribute must be a “base64 encoded UTF-8 encoded string”. Let’s test with a string that requires more than plain ASCII:

Now we have a payload set. The Data object is now ready for sending. We still need to create a list of recipients:

The recipient number must be a string, and it must have a country code. A sender id or number is also required, but it can be whatever you choose. We can give it directly to the Send() method when we send the message. But before that, we must set up authentication:

We set up a username/password token, and a timestamp. Now we have 120 seconds of time to send a message using the security tokens.

At this point, we should have everything we need to send our message. Use the Send() method:

You will get a reply from the remote server. It will either tell you that it failed for some reason, but if everything went ok, the message was queued for delivery, and the response object will look something like this:

The recipient should receive the message shortly.

To wrap it up, let’s make a simple class out of it. Put this to a file called

To use:

That’s it! The receiving of messages, the checking of message delivery status, and the handling of exceptions are left as exercises to the reader (and to myself).

 Useful links:

Leave a Reply