mirror of
https://github.com/zitadel/zitadel.git
synced 2024-12-04 23:45:07 +00:00
docs: notification provider docs (#8626)
# Which Problems Are Solved There is no documentation on how to use the HTTP providers for SMS and Email. # How the Problems Are Solved Add documentation and correct the tags in the proto files to correctly group the calls for the API docs. # Additional Changes None # Additional Context None --------- Co-authored-by: Fabi <fabienne@zitadel.com>
This commit is contained in:
Stefan Benz
GitHub
parent
68e78ff7c0
commit
c297a62c4f
74
docs/docs/guides/manage/customize/notifications.md
Normal file
74
docs/docs/guides/manage/customize/notifications.md
Normal file
@ -0,0 +1,74 @@
|
||||
---
|
||||
title: SMS, SMTP and HTTP Provider for Notifications
|
||||
---
|
||||
|
||||
All Notifications send as SMS and Email are customizable as that you can define your own providers,
|
||||
which then send the notifications out. These providers can also be defined as an HTTP type,
|
||||
and the text and content, which is used to send the SMS's and Emails will get send to a Webhook as JSON.
|
||||
|
||||
With this everything can be customized or even custom logic can be implemented to use a not yet supported provider by ZITADEL.
|
||||
|
||||
## How it works
|
||||
|
||||
There is a default provider configured in ZITADEL Cloud, both for SMS's and Emails, but this default providers can be changed through the respective API's.
|
||||
|
||||
This API's are provided on an instance level:
|
||||
- [SMS Providers](/apis/resources/admin/sms-provider)
|
||||
- [Email Providers](/apis/resources/admin/email-provider)
|
||||
|
||||
To use a non-default provider just add, and then activate. There can only be 1 provider be activated at the same time.
|
||||
|
||||
## Resulting messages
|
||||
|
||||
In case of the Twilio and SMTP providers, the messages will be sent as before, in case of the HTTP providers the content of the messages is the same but as a HTTP call.
|
||||
|
||||
Here an example of the body of an Email sent via HTTP provider:
|
||||
```json
|
||||
{
|
||||
"contextInfo": {
|
||||
"eventType": "user.human.initialization.code.added",
|
||||
"provider": {
|
||||
"id": "285181292935381355",
|
||||
"description": "test"
|
||||
},
|
||||
"recipientEmailAddress": "example@zitadel.com"
|
||||
},
|
||||
"templateData": {
|
||||
"title": "Zitadel - Initialize User",
|
||||
"preHeader": "Initialize User",
|
||||
"subject": "Initialize User",
|
||||
"greeting": "Hello GivenName FamilyName,",
|
||||
"text": "This user was created in Zitadel. Use the username Username to login. Please click the button below to finish the initialization process. (Code 0M53RF) If you didn't ask for this mail, please ignore it.",
|
||||
"url": "http://example.zitadel.com/ui/login/user/init?authRequestID=\u0026code=0M53RF\u0026loginname=Username\u0026orgID=275353657317327214\u0026passwordset=false\u0026userID=285181014567813483",
|
||||
"buttonText": "Finish initialization",
|
||||
"primaryColor": "#5469d4",
|
||||
"backgroundColor": "#fafafa",
|
||||
"fontColor": "#000000",
|
||||
"fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Lato, Arial, Helvetica, sans-serif",
|
||||
"footerText": "InitCode.Footer"
|
||||
},
|
||||
"args": {
|
||||
"changeDate": "2024-09-16T10:58:50.73237+02:00",
|
||||
"code": "0M53RF",
|
||||
"creationDate": "2024-09-16T10:58:50.73237+02:00",
|
||||
"displayName": "GivenName FamilyName",
|
||||
"firstName": "GivenName",
|
||||
"lastEmail": "example@zitadel.com",
|
||||
"lastName": "FamilyName",
|
||||
"lastPhone": "+41791234567",
|
||||
"loginNames": [
|
||||
"Username"
|
||||
],
|
||||
"nickName": "",
|
||||
"preferredLoginName": "Username",
|
||||
"userName": "Username",
|
||||
"verifiedEmail": "example@zitadel.com",
|
||||
"verifiedPhone": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There are 3 elements to this message:
|
||||
- contextInfo, with information on why this message is sent like the Event, which Email or SMS provider is used and which recipient should receive this message
|
||||
- templateData, with all texts and format information which can be used with a template to produce the desired message
|
||||
- args, with the information provided to the user which can be used in the message to customize
|
||||
@ -158,6 +158,7 @@ module.exports = {
|
||||
"guides/manage/customize/texts",
|
||||
"guides/manage/customize/behavior",
|
||||
"guides/manage/customize/restrictions",
|
||||
"guides/manage/customize/notifications",
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@ -437,7 +437,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -457,7 +457,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -478,7 +478,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -499,7 +499,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -520,7 +520,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -541,7 +541,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP Provider";
|
||||
tags: "SMTP Configs";
|
||||
summary: "Activate SMTP Provider";
|
||||
description: "Activate an SMTP provider."
|
||||
deprecated: true;
|
||||
@ -564,7 +564,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP Provider";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -584,7 +584,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -605,7 +605,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP Provider";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -626,7 +626,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP Provider";
|
||||
tags: "SMTP Configs";
|
||||
deprecated: true;
|
||||
};
|
||||
}
|
||||
@ -663,7 +663,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email providers";
|
||||
tags: "Email Provider";
|
||||
summary: "List Email providers";
|
||||
description: "Returns a list of Email providers."
|
||||
};
|
||||
@ -679,7 +679,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email";
|
||||
tags: "Email Provider";
|
||||
summary: "Get active Email provider";
|
||||
description: "Returns the active Email provider from the system. This is used to send E-Mails to the users."
|
||||
};
|
||||
@ -695,7 +695,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email";
|
||||
tags: "Email Provider";
|
||||
summary: "Get Email provider by its id";
|
||||
description: "Get a specific Email provider by its ID.";
|
||||
};
|
||||
@ -712,7 +712,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email";
|
||||
tags: "Email Provider";
|
||||
summary: "Add SMTP Email provider";
|
||||
description: "Add a new SMTP Email provider if nothing is set yet."
|
||||
};
|
||||
@ -729,7 +729,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email";
|
||||
tags: "Email Provider";
|
||||
summary: "Update SMTP Email provider";
|
||||
description: "Update the SMTP Email provider, be aware that this will be activated as soon as it is saved. So the users will get notifications from the newly configured SMTP."
|
||||
};
|
||||
@ -746,7 +746,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email";
|
||||
tags: "Email Provider";
|
||||
summary: "Add HTTP Email provider";
|
||||
description: "Add a new HTTP Email provider if nothing is set yet."
|
||||
};
|
||||
@ -763,7 +763,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email";
|
||||
tags: "Email Provider";
|
||||
summary: "Update HTTP Email provider";
|
||||
description: "Update the HTTP Email provider, be aware that this will be activated as soon as it is saved. So the users will get notifications from the newly configured HTTP."
|
||||
};
|
||||
@ -780,7 +780,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP";
|
||||
tags: "Email Provider";
|
||||
summary: "Update SMTP Password";
|
||||
description: "Update the SMTP password that is used for the host, be aware that this will be activated as soon as it is saved. So the users will get notifications from the newly configured SMTP."
|
||||
};
|
||||
@ -830,7 +830,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "Email";
|
||||
tags: "Email Provider";
|
||||
summary: "Remove Email provider";
|
||||
description: "Remove the Email provider, be aware that the users will not get an E-Mail if no provider is set."
|
||||
};
|
||||
@ -847,7 +847,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP Email Provider";
|
||||
tags: "Email Provider";
|
||||
summary: "Test SMTP Email Provider";
|
||||
description: "Test an SMTP Email provider identified by its ID. After testing the provider, the users will receive information about the test results."
|
||||
};
|
||||
@ -864,7 +864,7 @@ service AdminService {
|
||||
};
|
||||
|
||||
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
|
||||
tags: "SMTP EMailProvider";
|
||||
tags: "Email Provider";
|
||||
summary: "Test SMTP Email Provider";
|
||||
description: "Test an SMTP Email provider. After testing the provider, the users will receive information about the test results."
|
||||
};
|
||||
|
||||
Loading…
Reference in New Issue
Block a user