Ct/correspondence/custom recipients (#1936)

* minor grammatical changes

* update swagger

* add english description of custom recipients

* add norwegian doc

* update init endpoint documentation

content/correspondence/getting-started/developer-guides/notifications/_index.en.md

@@ -10,22 +10,28 @@ weight: 40
 {{<children />}}
 
 {{% notice warning  %}}
-This section of the documentation is a work in progress, and as such currently makes extensive reference to external sources.
+This section of the documentation is a work in progress and currently makes extensive reference to external sources.
 {{% /notice %}}
 
 {{% notice warning  %}}
-Currently the Events for Correspondence are not ready for full-scale use, due to pending changes in Altinn Events and Authorization.
+Currently, the Events for Correspondence are not ready for full-scale use due to pending changes in Altinn Events and Authorization.
 This documents the expected scenario, but may be subject to change.
 {{% /notice %}}
 
-To use notifications in Altinn Correspondence, a notification order is placed when a message is created. The notification will primarily be sent out at the publication time of the message. If a reminder is activated, the reminder will be sent after 7 days if the message has not been read. In the test and staging environment, the reminder will be sent out after 1 hour if the message has not been read. 
+To use notifications in Altinn Correspondence, a notification order is placed when a message is created.
+The notification will primarily be sent out at the publication time of the message.
+If a reminder is activated, the reminder will be sent after 7 days if the message has not been read.
+In the test and staging environment, the reminder will be sent out after 1 hour if the message has not been read.
 
-Notifications can be sent via either email or SMS. While email does not have a time window, SMS notifications are sent between 9:00 AM and 5:00 PM. If the sending time falls outside this window, the notification will be sent the following day.
+Notifications can be sent via either email or SMS. While email does not have a time window, SMS notifications are sent between 9:00 AM and 5:00 PM.
+If the sending time falls outside this window, the notification will be sent the following day.
 {{% notice warning  %}}
-In the test environment, Notifications via SMS can only be sent out to phone numbers that are whitelisted internally. Contact us at [Altinn@Slack#produkt-melding](https://join.slack.com/t/altinn/shared_invite/zt-7c77c9si-ZnMFwGNtab1aFdC6H_vwog) if this is required for your service.
+In the test environment, Notifications via SMS can only be sent to phone numbers that are whitelisted internally.
+Contact us at [Altinn@Slack#produkt-melding](https://join.slack.com/t/altinn/shared_invite/zt-7c77c9si-ZnMFwGNtab1aFdC6H_vwog) if this is required for your service.
 {{% /notice %}}
 
 A notification order is made by adding the following when initializing a message:
+
 ```json
 {
   "Correspondence": {
@@ -34,13 +40,13 @@ A notification order is made by adding the following when initializing a message
       "notificationTemplate": CustomText (0) | GenericAltinnMessage(1),
       "notificationChannel": Email(0) | Sms(1) | EmailPreferred(2) | SmsPreferred(3),
       "SendReminder": boolean,
-      "EmailBody": string?, 
+      "EmailBody": string?,
       "EmailSubject": string?,
       "SmsBody": string?,
-      "ReminderNotificationChannel": Email(0) | Sms(1) | EmailPreferred(2) | SmsPreferred(3), 
+      "ReminderNotificationChannel": Email(0) | Sms(1) | EmailPreferred(2) | SmsPreferred(3),
       "ReminderEmailBody": string?,
       "ReminderEmailSubject": string?,
-      "ReminderSmsBody": string? 
+      "ReminderSmsBody": string?
     }
   },
   "Recipients": [],
@@ -49,14 +55,16 @@ A notification order is made by adding the following when initializing a message
 ```
 
 ## Keyword support
-A list of keywords will soon be implemented in Altinn Notifications, but it is not available yet. 
-This feature will allow you to incorporate keywords into the text, such as \$sendersName\$ to display the name of the organization that sent the correspondence, 
+
+A list of keywords will soon be implemented in Altinn Notifications, but it is not available yet.
+This feature will allow you to incorporate keywords into the text, such as \$sendersName\$ to display the name of the organization that sent the correspondence,
 or \$recipientName\$ to use the name of the individual or organization receiving the correspondence. Further details will be provided when it is ready.
 
-## Notification Templates 
-Two types of notification templates are offered when using notifications through the Correspondence API. 
+## Notification Templates
+
+Two types of notification templates are offered when using notifications through the Correspondence API.
 {{% notice warning  %}}
-NOTE: These templates is not the final version. And will change, especially when keywords is ready.
+NOTE: These templates are not the final version and will change, especially when keywords are ready.
 {{% /notice %}}
 
 **CustomText:**
@@ -65,7 +73,8 @@ NOTE: These templates is not the final version. And will change, especially when
 
 **GenericAltinnMessage:**
 
-A generic Altinn text with the option to supplement with additional text. Currently supported languages are Norwegian, Nynorsk, and English. The language is chosen based on the language defined in the message.
+A generic Altinn text with the option to supplement with additional text. Currently supported languages are Norwegian, Nynorsk, and English.
+The language is chosen based on the language defined in the message.
 
 **Title:** You have received a message in Altinn {textToken}<br>
 **Content:** Hello \$recipientName\$, you have received a new message in Altinn from \$sendersName\$. {textToken} Log in to Altinn inbox to see this message.
@@ -77,16 +86,72 @@ In the text, textToken will be replaced with the value given in, for example, "E
 
 Note! Links should NEVER be used in notifications.
 
-## Notification Channels 
+## Notification Channels
+
 Supported notification channels:
 
 - **Email:** Sends an email to the recipient.
 - **SMS:** Sends an SMS to the recipient. Supports both national and international phone numbers.
 - **EmailPreferred:** Uses email as the main communication channel, and SMS as a fallback if email is not available.
 - **SmsPreferred:** Uses SMS as the main communication channel, and email as a fallback if SMS is not available.
-The first notification and the reminder notification can use different notification channels. For example, the first notification is sent by email, while the reminder notification seven days later is sent by SMS.
+  The first notification and the reminder notification can use different notification channels. 
+  For example, the first notification is sent by email, while the reminder notification seven days later is sent by SMS.
+
 ## Cancellation of Notification
-If a message is deleted before the publication date, the notification order will also be deleted. In situations where an error occurs during the publication of a message, the notification will also be deleted.
+
+If a message is deleted before the publication date, the notification order will also be deleted. 
+In situations where an error occurs during the publication of a message, the notification will also be deleted.
 
 ## Errors in Notification Ordering
-If no contact information is available for a recipient, the message will still be sent as planned. Information about the notification can be viewed by retrieving the details about the specific correspondence. Improvements are planned to provide feedback on this during the creation of a message.
+
+If no contact information is available for a recipient, the message will still be sent as planned.
+Information about the notification can be viewed by retrieving the details about the specific correspondence.
+Improvements are planned to provide feedback on this during the creation of a message.
+
+## Custom recipients for Notifications
+
+For all correspondences created with Notifications enabled, the notifications will be sent to the recipient specified in the creation of the correspondence.
+However, it is also possible to choose optional recipients of the notification that are not necessarily the recipient(s) of the correspondence.
+This can be achieved by populating the `recipients` field under `notification` as follows:
+
+```json
+{
+  "notification": {
+    ...,
+    "recipients": [
+      {
+        "recipientToOverride": "string",
+        "notificationRecipient": [
+          {
+            "organizationNumber": "string",
+            "nationalIdentityNumber": "string",
+            "mobileNumber": "string",
+            "emailAddress": "string"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+For each of the optional recipients, they must override an existing recipient in the `Correspondence.Recipients` list.
+This value corresponds to either the organization number or national identity number of the recipient for the correspondence.
+
+Furthermore, it is only possible to provide one of the following fields for the recipient
+
+1. Organization number
+2. National identity number
+3. Mobile number and/or email address
+
+Lastly, if either mobile number or email address is used, they must follow the correct format in order to be able to send the notifications.
+For emails, most of the values are accepted as long as they are on the form '[email protected]'.
+For mobile numbers, they must satisfy the _E.164 format_.
+
+{{% panel theme="warning" %}}
+⚠️ IMPORTANT: In order to use custom recipients for notifications, they must __all__ be valid. 
+Without valid recipients, the correspondence will not be sent out.
+
+Therefore, it is recommended to only use this feature if it is critical for the service. 
+For large dispatches of correspondences these should be made without custom recipients.
+{{% /panel %}}

content/correspondence/getting-started/developer-guides/notifications/_index.nb.md

@@ -18,12 +18,16 @@ For øyeblikket er varslinger for Melding ikke klare for fullskala bruk, på gru
 Dette dokumenterer det forventede scenarioet, men kan endres.
 {{% /notice %}}
 
-For å bruke varslinger i en meldingstjeneste, legges en varslingsbestilling til når en melding opprettes. Varslingen vil bli sendt ut på publikasjonstidspunktet for meldingen. Hvis revarsel er aktivert, vil revarselet sendes ut etter 7 dager dersom meldingen ikke er lest.
+For å bruke varslinger i en meldingstjeneste, legges en varslingsbestilling til når en melding opprettes.
+Varslingen vil bli sendt ut på publikasjonstidspunktet for meldingen. 
+Hvis revarsel er aktivert, vil revarselet sendes ut etter 7 dager dersom meldingen ikke er lest.
 I test- og stagingmiljøet vil revarselet sendes ut etter det har gått en time dersom meldingen ikke er lest.
 
-Varslinger kan sendes via enten e-post eller SMS. Mens e-post ikke har noe tidsvindu, vil SMS-varsler bli sendt mellom kl. 09:00 og 17:00. Hvis avsendingstidspunktet faller utenfor dette tidsvinduet, vil varselet bli sendt neste dag.
+Varslinger kan sendes via enten e-post eller SMS. Mens e-post ikke har noe tidsvindu, vil SMS-varsler bli sendt mellom kl. 09:00 og 17:00.
+Hvis avsendingstidspunktet faller utenfor dette tidsvinduet, vil varselet bli sendt neste dag.
 {{% notice warning  %}}
-I testmiljøet kan varslinger via SMS kun sendes til telefonnumre som er hvitlistet internt. Ta kontakt med oss på [Altinn@Slack#produkt-melding](https://join.slack.com/t/altinn/shared_invite/zt-7c77c9si-ZnMFwGNtab1aFdC6H_vwog) hvis dette er nødvendig for din tjeneste.
+I testmiljøet kan varslinger via SMS kun sendes til telefonnumre som er hvitlistet internt.
+Ta kontakt med oss på [Altinn@Slack#produkt-melding](https://join.slack.com/t/altinn/shared_invite/zt-7c77c9si-ZnMFwGNtab1aFdC6H_vwog) hvis dette er nødvendig for din tjeneste.
 {{% /notice %}}
 
 En varslingsbestilling gjøres ved å legge til følgende når du initialiserer en melding:
@@ -36,13 +40,13 @@ En varslingsbestilling gjøres ved å legge til følgende når du initialiserer
       "notificationTemplate": CustomText (0) | GenericAltinnMessage(1),
       "notificationChannel": Email(0) | Sms(1) | EmailPreferred(2) | SmsPreferred(3),
       "SendReminder": boolean,
-      "EmailBody": string?, 
+      "EmailBody": string?,
       "EmailSubject": string?,
       "SmsBody": string?,
-      "ReminderNotificationChannel": Email(0) | Sms(1) | EmailPreferred(2) | SmsPreferred(3), 
+      "ReminderNotificationChannel": Email(0) | Sms(1) | EmailPreferred(2) | SmsPreferred(3),
       "ReminderEmailBody": string?,
       "ReminderEmailSubject": string?,
-      "ReminderSmsBody": string? 
+      "ReminderSmsBody": string?
     }
   },
   "Recipients": [],
@@ -51,22 +55,27 @@ En varslingsbestilling gjøres ved å legge til følgende når du initialiserer
 ```
 
 ## Keyword støtte
+
 {{% notice warning  %}}
-Keywords er ikke ferdig implementert, men forventes å være på plass i Q4 2024. Mer dokumentasjon kommer da. 
+Keywords er ikke ferdig implementert, men forventes å være på plass i Q4 2024. Mer dokumentasjon kommer da.
 {{% /notice %}}
-Keywords er en liste tokens som lar deg personalisere varslingene med for eksempel mottakers navn. For eksempel vil man kunne bruke \$sendersName\$ for å vise organisasjonsnavnet til avsender. 
+Keywords er en liste tokens som lar deg personalisere varslingene med for eksempel mottakers navn.
+For eksempel vil man kunne bruke \$sendersName\$ for å vise organisasjonsnavnet til avsender.
 
 ## Varslingsmaler
+
 Det tilbys to typer varslingsmaler når du bruker varsling gjennom Meldings-API`et.
 {{% notice warning  %}}
-NOTE: Disse malene vil kunne endres fremmover. Spesielt da Keywords blir ferdig implementert. 
+NOTE: Disse malene vil kunne endres fremmover. Spesielt da Keywords blir ferdig implementert.
 {{% /notice %}}
 
-**CustomText:** 
-- Hele meldingen skrives inn av avsender og sendes i sin helhet til mottaker. 
+**CustomText:**
+
+- Hele meldingen skrives inn av avsender og sendes i sin helhet til mottaker.
 
-**GenericAltinnMessage:** 
-- En generisk Altinn-tekst med mulighet for å supplere med ekstra tekst. Foreløpig støttede språk er norsk, nynorsk og engelsk. Språk velges basert på språket definert i meldingen 
+**GenericAltinnMessage:**
+
+- En generisk Altinn-tekst med mulighet for å supplere med ekstra tekst. Foreløpig støttede språk er norsk, nynorsk og engelsk. Språk velges basert på språket definert i meldingen
 
 **Tittel:** Du har mottatt en melding i Altinn {textToken}<br>
 **Innhold:** Hei \$recipientName\$, du har mottatt en ny melding i Altinn fra \$sendersName\$. {textToken} Logg deg inn i Altinn inboks for å se denne meldingen.
@@ -76,21 +85,75 @@ NOTE: Disse malene vil kunne endres fremmover. Spesielt da Keywords blir ferdig
 
 I teksten vil textToken bli byttet ut med verdien gitt i for eksempel "EmailSubject" for tittelen. SMS bruker kun innholdet, ikke tittelen.
 
-NB! Linker skal ALDRI brukes i varslinger. 
+NB! Linker skal ALDRI brukes i varslinger.
+
+## Varslingskanaler
+
+Støttede varslingskanaler:
 
-## Varslingskanaler 
-Støttede varslingskanaler: 
 - **Email:** Sender en e-post til mottaker.
 - **SMS:** Sender en sms til mottaker. Støtter nasjonale og internasjonale telefonnummre.
 - **EmailPreferred:** Bruker e-post som hoved kommunikasjonskanal, og SMS som fallback hvis e-post ikke er tilgjengelig.
 - **SmsPreferred:** Bruker SMS som hoved kommunikasjonskanal, og e-post som fallback om SMS ikke finnes.
 
-Hovedvarsel og revarsel kan bruke forskjellige notifikasjonskanaler. For eksempel kan man velge å sende første varsel på e-post, men så går det ett revarsel på sms etter 7 dager.
+Hovedvarsel og revarsel kan bruke forskjellige notifikasjonskanaler.
+For eksempel kan man velge å sende første varsel på e-post, men så går det ett revarsel på sms etter 7 dager.
 
 ## Kansellering av varsling
-Dersom en melding slettes før publiseringsdatoen, vil varslingsbestillingen også bli slettet. I tilfeller der det oppstår en feil under publisering av en melding, vil varslingen også bli slettet.
+
+Dersom en melding slettes før publiseringsdatoen, vil varslingsbestillingen også bli slettet.
+I tilfeller der det oppstår en feil under publisering av en melding, vil varslingen også bli slettet.
 
 ## Feil ved bestilling av varsling
-Hvis det ikke finnes kontaktinformasjon for en mottaker, vil meldingen fortsatt bli sendt som planlagt. 
-Informasjon om varslingen kan sees ved å hente detaljer om den spesifikke meldingen. 
+
+Hvis det ikke finnes kontaktinformasjon for en mottaker, vil meldingen fortsatt bli sendt som planlagt.
+Informasjon om varslingen kan sees ved å hente detaljer om den spesifikke meldingen.
 Det er planlagt forbedringer for å gi tilbakemelding omkring dette under opprettelsen av en melding.
+
+## Valgfri mottakere for varsling
+
+For meldinger som er opprettet med varsling aktivert vil mottakeren av varslingen være den samme som mottakeren av meldingen.
+Det er derimot mulig benytte valgfrie mottakere av varsling, som ikke nødvendigvis er mottaker av meldingen.
+Dette gjøres ved å fylle ut `recipients`-feltet under `notification` slik:
+
+```json
+{
+  "notification": {
+    ...,
+    "recipients": [
+      {
+        "recipientToOverride": "string",
+        "notificationRecipient": [
+          {
+            "organizationNumber": "string",
+            "nationalIdentityNumber": "string",
+            "mobileNumber": "string",
+            "emailAddress": "string"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Alle valgfrie mottakere må overstyre en eksisterende mottaker i listen til `Correspondence.Recipients`l
+Denne verdien vil være enten organisasjonsnummeret eller fødselsnummeret til mottakeren av korrespondansen.
+
+Det er også kun mulig å oppgi ett av følgende felt for mottakeren:
+
+1. Organisasjonsnummer
+2. Fødselsnummer
+3. Mobilnummer og/eller e-postadresse
+
+Dersom enten mobilnummer eller e-postadresse brukes, må de ha riktig format for å kunne sende varslingene.
+For e-poster aksepteres de fleste verdier så lenge de er i formen '[email protected]'.
+For mobilnumre må de tilfredsstille _E.164-formatet_.
+
+{{% panel theme="warning" %}}
+⚠️ VIKTIG: For å bruke valgfrie mottakere for varslinger, må **alle** mottakere være gyldige.
+Dersom en mottaker er ugyldig vil ikke meldingen(e) bli sendt ut.
+
+Derfor anbefales det å kun bruke denne funksjonaliteten dersom det er kritisk for tjenesten.
+For store utsendelser av meldinger bør disse opprettes uten tilpassede mottakere.
+{{% /panel %}}

content/correspondence/reference/API endpoints/initialize/_index.en.md

@@ -77,10 +77,10 @@ A list of the generated notifications with send results. Each notification will
 
 - _orderId_: the ID of the order.
 - _isReminder_: a boolean indicating whether the notification is a reminder or not.
-- _status_: shows the status of the notification.
+- _status_: shows the status of the notification at the time of creating the correspondence(s).
 
 | Status            | Description                                                                 |
 |:-----------------:|:---------------------------------------------------------------------------:|
-| Success           | Means that the notification order was created successfully with contact information. |
-| MissingContact    | Contact information was not found at the time of creating the correspondence. |
-| Failure           | Creating notification order failed.                                         |
+| Success           | Notification order was created successfully with contact information for __at least one__ of the recipients for the notification. |
+| MissingContact    | Contact information was not found for __any of__ the recipients for the notification at the time of creating the correspondence. |
+| Failure           | Creating notification order failed due to an error.|