Opaali Portal – Quick guide

Company information
Telia Finland Oyj
Teollisuuskatu 15, 00510 HELSINKI, FI
Registered office: Helsinki
Business ID 1475607-9, VAT No. FI14756079 Page
1 (40)
 Page
2 (40)

Copyright © 2017 Telia Company

All rights reserved by respective owners.

Revision: 8.0

Table of contents
1 Partner Dashboard......................................................................................................................... 3
1.1 Login to Telia Opaali portal .................................................................................................. 3
1.2 Edit User Profile ................................................................................................................... 4
1.3 Manage Partner ................................................................................................................... 4
1.4 Partner Numbers .................................................................................................................. 5
1.5 Partner Reports .................................................................................................................... 6
1.6 Invite User to Partner ........................................................................................................... 8
1.7 Forgot your password?......................................................................................................... 9
2 Partner Use Cases....................................................................................................................... 12
2.1 Sandbox............................................................................................................................. 12
2.2 Mobile Messaging .............................................................................................................. 13
2.3 Messaging Interface ........................................................................................................... 15
2.4 Mobile Charger .................................................................................................................. 18
3 Manage Application ..................................................................................................................... 20
3.1 Create Application .............................................................................................................. 20
3.2 Edit Application Details ...................................................................................................... 21
3.3 Manage Endpoints ............................................................................................................. 23
3.4 Manage Notifications.......................................................................................................... 24
3.5 Request New Number ........................................................................................................ 25
3.6 Create Keyword ................................................................................................................. 26
3.7 Create Notification.............................................................................................................. 28
3.9 API Console ....................................................................................................................... 31
4 Sandbox....................................................................................................................................... 31
4.1 Sandbox Checklist ............................................................................................................. 31
5 Promote to Production ................................................................................................................. 33
5.1 Application Checklist .......................................................................................................... 33
5.2 Partner Profile .................................................................................................................... 33
5.3 Application Profile .............................................................................................................. 35
5.4 Application Bundle Description ........................................................................................... 36
5.5 Production mode ................................................................................................................ 39
5.6 Developer Resources ......................................................................................................... 40
 Page
3 (40)

1 Partner Dashboard

1.1 Login to Telia Opaali portal

Use the credentials (your email address and password) that you have received from Telia Opaali support
team to log into Telia Opaali portal.

Opaali portal address is https://developer.opaali.telia.fi

Note: When log into Opaali portal for the first time, you must accept the Terms And Conditions and then
you need to select response for your security question in case you will forgot your password.

After you have logged in, dashboard view with user profile and a list of partner profiles will be displayed.

You can access all the Partner Profiles associated with your Opaali portal Partner ID from here.
 Page
4 (40)

1.2 Edit User Profile

By clicking link “Edit Profile” you can edit your User profile in Opaali Portal. You can change Password,
Email or Security Details from this page and change your Personal Information.

1.3 Manage Partner

Select a partner and click “Manage Partner” button to open up partner management view. In partner
management page, you can start adding applications for your partner.
 Page
5 (40)

1.4 Partner Numbers

By clicking link ”Partner Numbers” you can see which Short Code Numbers and informative Long
Numbers are attached to your partner profile.

Note: Inbound Notifications for MO messages in Opaali Portal are always created for Short Codes, not
for the Long Numbers.

Routing for Long Numbers is done in Telia network where long numbers are mapped to the assigned
short codes and routed to the Opaali platform for the Partner notification(s).
 Page
6 (40)

1.5 Partner Reports

By clicking link ”Partner Reports” or ”Partner Summary Reports” you can view traffic and revenue reports
separately for the production and sandbox modes.

Click the link “Submit” to view partner report “CountPerOperation”.

In this example partner report shows monthly failure and success counts with HTML format. It is also
possible to generate report with CSV, XLS or PDF format and with different report types.

Example of ‘CountsPerOperation’ report type:

 Page
7 (40)

Example of ‘CountsPerMessageType” report:

 Page
8 (40)

1.6 Invite User to Partner

As a partner profile user you can invite users to the partner profile by clicking link “Invite User To
Partner”.

In the next page you can input the email address for the invited user and selecting Admin or Standard
access. You can define permissions for Partner access and separately for Application access.

From “Manage Invitations” page you can view pending invitations which have been sent the users.
 Page
9 (40)

1.7 Forgot your password?

If you forgot your password, you can reset it by clicking link “Forgot your password?” in the main log in
page of Opaali portal.
 Page
10 (40)

In the next page fill your email address and text from security box and click link “Reset Password”.
 Page
11 (40)

Stay in this browser session and check your email account for confirmation email.

You should have received confirmation email from Opaali-support team, click the confirmation link in the
email to continue resetting your password and then you are redirected back to the Opaali portal browser
page.

Next fill the response for the security question and type the new password twice, then click “Reset
Password” link.

Note: You have defined response to your security question when logged into Opaali Portal for the first
time.

When the new password meets the security requirements and password reset is succesfull, you will see
message "“Your new password has been saved” in the top of the Opaali portal page.
 Page
12 (40)

2 Partner Use Cases

Following chapter illustrates use case examples for the Partner with commercial business services
Mobile Messaging, Messaging Interface and Mobile Charger.

2.1 Sandbox
 Page
13 (40)

2.2 Mobile Messaging

Application types:

Bulk
Receive-Only No Charge
Page
14 (40)
 Page
15 (40)

2.3 Messaging Interface

Application types:

Send Only No Charge

Receive-Only With Charging
Query-Response No Charge
Query-Response With Charging
Push No Charge
Push With Charging
Page
16 (40)
Page
17 (40)
 Page
18 (40)

2.4 Mobile Charger

Application type:

Mobile Payment
Page
19 (40)
 Page
20 (40)

3 Manage Application

3.1 Create Application

Click “Create an application” button to start creating new application for the partner.

Note: You cannot have more than one application with the same application name under a single partner
profile. Make your application name as meaningful as possible because you won’t be able to change
application name or delete your application once you've created the application profile.

In case you need to delete your application, please contact opaali-tuki@teliacompany.com

At this point it’s a good practice to name the application based on your service and application type:

1) Sending MT messages (Bulk, Send-Only)

2) Receiving MO messages (Receive-Only, QR, Push)
3) Mobile Payment service

Type of application bundle is selected and confirmed in the promote-to-production phase later on.
 Page
21 (40)

Type in Application name and description and press “Create Application” button.

Portal will show you confirmation that application was created and open up application profile. You will
also receive an email confirmation of application created with application details.

3.2 Edit Application Details

From “Edit Application Details” page you can edit your application description and attributes for
applications.

Attributes that can be updated are Validity Timeout, Receive-Only price and currency, Query and
Response balance check and currency, Push balance check and currency and VAT percentage.

Validity time for MT messages can be configured (in minutes 0 - 4320) for the applications in Opaali
portal.
Page
22 (40)
 Page
23 (40)

3.3 Manage Endpoints

Click “Manage endpoints” link to open up application endpoint management view.

Your application credentials are shown here. These credentials were assigned to this application when
you created it and are unique to this application.

Note: These Application credentials (Application Username and Application Password) are used for
Basic Authentication to obtain Access Token from the production server’s authentication API.

Do not use these credentials for another application and do not share these credentials with anyone
else. These credentials are associated with your account. You are responsible for all activity that is tied
to the use of these credentials.

Your endpoints for use within your applications are also listed. You can disable an endpoint which will
prevent your credentials from being used with it. You can subsequently enable an endpoint to permit
use.
 Page
24 (40)

3.4 Manage Notifications

When you want to receive inbound MO messages, you need to define Short Code, Keyword and
Notification callback URL in Opaali portal.

Click “Manage Notifications” link to open up the page which allows you to create and manage your
notifications. You can request and assign short codes and long numbers that can then be used to create
the keywords for new notifications

By clicking link “Assign Partner Number” you can assign Partner Number to your application, if there are
already assigned Short Codes or Long numbers to your Partner profile.
 Page
25 (40)

3.5 Request New Number

Click ”Request Number” button to request a short code or a long number for the application. You can
request a specific number for the application or ask the number to be assigned automatically.

Note:

1) Please request a specific number if you want to use existing number from CGW platform or want
to request totally a new number.

2) Please request automatic number if you want to use Test short number in Opaali portal before
using real existing number from CGW. Test short number will be allocated to your Partner profile
for testing purposes by Telia Opaali Support team during the migration phase.

Select “Telia” checkbox from Countries and Networks options and click “submit” button.

Your request for new short code or long number has been sent for approval. “Pending Requests” button
will show you a list of requests that you have made and are in pending status.
 Page
26 (40)

You will receive email confirmation after the request has been processed by Telia Opaali Support team.
Go back to “Manage Notifications” menu after you have received the email confirmation and you will see
a number that has been assigned for your application.

By clicking link “Pending Requests” you can see Short Code and Long Number requests.

3.6 Create Keyword

Now that you have a number assigned for you application, you can go to create a keyword.
Click “Create Keyword” button and keyword creation screen opens. Select the number from the drop
down menu and type in keyword for the application and press “Create Keyword” button. Only letters and
numbers can be used in keyword name, special characters are not supported.

A keyword is used as part of a notifications search criteria. The keyword is used to identify which service
you want to invoke. e.g. A user might Text Football to 71941 which in turn would return the latest football
scores.

NOTE: @ keyword is not supported fully in sandbox mode, @ keyword can be only used dynamically in
production mode when whatever keyword message sent to your short code will be routed to your
callback URL.
 Page
27 (40)

Keyword will be created and you will see a new keyword on the notification management view.
 Page
28 (40)

3.7 Create Notification

When you have a Short Code number assigned and keyword created, you define a notification callback
URL for the application.

Click “Create Notification” button to start adding notification. Fill in mandatory data for the notification
(Type, Number, Keyword, Networks) and select either

1) Poll Notification

MO messages are polled by the application by means of the OMA

InboundMessageRetrieveAndDelete request – in this case the application is configured in the
Opaali Portal as operating in ‘Polling’ mode.

A callbackURL for application is configured with the default URL

http://www.w3.org/2005/08/addressing/none.

2) Push Notification

MO messages are pushed directly to the partner’s callback URL from Opaali portal.

Note: If your notification callbackURL port number is not standard 80/8080 or 443/8443 this
requires a new firewall rule to be setup on the Opaali Portal before notifications can be received.

Please send email to opaali-tuki@teliacompany.com and request firewall opening.

Press Save button to save the notification

 Page
29 (40)

You will get confirmation on the screen that notification has been started successfully for your number.
Notification management view will show the new notification below keywords.

Registration ID is available in the first column which can be used in polling method to fetch the
messages from the Messaging API with “InboundMessageRetrieveAndDelete” request.
 Page
30 (40)

Notification can be paused of stopped with the buttons in right side. Stopping notification will delete the
notification.

Please note when you delete notification and if you create it again, it will get a new registration ID.
 Page
31 (40)

3.9 API Console

API Console will be available in Opaali Portal for developers to test and verify API request and
responses. API console can be used with sandbox and production endpoints with OAUTHService,
Messaging and Payment services.

4 Sandbox

4.1 Sandbox Checklist

When you create a new application it will be in 'Sandbox' status by default. This will give you very
restrictive and limited access to Opaali Platform endpoints.

Sandbox enables testing applications without additional service fees or visibility to end customers, while
you are developing your application or service.

With sandbox mode you are not able to send MT messages to the real mobile phones or receive MO
messages from the real mobile phones and billing services are deactivated.
 Page
32 (40)

To get started with Sandbox testing, please take a look Opaali Portal Documentation and Guides page
from https://developer.opaali.telia.fi/resources and download the OMA Sandbox REST document to get
familiar with the Sandbox features.

There are pre-defined parameter values and canned responses which can be used in Sandbox mode to
develop the partner’s applications and services.

A Sandbox service is available for the following API’s in https://api.sonera.fi/sandbox:

 Payment Sandbox URI

 MT Messaging Sandbox URI
 MO Messaging Sandbox URI

There is no separate sandbox service for generating the access token from Authentication API. The one
obtained from the production server should be used.
 Page
33 (40)

5 Promote to Production

Click “Promote to Production” button in your Application profile page in Opaali Portal.

5.1 Application Checklist

Now that you’ve successfully tested your application, you can use this simple process to request a
promotion to production.

You will be notified by email when the Administrator has made a decision. If successful, the status of
your application will be shown as ‘Production’.

To start the process click Continue.

5.2 Partner Profile

Fill in the mandatory support and billing information for the Partner (this includes support email / phone
number and address information). Please make sure your details are correct and up-to-date. These
details will be only shown to the Opaali Support team.
 Page
34 (40)

To Continue the process click Continue.

 Page
35 (40)

5.3 Application Profile

Application name cannot be changed or application cannot be deleted after it was created but you can
change the application description here if needed.
 Page
36 (40)

5.4 Application Bundle Description

Next you need to select what type of commercial business service you need by selecting Application
Bundle type:

1) Select application bundle “Bulk” or “Receive Only No Charge if your contract with Telia is
“Mobile Messaging”.

2) Select application bundle “Receive Only with charging”, “QR with charging / No Charging”, “Push
with charging / No Charging or “Send Only No Charge” ” if your contract with Telia is
“Messaging Interface”.

3) Select “Mobile Payment” if your contract with Telia is “Mobile Charger”.

Note: The Premium Messaging Service supports two types of service

1) Query & Response Messaging, where only one MT Message is allowed for every MO
request made by the subscriber (QR).

2) Push Messaging, where the subscriber may request (and terminate) an ongoing service
where the application may send multiple MT messages (PUSH).

 Next select ‘Charge On Delivery’ attribute YES / NO.

* Charge On Delivery attribute value means the initial phase when the charging CDR ticket is
generated for charging and invoicing system in Telia Network.

Charge On Delivery value NO = initial submission phase of MT message, deliverystatus

‘DeliveredToNetwork’
Charge On Delivery value YES = MT message is actually delivered to the terminal with the
deliverystatus “DeliveredToTerminal”.

 Please complete the Request Change to Bundle section, if the selected Application Bundle
does not meet your requirements. If the Application Bundle Description includes a specific TPS,
you may wish to request a higher TPS. Default is 10 TPS.

Note: “Request change to bundle” can be filled if you would need some other configurations for
your application, except default configuration.
 Page
37 (40)

Ex. Here you could request change to charge limit, destination address blacklist, maximum
transactions/revenue per interval, or if you would like to restrict some feature, ex. setting amount
split transaction for payment transactions to FALSE. Usually by default you don’t need to request
any specific changes.

Click the checkbox “Request Change to the Bundle” and enter your requested changed to the
opened description field.

 For Payment applications only (Mobile Charger) select Application restriction class from
drop box menu:

Service Group I – Services of General Interest

Service Group II – Transaction Services
Service Group III – Entertainment
Service Group IV – Adult Services

 Update Application Attributes if necessary.

Attributes that can be updated for your application are:

 Validity Timeout (0 -4320)

 Receive-Only price and currency
 Query and Response balance check and currency
 Push balance check and currency
 VAT percentage (0 -24).

Validity time for MT messages can be configured (in minutes 0 - 4320 ) can be set.
 Page
38 (40)

 Receive-Only Price – the amount to charge to the subscriber for an MO message, for an MO
message Receive Only service type of Application

 Receive-Only Currency – select “Euro” from the drop-down list

 QR Balance Check – the minimum credit a prepaid subscriber must have, to allow a
Query/Response service to proceed

 QR Balance Check Currency – select “Euro”from the drop-down list

 Page
39 (40)

 Push Balance Check – the minimum credit a prepaid subscriber must have, to allow a Push
service to proceed

 Push Balance Check Currency – select “Euro” from the drop-down list

 VAT Percentage – VAT % to be applied to the service. This is mandatory field to fill, do not leave
it empty.

Setting the VAT Percentage to a specific value other than the standard VAT amount will require
manual Promote-to-Production.

Please confirm that you would like to submit your application promotion request with clicking
“Continue” button

5.5 Production mode

Now you have successfully completed the promote-to-production request process. You will get an email
confirmation that your application request for promoting to production has been initiated and will be
reviewed by Telia Opaali Support team. You'll be notified by email when a decision has been made.

When your application is approved to production, status will be “Enabled – Production”. Meanwhile
application status is “Pending” until approved for production.

Production endpoints (old) are enabled in https://api.soneri.fi/production

Production endpoints (new) are enabled in https://api.opaali.telia.fi/production

Sandbox endpoints are still also available for testing purposes.

For Mobile messaging services, Messaging Interface services and Mobile Charger services billing and
invoicing are activated in Telia billing and invoicing network when your application is promoted to
production.

For Messaging Interface services please see following note during CGW migration phase:

When you want to switch your existing Short code numbers from old CGW platform to the Opaali
platform for MO traffic, please send email to opaali-tuki@teliacompany.com and agree suitable time
schedule for switchover
 Page
40 (40)

5.6 Developer Resources

Technical documentation of Opaali portal can be found from https://developer.opaali.telia.fi/resources

In case you have a question or you need more help, please contact opaali-tuki@teliacompany.com or
post a thread to forum https://developer.opaali.telia.fi/forum

Interesting reading from the Opaali Blog – API migration paths from CGW to Opaali by JPLa:
https://miikos.github.io/Opaali/

Kind regards,
Opaali- support team / Telia
E-mail: opaali-tuki@teliacompany.com