Notification Service – Samples for v3.x¶
Sending E-Mails with Simple Content¶
Use the following endpoint to send a simple e-mail:
POST /api/notification/v3/publisher/messages
Sample Request payload:
{
"body":
{
"message":"message"
},
"recipientsTo":"mail@provider.com;mail@provider-B.com",
"from":"name",
"subject":"subject"
}
The recipientTo field accepts multiple recipients separated by semicolons.
Creating E-Mail Templates¶
For sending e-mails using templates, the recipients, the e-mail content and a communication category have to be created first.
Creating a Recipient¶
A recipient is registered using the following endpoint:
POST /api/notification/v3/recipient/
For providing valid input for the addresstypeid, refer to the /recipient/addresstype of the Notification Service API Specification.
Sample Request:
{
"recipientname" : "name",
"recipientdetail" : [ {
"address" : "mail@provider.com",
"addresstypeid" : 2
},
{
"address" : "mail@provider-B.com",
"addresstypeid" : 1
} ]
}
Sample Response:
806
The response contains the recipientID of the created recipient. Store this information as reference for the following API calls.
Getting recipient details¶
Use the following endpoint get a recipient details based on the recipientID:
GET /api/notification/v3/recipient/{id}
Sample Response:
{
"recipientid": 124816,
"recipientname": "Example recipient",
"isactive": "Y",
"recipientdetail": [
{
"address": "example@siemens.com",
"addresstypeid": 2
}
]
}
Here, isactive is the property used to show status (active/inactive) of the recipient. However, currently the value is Y (active) by default and it is not possible to change this property.
Creating a Template for E-Mail Content¶
The template for e-mail content is created using the following endpoint:
POST /api/notification/v3/template/
Refer to the API for this endpoint for detailed information on the request structure and creating placeholders. For providing valid input for the commChannelId, refer to the /communicationchannel/ of the Notification Service API Specification.
Sample template:
<html xmlns:th="http://www.thymeleaf.org" th:inline="text" th:remove="tag">
Hello [[${name}]]. Please click the URL for more details : <a th:href="${actualurl}">[[${url}]]</a>
</html>
In this template, the name of the recipient and the included URL are the defined placeholders.
Sample response:
{
"templatesetId": 111,
"templatesetName": "TestTemplateForEmail",
"templateList": [
{
"templateId": 412,
"commChannelId": 1,
"commChannelName": "Email"
}
]
}
Store the values of templatesetId and templateId as reference for the following API calls.
Creating a Communication Category for E-mail¶
A communication category is created using the following endpoint:
POST /api/notification/v3/communicationcategories/
In the following sample request, the recipientID, templatesetId and templateId created in the previous steps are reused.
Sample Request:
{
"msgCategoryName": "category name",
"subject": "subject",
"priority":1,
"from":"name",
"recipients":[
{
"recipientId":807,
"position":"TO"
}
],
"templates":[
{
"templateId":412,
"templatesetId":111,
"commChannelName":"Email"
}
]
}
Sample Response:
642
The response contains the categoryID of the generated communication category. Store this information as reference for the following API call.
Sending E-Mails using a Template¶
For sending e-mails using a template, use the following endpoint:
POST /api/notification/v3/publisher/messages
The request must provide the categoryId and define values for the placeholders of the template for the e-mail content. Default recipients for a communication category are defined during its creation, but the recipientTo field accepts additional recipients separated by semicolons.
Sample Request:
{
"body" : {
"placeholderkey1" : "value1",
"placeholderkey2" : "value2",
},
"recipientsTo" : "mail@provider.com",
"messageCategoryId" :642
}
Broadcasting E-Mails¶
Use the following endpoint to broadcast unencrypted e-mails to all users of a tenant including subtenant users:
POST /api/notification/v3/broadcastEmails?broadcastType=all
The recipients of broadcasted e-mails are concealed using Bcc.
Sample request for broadcasting a simple e-mail:
{
"body":
{
"message":"Simple broadcast Email content"
},
"from":"name",
"subject":"subject"
"priority": 3
}
Sample request for broadcasting an e-mail using a template:
{
"body":
{
"placeholderkey1" : "value1",
"placeholderkey2" : "value2",
},
"messageCategoryId" :642,
"subject":"subject"
}
Change the broadcastType parameter in the request for broadcasting e-mails to other user groups as explained in the API Specification.
Sending SMS Notifications using a Template¶
The Notification Service provides the functionality to send SMS notifications to mobile devices. For sending SMS notifications using templates, the recipients, the message content and a communication category have to be created first.
Creating a recipient with SMS notification details¶
A recipient is registered using the following endpoint:
POST /api/notification/v3/recipient/
For providing valid input for the addresstypeid, refer to the /recipient/addresstype of the Notification Service API Specification.
Note
Due to regulatory restrictions, sending SMS using the Industrial IoT notification service is suspended if at least one of the target recipients is from the India region (country code +91). Recipients from the India region shall use other notification options (e-mail or push notification).
Sample Request:
{
"recipientname" : "User",
"recipientdetail" : [ {
"address" : "+411234567890",
"addresstypeid" : 4
},
{
"address" : "+497777777777",
"addresstypeid" : 5
} ]
}
Sample Response:
100795
Creating a Template for SMS Notification Content¶
The template for SMS content is created using the following endpoint:
POST /api/notification/v3/template/
Refer to the API for this endpoint for detailed information on the request structure and creating placeholders. For providing valid input for the commChannelId, refer to the /communicationchannel/ of the Notification Service API Specification.
Sample template:
<html xmlns:th="http://www.thymeleaf.org" th:inline="text" th:remove="tag">
Dear [[${name}]], Welcome to SMS service feature of Communication Service Mindsphere.(Hardware Activation)
</html>
In this template, the name of the recipient is the defined placeholder. The above html is saved as SMS.html and added to request as templateFiles parameter.
Sample Request:
{
"templateParam": [{
"paramName": "Name",
"defaultValue": "MindSphere User",
"placeHolderName": "name",
"paramTypeId": 4
}],
"templatesetName": "TemplateForSMS",
"templateChannelAndFile": [{
"communicationChannel": 2,
"fileName": "SMS.html"
}]
}
Sample Response:
{
"templatesetId": 19489,
"templatesetName": "TemplateForSMS",
"templateList": [
{
"templateId": 22578,
"commChannelId": 2,
"commChannelName": "SMS"
}
]
}
Store the values of templatesetId and templateId as reference for the following API calls.
Creating a Communication Category for SMS¶
A communication category is created using the following endpoint:
POST /api/notification/v3/communicationcategories/
In the following sample request, the recipientId, templatesetId and templateId created in the previous steps are re-used. A subject for the SMS notification must be provided in the respective field of the request.
Sample Request:
{
"msgCategoryName" : "Category for SMS",
"recipients" : [ {
"recipientId" : 100795
} ],
"templates" : [ {
"templateId" : 22578,
"commChannelName" : "SMS",
"templatesetId" : 19489
} ]
}
Sample Response:
29675
The response contains the categoryId of the generated communication category. Store this information as reference for the following API call.
Triggering the SMS Notification¶
For triggering the prepared notification, use the following endpoint:
POST /api/notification/v3/publisher/messages
The request must provide the categoryId and define values for the placeholders of the template for the SMS content. Default recipients for a communication category are defined during its creation.
Sample Request:
{
"body": {
"name": "MDSP User"
},
"messageCategoryId": 29675
}
Sending Push Notifications using a Template¶
The Notification Service provides the functionality to send push notifications to mobile devices. For sending push notifications using templates, the recipients, the content and a communication category have to be created first.
Creating a recipient with push notification details¶
A recipient is registered using the following endpoint:
POST /api/notification/v3/recipient/
For providing valid input for the addresstypeid, refer to the /recipient/addresstype of the Notification Service API Specification. The following information must be provided in the address field of the request:
appId: Unique device and application specific ID issued by the GCM connection servers, which allows the client app to receive messages.serverApiKey: Unique application specific key of an application, which is stored on the app server and provides authorized access to Google servicesapplicationName: Name of the application, that sends the notifications
Sample Request:
{
"recipientname" : "PushNotificationTest",
"recipientdetail" : [{
"address" : {
"appId":"id",
"serverApiKey":"apiKey",
"applicationName":"app name"
},
"addresstypeid" : 7
} ]
}
Sample Response:
807
The response contains the recipientID of the created recipient. Store this information as reference for the following API calls.
Creating a Template for Push Notification Content¶
The template for push notification content is created using the following endpoint:
POST /api/notification/v3/template/
Refer to the API for this endpoint for detailed information on the request structure and creating placeholders. For providing valid input for the commChannelId, refer to the /communicationchannel/ of the Notification Service API Specification.
Sample template:
<html xmlns:th="http://www.thymeleaf.org" th:inline="text" th:remove="tag">
Hello [[${name}]]. Please click the URL for more details : <a th:href="${actualurl}">[[${url}]]</a>
</html>
In this template, the name of the recipient and the included URL are the defined placeholders.
Sample response:
{
"templatesetId": 436,
"templatesetName": "TestTemplateForPushNotification12",
"templateList": [
{
"templateId": 468,
"commChannelId": 3,
"commChannelName": "Push Notification"
}
]
}
Store the values of templatesetId and templateId as reference for the following API calls.
Creating a Communication Category for Push Notification¶
A communication category is created using the following endpoint:
POST /api/notification/v3/communicationcategories/
In the following sample request, the recipientID, templatesetId and templateId created in the previous steps are reused. A subject for the push notification must be provided in the respective field of the request.
Sample Request:
{
"msgCategoryName": "category name",
"subject": "subject",
"priority":1,
"from":"name",
"recipients":[
{
"recipientId":806,
"position":"TO"
}
] ,
"templates":[
{
"templateId":468,
"templatesetId":436,
"commChannelName":"Push Notification"
}
]
}
Sample Response:
642
The response contains the categoryID of the generated communication category. Store this information as reference for the following API call.
Triggering the Push Notification¶
For triggering the prepared notification, use the following endpoint:
POST /api/notification/v3/publisher/messages
The request must provide the categoryId and define values for the placeholders of the template for the push content. Default recipients for a communication category are defined during its creation.
Sample Request:
{
"body" :
{
"placeholderkey1" : "value1",
"placeholderkey2" : "value2",
},
"messageCategoryId":642
}
Removing Blocked E-Mail Addresses from the Blacklist¶
Tenant admins can use the following endpoint:
DELETE /api/notification/v3/communicationcategories/bouncedEmailIds
Sample Request:
{
"emailList" : ["mail@provider.com"]
}
Hint
Use the following endpoint to list all blacklisted e-mail addresses:
GET /api/notification/v3/communicationcategories/bouncedEmailIds
Note
IoT Value Plan tenants will not be able to access the blacklisted endpoints directly. These tenants can request for the blacklisted emails using Support Request.