-
Notifications
You must be signed in to change notification settings - Fork 43
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation for sms notification summary (#1399)
- Loading branch information
Showing
2 changed files
with
137 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
130 changes: 130 additions & 0 deletions
130
...ications/send-notifications/developer-guides/get-sms-notifications/_index.en.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,130 @@ | ||
| --- | ||
| title: Get sms notifications | ||
| linktitle: Get sms notifications | ||
| description: Endpoint for retrieving the send status of all sms notifications generated by a notification order. | ||
|
|
||
| weight: 60 | ||
| toc: true | ||
| --- | ||
|
|
||
| ## Endpoint | ||
|
|
||
| GET /order/{id}/notifications/sms | ||
|
|
||
| {id} represents the id of the notification order to retrieve notifications for. | ||
|
|
||
| ## Authentication | ||
|
|
||
| This API requires authentication and the request must also include one of the following: | ||
| - Maskinporten scope __altinn:serviceowner/notifications.create__ (for external system callers) | ||
| - Platform Access Token (for Altinn Apps and internal Altinn systems) | ||
|
|
||
| See [Authentication and Authorization](../../../api/#authentication--authorization) for more information. | ||
|
|
||
| ## Response | ||
|
|
||
| ### Response codes | ||
| - 200 OK: The sms notifications were successfully retrieved | ||
| - 404 Not Found: No order matching the provided id were found | ||
|
|
||
| Refer to problem details in response body for further information. | ||
| - 401 Unauthorized: Indicates a missing, invalid or expired authorization header. | ||
| - 403 Forbidden: Indicates that required scope or Platform Access Token is missing or invalid. | ||
|
|
||
| ### Content-Type | ||
| - application/json | ||
|
|
||
| ### Response body | ||
| The response body is formatted as an | ||
| [SmsNotificationSummaryExt](https://github.com/Altinn/altinn-notifications/blob/main/src/Altinn.Notifications/Models/SmsNotificationSummaryExt.cs) | ||
| and serialized as a JSON string. | ||
|
|
||
|
|
||
| ### Response body properties | ||
|
|
||
| #### orderId | ||
| Type: _Guid_ | ||
|
|
||
| The id of the notification order the listed notifications are related to | ||
|
|
||
| #### sendersReference | ||
| Type: _string_ | ||
|
|
||
| The senders reference the creator provided upon the creation of the notification order | ||
|
|
||
| #### generated | ||
| Type: _int_ | ||
|
|
||
| The total number of sms notifications generated so far based on the notification order | ||
|
|
||
| #### succeeded | ||
| Type: _int_ | ||
|
|
||
| The number of sms notifications that have been sent successfully so far | ||
|
|
||
| #### notifications | ||
| Type: _List\<[SmsNotificationWithResult](https://github.com/Altinn/altinn-notifications/blob/main/src/Altinn.Notifications/Models/SmsNotificationWithResultExt.cs)\>_ | ||
|
|
||
| A list of the generated notifications with send result. | ||
| Each notification will include the following properties: | ||
| - id: the id of the notification | ||
| - succeeded: a boolean indicating whether the send status is a successful one. | ||
| - _recipient_: the contact details of the recipient that the notification is sent to. | ||
| - _sendStatus_: the send status of the notification. | ||
|
|
||
| | Status | Description | | ||
| |:-----------------------------:|:-----------------:| | ||
| | New | The SMS has been created, but has not been picked up for processing yet. | | ||
| | Sending | The SMS is being processed and will be attempted sent shortly. | | ||
| | Accepted | The SMS has been accepted by the gateway service and will be sent shortly. | | ||
| | Failed | The SMS was not sent due to an unspecified failure.| | ||
| | Failed_RecipientNotIdentified | The SMS was not sent because the recipient's SMS address was not found. | | ||
| | Failed_InvalidRecipient | The SMS was not sent because the recipient number was invalid. | | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Request | ||
| {{% notice info %}} | ||
| In the example we have included place holders for both the Platform Access and Altinn token. | ||
|
|
||
| __You only need one of them__, reference [Authentication](#authentication) for which one applies to your use case. | ||
| {{% /notice %}} | ||
|
|
||
|
|
||
| ```bash | ||
| curl --location 'https://platform.altinn.no/notifications/api/v1/orders/f1a1cc30-197f-4f34-8304-006ce4945fd1/notifications/sms' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --header 'PlatformAccessToken: [INSERT PLATFORM ACCESS TOKEN]' \ | ||
| --header 'Authorization: Bearer [INSERT ALTINN TOKEN]' | ||
| ``` | ||
|
|
||
| ### Response | ||
|
|
||
| #### 200 OK | ||
| Response body contains the sms notification summary. | ||
|
|
||
| ```json | ||
| { | ||
| "orderId": "f1a1cc30-197f-4f34-8304-006ce4945fd1", | ||
| "sendersReference": "ref-2023-12-01", | ||
| "generated": 1, | ||
| "succeeded": 0, | ||
| "notifications": [ | ||
| { | ||
| "id": "e0197ec7-3d82-4917-8329-8c9ecc4c569b", | ||
| "succeeded": false, | ||
| "recipient": { | ||
| "mobileNumber": "+4799999999" | ||
| }, | ||
| "sendStatus": { | ||
| "status": "New", | ||
| "description": "The sms has been created, but has not been picked up for processing yet.", | ||
| "lastUpdate": "2023-11-14T16:06:02.877361Z" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| #### 404 Not Found | ||
| An empty response is returned with the 404 status code. |