Last time we learned how to get the access_token. This time we will use it while trying to send an SMS message.

$ access_token=$(curl -s -k -d grant_type=client_credentials "https://api.sonera.fi/autho4api/v1/token" --header "Content-Type:application/x-www-form-urlencod
ed" --header "Authorization: Basic $basic_auth_string" | grep access_token | cut -d: -f2 | tr -d "\",")

$ echo $access_token
41282571-a525-439a-8462-79db44ad2af1

(notice how I this time use the $(curl…) syntax instead of backtick notation `curl…`)

API Reference

You should always first check what the API Reference tells you to do:

API Reference for Outbound Message Requests

For some reason it shows you how to send a binary message … when most likely you would want to start with sending a text message. (the binary message is unlikely to be displayed by your phone … which will probably leave you confused about whether your API Call worked or not!)

There is a Request Parameters chapter later in the document, based on which one can construct a simple request with outboundSMSTextMessage:

$ curl -s -k -d '{"outboundMessageRequest":{"address":["tel:+358403219113"],"senderAddress":"tel:+358000000000","outboundSMSTextMessage":{"message":"Hello World"},"senderName":"JPLa"}}' "https://api.opaali.telia.fi/production/messaging/v1/outbound/tel%3A%2B358000000000/requests" --header "Content-Type:application/json" --header "Authorization: Bearer $access_token" 

There are a couple of “tricks” you may want to make note of:

we use the dummy address +358000000000 as senderAddress as we haven’t been assigned a short code yet (you don’t need a short code for sending BULK MT messages)
numbers in international (+358…) format need to have a “tel:” prefix (no prefix for short codes)
the senderAddress value needs to be repeated in the API URL (and it needs to be URL-encoded when used as part of a URL!)
the optional senderName field will overwrite the given senderAddress
also note the use of single quotes (‘) around the message content to avoid needing to escape nested quotes(“) (you could write “{\“outboundMessageRequest\”:{\“… if that is your preference…)

Lets run this command and see what we get!

$ curl -s -k -d '{"outboundMessageRequest":{"address":["tel:+358403219113"],"senderAddress":"tel:+358000000000","outboundSMSTextMessage":{"message":"Hello World"},"senderName":"JPLa"}}' "https://api.opaali.telia.fi/production/messaging/v1/outbound/tel%3A%2B358000000000/requests" --header "Content-Type:application/json" --header "Authorization: Bearer $access_token"

$

…we got absolutely nothing, which is not what we expected. To do a little bit of debugging lets run it in verbose mode and use some shell script trickery to filter out everything except the request and response lines (by directing stderr output to stdout and grepping only lines starting with < or > (if you really wanted to know))

$ curl -v -k -d '{"outboundMessageRequest":{"address":["tel:+358403219113"],"senderAddress":"tel:+358000000000","outboundSMSTextMessage":{"message":"Hello World"},"senderName":"JPLa"}}' "https://api.opaali.telia.fi/production/messaging/v1/outbound/tel%3A%2B358000000000/requests" --header "Content-Type:application/json" --header "Authorization: Bearer $access_token" 2>&1 | grep -E "<|>"
> POST /production/messaging/v1/outbound/tel%3A%2B358000000000/requests HTTP/1.1
> Host: api.opaali.telia.fi
> User-Agent: curl/7.47.1
> Accept: */*
> Content-Type:application/json
> Authorization: Bearer  753fc2e3-d69b-452d-a5a8-1230dbeb6583
> Content-Length: 167
>
< HTTP/1.1 403 Forbidden
< date: Thu, 27 Jul 2017 11:03:37 GMT
< server: Operator Service Platform
< Content-Length: 0
<

$

What is ‘Sandbox mode’?

When you create a new application, it will initially be in ‘Sandbox mode’. While in sandbox mode you can test your application outside of the real telephone network and avoid making costly mistakes. You don’t need to decide all the details of the service yet and you won’t be billed for messages until you request ‘Promote to Production’ to enter production mode. Production mode and sandbox mode use different API URLs, so we need to change ‘production’ into ‘sandbox’:

$ curl -s -k -d '{"outboundMessageRequest":{"address":["tel:+358403219113"],"senderAddress":"tel:+358000000000","outboundSMSTextMessage":{"message":"Hello World"},"senderName":"JPLa"}}' "https://api.opaali.telia.fi/sandbox/messaging/v1/outbound/tel%3A%2B358000000000/requests" --header "Content-Type:application/json" --header "Authorization: Bearer $access_token"
{
  "resourceReference" : {
    "resourceURL" : "https://api.opaali.telia.fi/sandbox/messaging/v1/outbound/tel%3A%2B358000000000/requests/1485bfbb-5d03-4535-b5a7-2221f0326471"
  }
}
$

This time everything seemed to go well and we even got a resourceURL back which we can later use to check the delivery status of the message.

Where did it disappear?

After a while you may start wondering why hasn’t the sent message arrived at your phone even though the send request seemed to be successful. Before you write to opaali-tuki@teliacompany.com to ask why it didn’t work, go back to Chapter 2 of the Opaali Portal Quick Guide and have a look at this picture:

Sandbox Use Case

While in sandbox, you are disconnected from the actual telephone network, so there is no way the message you sent from sandbox could end up in your phone! Read the document API Telia OMA Sandbox REST in the Resources section of Opaali Portal. It turns out that you are supposed to use specified predefined phone numbers to get canned responses. This way you can easily simulate many of the common error cases, too. Chapter 3.2 lists the scenarios with expected responses, lets try number 6 where we should get a policy error:

$ curl -s -k -d '{"outboundMessageRequest":{"address":["tel:+35812345005"],"senderAddress":"tel:+358000000000","outboundSMSTextMessage":{"message":"Hello World"},"senderName":"JPLa"}}' "https://api.opaali.telia.fi/sandbox/messaging/v1/outbound/tel%3A%2B358000000000/requests" --header "Content-Type:application/json" --header "Authorization: Bearer $access_token" 
{
  "requestError" : {
    "policyException" : {
      "messageId" : "POL3003",
      "text" : "The following policy error occurred: %1. Error code is %2.",
      "variables" : [ "Maximum Transactions per Interval Exceeded.", "3003" ]
    }
  }
}
$

Yep - you can get this policy error in production mode, too, if you make too many API requests in a short period of time. To avoid this, try to slow down making your requests so that you don’t exceed the Transactions Per Second (TPS) limit.

When you think your application is ready, you can request ‘Promote to Production’ and move to production mode. The request and response will look the same as in our successful sandbox example earlier in this article (just replace sandbox with production in the URL this time) and if all goes well the message should reach your phone.

Next time we will see how to use the ResourceURL we got in the response to check the delivery status of the sent message.

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

Getting started with Opaali API - Part 2

Sending a message

API Reference

What is ‘Sandbox mode’?

Where did it disappear?