Opaali Portal Quick guide Company information Telia Finland Oyj Teollisuuskatu 15, 00510 HELSINKI, FI Registered office: Helsinki Business ID 1475607-9, VAT No. FI14756079 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
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.
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.
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).
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:
Example of CountsPerMessageType report: Page 7 (40)
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.
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.
In the next page fill your email address and text from security box and click link Reset Password. Page 10 (40)
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.
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
13 (40) 2.2 Mobile Messaging Application types: Bulk Receive-Only No Charge
14 (40)
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
16 (40)
17 (40)
18 (40) 2.4 Mobile Charger Application type: Mobile Payment
19 (40)
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.
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.
22 (40)
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.
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.
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.
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.
Keyword will be created and you will see a new keyword on the notification management view. Page 27 (40)
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
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.
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.
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.
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.
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.
To Continue the process click Continue. Page 34 (40)
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.
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.
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.
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
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
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