Notifications setup

Viber

This document provides all required steps to create and link a new Viber bot account to the Viber bot web API project.

Create Viber account

Figure 1: Log in Viber admin panel

Figure 2: Create Viber bot account

Figure 3: Viber bot account created - copy auth token

Set Viber Auth token in Upkip Administration

Open Upkip Administration.

Select menu Notification servers/Media Types. Paste the Viber authentication token in the field Viber Authentication Token and click Update.

Figure 4: Upkip Administration-Notification server-Media Types-Viber

Set this key to the Viber:AuthenticationToken setting in the ViberBot web app project.

In this case, the deep link URL till be:

viber://pa/info?uri=icpenotifier

Create QR Code

Last but not least we must generate a QR code leading to the Viber deep link URL so the users can be redirected to the bot when clicking on the QR Code on the mobile phone.

Navigate to a QR Code generator tool, e.g. https://www.qr-code-generator.com/

SMS

This section provides instructions on how to create a Twilio account and Messaging service and filling required parameters in Notification servers/Media Types.

Create Twilio account

  1. Navigate to Twilio site - https://www.twilio.com/try-twilio
  2. Create your free Twilio account by filling required fields

Figure 1: CREATE TWILIO ACCOUNT

  1. The verification form is shown with button the Verify. Click Verity and follow the instructions.
    • The verification email has sent.
  2. Open the received email with the subject “Verify your email”. Click on the link Confirm Your Email.
  3. Log in by email and password of created Twilio account. Verify by following the instructions.
    • Verify Email has passed

Figure 2: Twilio free account - enter and verify your phone

  1. The user is prompted to enter the phone number.
    • Verification code is sent as SMS
  2. Enter the code and finish verification

Configure in Upkip Administration Twilio account SID and Token

Get the Twilio account SID and Token

  1. Log in to Twilio with your account
    • Twilio account dashboard is opened

Figure 3: Twilio account SID and AUTH TOKEN

  1. Copy the Account SID and Auth Token.

Configure Upkip SMS Media Type SID and Token

  1. Log with user administrator in Upkip Administration
  2. Select menu Notification servers/Media Types
    • The fields for SMS have to be configured.

Figure 4: Notification server - Media Types

Figure 5: Notification server - SMS Media Type

  1. Copy from Twilio account SID (1) and paste in the Upkip String identifier (SID) (1) field
  2. Copy from Twilio account Auth Token (2) and paste in the Upkip Token (2) field.

Configure in Upkip Administration Twilio phone number

Get a Twilio phone number

  1. Go back to your Twilio account dashboard and Step1: Get a Twilio trial phone number.

Figure 5: Twilio account - get a phone number

  1. Click the button Get a trial phone number

Figure 6: Twilio account - choose a phone number

  1. Click Choose this Number
    • You get the number

Figure 7: Twilio account - a phone number received

Configure Upkip Administration SMS Media Type phone number

  1. Go back to Upkip Administration Notification Server/Media Type SMS
  2. Copy the received number from Twilio (e.g. +17745385034)
  3. Paste the number in the Sender phone field (3)
    • Sender phone is configured.

Configure in Upkip Administration Twilio Messaging Service SID

Get a Twilio messaging service SID

  1. Go back to your Twilio account dashboard
  2. Go to Twilio documentation Messaging Services - https://www.twilio.com/docs/messaging/services

There is described how to configure messaging services. This is possible through Console or using the REST API.

Figure 9: Twilio Help - Send a message with a messaging service

  1. Receive the messaging service ID (SID) by using some of the given examples.
  2. From the Twilio account dashboard select menu Programmable messaging

Figure 10: Twilio account dashboard - Select Programmable messaging

  1. Programable Messaging Dashboard is opened.

Figure 11: Twilio account - Programmable messaging dashboard

  1. Click on Messaging service
    • Messaging Services page is opened. Click button Create Messaging Service.

Figure 12: Twilio account - Messaging services

  1. Create messaging service by filling in the service name and messaging service use case and clicking Create.

Figure 13: Twilio account - Create Messaging services

  1. Follow the wizard to finish Message service creating.
  2. Select again menu Messaging services and open Messaging Services page.
    • Messaging service is created and visible by Name and SID.

Figure 14: Twilio account - Created Messaging service with Name and SID

  1. Copy the Messaging service SID

Configure Upkip Messaging service SID

  1. Go back to Upkip Administration Notification Server/Media Type SMS
  2. Type in the field Use Message Service: True
  3. Type in the field Message Service SID the SID of created Messaging service.
  4. Click Update to update/save the SMS Media Type data.

Email

The Upkip platform uses its SMTP server by default.

In the Upkip Administration menu Notification servers/Media Types option Use Upkip Email Service is checked by default.

There is no problem if the client wants to use another SMTP server (own or third party). You only need to uncheck the option Use Upkip Email Service and enter the appropriate parameters in the Upkip Administration/Notification servers/Media Types.

Also SendGrid can be used as a service provided by the SMTP server, for which we give him detailed instructions.

Create sender identity

Before sending an email, you’ll need to create a sender identity. There are two ways to do this, but SendGrid recommends creating a Single Sender to get set up quickly.

  1. Open send grid resource in Azure
  2. Click on Manage
  3. If requested, confirm the assigned e-mail address. SendGrid Account Manage link and Confirmation link should be opened with the same browser
  4. Proceed to Create a Single Sender by following the site’s instructions
    • From Name, Company Address, and Nickname: Upkip <customer_identifier>
    • From Email Address and Reply To: upkip@icb.bg
    • City: Sofia
    • Country: Bulgaria Figure 1: AAD - Create a Sender
  5. Confirm the email
  6. Configured senders can be found here: https://app.sendgrid.com/settings/sender_auth/senders

API Key setup

Next, a new API Key should be setup:

Fill in Upkip Administration Email fields

Open Upkip Administration/Notification servers/Media Types. Fill in Email section configuration parameters.

Figure 2 : Upkip Administration - Notification servers - Media type Email

IFTTT

IFTTT (If This Then That) defines a clear and concise protocol that your service’s API will implement. Each trigger and action for your service will map 1-to-1 to an API endpoint on your service built specifically for IFTTT. Trigger endpoints will be event streams that IFTTT will poll for new data. Conversely, action endpoints will be writable endpoints that IFTTT will send data to. For services that use OAuth, IFTTT is fully compatible with a couple of the common flavors of OAuth 2.0.

IFTTT is a free platform that helps you do more with all your apps and devices. We will use IFTTT to send notifications to our users when some trigger occurs. We will have to integrate our IFTTT Api with the IFTTT system. IFTTT will have access to our API’s to poll the data they require.

IFTTT API

Creating Web App

  1. Go to the Azure Portal and using the Dashboard you can find and create a Web App resource.
  2. On creation page you can connect the Web App to the already existing Application Insights that you created earlier.

Setup OAuth 2.0 Authentication

To set up Azure OAuth 2.0 Authentication you will need to create 2 AAD (Azure Active Directory) Applications. One will represent the IFTTT API, and the other will have privileges to access the IFTTT API and will be used to obtain access tokens with which you will authenticate yourself in front of the IFTTT API.

IFTTT API AAD Application

  1. Open the Azure Portal and go to Azure Active Directory.
  2. Open App registrations and click on “New registration”.
  3. On creation for “Redirect URI” put the URL of your IFTTT Web App + “/.auth/login/aad/callback”. Example: “https://osohw-test-iftttapi.azurewebsites.net/.auth/login/aad/callback”.
  4. After it’s created go to “Manifest” and add “identifierUris” which is the URL of your IFTTT Web App.

IFTTTApiManifest

Figure 1: IFTTT Identifier URL

IFTTT App AAD Application

  1. Open the Azure Portal and go to Azure Active Directory.
  2. Open App registrations and click on “New registration”.
  3. On creation for “Redirect URI” put the URL of your IFTTT Web App.
  4. After it’s created go to “Certificates & secrets” and create a new “Client Secret”, save it somewhere it will be required for you to get an access token.
  5. Go to “API permissions” and add permission to access the IFTTT Api AAD Application.

IFTTTApiPermissions

Figure 2: IFTTT API Permissions

Setup application settings

Now it’s time to set up the appsettings.json of the IFTTT API.

  1. Open Visual Studio 2019 and open the solution.
  2. Find the “IFTTTAPI” assembly and there under appsettings.json you will see appsettings.Development.json.

C:\Users\yoan.stavrev\AppData\Local\Microsoft\Windows\INetCache\Content.Word\SmartGridAppSettings.png

Figure 3: IFTTT API Settings

  1. Open the appsettings.Development.json and edit the following variables:

https://login.microsoftonline.com/{your tenant id here}

https://login.microsoftonline.com/{your tenant id here}

For the Azure Web Application to be able to read the correct appsettings.json you now need to go the the resource Application Settings and a new one. Since we are using the appsettings.Development.json you will need to add an environment variable with the value “Development”.C:\Users\yoan.stavrev\AppData\Local\Microsoft\Windows\INetCache\Content.Word\Development.png

Figure 4: IFTTT API Environment Variable

IFTTT Test User

IFTTT will need you to provide a test user through which they can test your service on publishing.

You can go to the Azure Active Directory and under “Manage” section click on “Users”. From there you can add a new user by clicking on the “New user” button.

After that go to Azure Active Directory and under “Manage” section open “Enterprise applications”. In the list of applications find your IFTTT App AAD Application and open it.

Then under “Manage” you will see “Users and groups” open it. Click on “Add user” and select the test user you created.Save your user information somewhere because you will need it later.

IFTTT Service

IFTTT is a free platform that helps you do more with all your apps and devices. We will use IFTTT to send notifications to our users when some trigger occurs. We will have to integrate our IFTTT Api with the IFTTT system. IFTTT will have access to our APIs to poll the data they require.

API Section

General tab

IFTTTplatform

Figure 5: IFTTT API General tab

In the general tab, there are 2 fields. In “IFTTT API URL” you need to input the URL of the Management Web App. The second field “Service Key” is something you will need later so make sure to save it somewhere. Copy the "Service Key".

Fill in Upkip Administration IFTTT fields

Open Upkip Administration.

Select menu Notification servers/Media Types. Paste the Service Key in the field IFTTT Service Key (1). Figure 6 : Upkip Administration - Notification servers - Media types - IFTTT fields

Go to IFTTT platform, Realtime API documentation https://platform.ifttt.com/docs/api_reference#realtime-api.

Copy the Realtime endpoint "https://realtime.ifttt.com/v1/notifications" and paste into the field IFTTT RealTime EndPoint (2). Click Update to save Media Types settings.

Authentication tab

Now let’s move on to the “Authentication” tab. IFTTTauthentication

Figure 6: IFTTT API Authentication tab

In the authentication tab select the option “My API has users with expiring OAuth2 access tokens and uses refresh tokens”. After you do that some new fields will show up where you will need to input the correct data so IFTTT can authenticate itself in front of our APIs.

IFTTTauth1

Figure 7: IFTTT Authentication fields

For the “Authorization URL” and “Token URL” you need to go to your Azure Portal and open Azure Active Directory.

Under the Manage section open “App registrations (Preview)” and from there you should open “Endpoints” which can be found on top of the blade. You are looking for “OAuth 2.0 Token Endpoint (v2)” and “OAUTH 2.0 Authorization Endpoint (v2)”.

IFTTTendpointsv2

Figure 8: AAD Authorization endpoints

Before you paste them into the fields you need to make small editions to the Authorization URL. At the end of your Authorization URL you need to add the following:

?scope={URL of your Management Web App}/user\_impersonation offline\_access

Example Authorization URL: https://login.microsoftonline.com/d4f23865-c0bd-4784-8c5c-165750372dc3/oauth2/v2.0/authorize?scope=https://iotwh-test-iftttapi.azurewebsites.net/user_impersonation offline_access

Redirect URL after authentication completes:

 https://ifttt.com/channels/{{service_id}}/authorize.

This is what your redirect URL should look like, and instead of {service_id} put in the actual IFTTT service ID you chose earlier.

In the Demo account fields, you need to input the account information of the IFTTT test user you created earlier in the Azure Portal. Put in the Account Login and Password. The “Demo account notes” can be anything. You are ready with the Authentication tab, make sure to save it.

Triggers tab

You will create a trigger for Control Mode Change. When you open the triggers tab you should see a “New trigger” button, click it.

IFTTTtriggername

Figure 9: IFTTT Triggers

Make your trigger name section look the same as the image and click Save. After you save more fields will show up. Firstly you will create a new Trigger Field.

IFTTTtriggerfields

Figure 10: IFTTT Trigger Fields

After creating a trigger field you will have to set up it.

IFTTTtriggerfield1

Figure 11: IFTTT Trigger DeviceId field

IFTTTtriggerfield2

Figure 12: IFTTT Trigger DeviceId field

In the “API endpoint to populate the trigger field” you need to input:

{your management app url}/ifttt/v1/triggers/control_mode/fields/device_id/options

Now you are done with the “Trigger Fields” and next up is “Verbiage” but before you setup the “Verbiage” section you need to setup the “Ingredients” section so scroll past “Verbiage” for now. In “Ingredients” section click to add a new ingredient. And setup it exactly the same as the image below.

IFTTTingredients

Figure 13: IFTTT Triggers Ingredients

When you are done make sure to save this ingredient. Now you can go back to the “Verbiage” section and make your Verbiage field look exactly like the image below.

IFTTTverbiage

Figure 14: IFTTT trigger verbiage

Make sure to save your verbiage section. The last thing in the Triggers tab is to setup our Applet templates. The 3 notification types we will use are “Mobile push notification”, “Short message” and “Long post”.

IFTTTshortmsg

Figure 15: IFTTT short message

IFTTTmobilepush

Figure 16: IFTTT mobile push

IFTTTlongpost

Figure 17: IFTTT long post

Make sure to save everything and you are done in the Triggers tab.

Actions tab

Now it’s time to set up the Actions tab. You will first create the “heater_on” action. Open it and click on the “New action” button. Input “Name”, “Description” and “Endpoint” for your action.

iftttactionendpoint

Figure 18: IFTTT action endpoint

The “Endpoint” should look like the image above. For now, leave the “Verbiage” field empty and click save. After you save the action an “Action Fields” section will appear. Click on “Add action field” and make it look like the picture below.

IFTTTactionfields

Figure 19: IFTTT action fields

iftttactionfields2

Figure 20: IFTTT action fields

Make sure to save the action field you created. Now go back to the “Verbiage” section and make it look like the image below.

iftttactionverbiage

Figure 21: IFTTT action verbiage

Following the same same pattern just with the proper URLs, you can make other actions. Make sure everything is saved and you are ready with the actions tab.

IFTTT Integration testing

Before you begin the integration testing, you should go back and fill the config settings in all your resources that depend on the IFTTT Service. To test if the integration was successful you can go to the IFTTT platform and under the API tab you can run “Endpoint tests” and “Authentication tests”.

Direct link: https://platform.ifttt.com/services/{Your username}/api

Microsoft Teams

This section provides instructions on how to configure Microsoft Teams notifications. To configure the notification to Microsoft Teams go through steps:

Microsoft Teams

Install Microsoft Teams

Figure 1: Join or create a team

Note: If you have created a new team, it will automatically create a General channel for you, otherwise you will see the channel/’s that are part of your team.

Figure 2: Get link to channel

Figure 3: Copy link to the channel

Invite User to the Team

To be able to send messages to some team, you need to create an internal system user only for the purposes of the Upkip. Then invite this user to your team.

Right-click on the team name and select menu Manage team

Figure 4: Open manage team

Click Add member and type the user in the search bar

Figure 5: Manage team - open add member

Figure 6: Add Upkip Notifier member to the team

Continue adding other members to the team.

To configure Notification to Microsoft Teams channel