DOCUMENTATION.md in notifications-ruby-client-5.4.0 vs DOCUMENTATION.md in notifications-ruby-client-6.0.0
- old
+ new
@@ -10,11 +10,11 @@
```
gem install 'notifications-ruby-client'
```
-Refer to the [client changelog](https://github.com/alphagov/notifications-ruby-client/blob/master/CHANGELOG.md) for the version number and the latest updates.
+Refer to the [client changelog](https://github.com/alphagov/notifications-ruby-client/blob/main/CHANGELOG.md) for the version number and the latest updates.
### Create a new instance of the client
Add this code to your application:
@@ -183,11 +183,13 @@
If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a hash. For example:
```ruby
personalisation: {
name: "John Smith",
- year: "2016"
+ year: "2016",
+ # pass in an array and it will appear as bullet points in the message:
+ required_documents: ["passport", "utility bill", "other id"],
}
```
You can leave out this argument if a template does not have any placeholder fields for personalised information.
@@ -225,19 +227,17 @@
To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.
The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.
-Your file will be available to download for a default period of 78 weeks (18 months). From 29 March 2023 we will reduce this to 26 weeks (6 months) for all new files. Files sent before 29 March will not be affected.
+Your file will be available to download for a default period of 26 weeks (6 months).
To help protect your files you can also:
* ask recipients to confirm their email address before downloading
* choose the length of time that a file is available to download
-To turn these features on or off, you will need version 5.4.0 of the Ruby client library or a more recent version.
-
#### Add contact details to the file download page
1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in).
1. Go to the __Settings__ page.
1. In the __Email__ section, select __Manage__ on the __Send files by email__ row.
@@ -252,11 +252,11 @@
Your email should also tell recipients how long the file will be available to download.
#### Upload your file
-You can upload PDF, CSV, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support/ask-question-give-feedback) if you need to send other file types.
+You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support/ask-question-give-feedback) if you need to send other file types.
1. Pass the file object as an argument to the `Notifications.prepare_upload` helper method.
1. Pass the result into the personalisation argument.
For example:
@@ -270,55 +270,47 @@
link_to_file: Notifications.prepare_upload(f),
}
end
```
-##### CSV Files
+#### Set the filename
-Uploads for CSV files should use the `is_csv` parameter on the `prepare_upload()` helper method. For example:
+To do this you will need version 6.0.0 of the Ruby client library, or a more recent version.
-```ruby
-File.open("file.csv", "rb") do |f|
- ...
- personalisation: {
- first_name: "Amala",
- application_date: "2018-01-01",
- link_to_file: Notifications.prepare_upload(f, is_csv=true),
- }
-end
-```
+You should provide a filename when you upload your file.
-#### Ask recipients to confirm their email address before they can download the file
+The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.
-This new security feature is optional. You should use it if you send files that are sensitive - for example, because they contain personal information about your users.
+The filename must end with a file extension. For example, `.csv` for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.
-When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.
+If you do not provide a filename for your file, Notify will:
-From 29 March 2023, we will turn this feature on by default for every file you send. Files sent before 29 March will not be affected.
+* generate a random filename
+* try to add the correct file extension
-##### Turn on email address check
+If Notify cannot add the correct file extension, recipients may not be able to open your file.
-To use this feature before 29 March 2023 you will need version 5.4.0 of the Ruby client library, or a more recent version.
-
-To make the recipient confirm their email address before downloading the file, set the `confirm_email_before_download` flag to `true`.
-
-You will not need to do this after 29 March.
-
```ruby
-File.open("file.pdf", "rb") do |f|
+File.open("file.csv", "rb") do |f|
...
personalisation: {
first_name: "Amala",
application_date: "2018-01-01",
- link_to_file: Notifications.prepare_upload(f, confirm_email_before_download: true),
+ link_to_file: Notifications.prepare_upload(f, filename="2023-12-25-daily-report.csv"),
}
end
```
+#### Ask recipients to confirm their email address before they can download the file
+
+When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.
+
+This security feature is turned on by default.
+
##### Turn off email address check (not recommended)
-If you do not want to use this feature after 29 March 2023, you can turn it off on a file-by-file basis.
+If you do not want to use this feature, you can turn it off on a file-by-file basis.
To do this you will need version 5.4.0 of the Ruby client library, or a more recent version.
You should not turn this feature off if you send files that contain:
@@ -343,16 +335,21 @@
#### Choose the length of time that a file is available to download
Set the number of weeks you want the file to be available using the `retention_period` key.
-You can choose any value between 1 week and 78 weeks.
-
To use this feature will need version 5.4.0 of the Ruby client library, or a more recent version.
-If you do not choose a value, the file will be available for the default period of 78 weeks (18 months).
+You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:
+* the need to protect the recipient’s personal information
+* whether the recipient will need to download the file again later
+
+If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).
+
+Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).
+
```ruby
File.open("file.pdf", "rb") do |f|
...
personalisation: {
first_name: "Amala",
@@ -383,12 +380,12 @@
|error.code|error.message|class|How to fix|
|:--- |:---|:---|:---|
|`400`|`BadRequestError: Can't send to this recipient using a team-only API key`|`BadRequestError`|Use the correct type of [API key](#api-keys)|
|`400`|`BadRequestError: Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode`|`BadRequestError`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
|`400`|`BadRequestError: Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)'`|`BadRequestError`|Wrong file type. You can only upload .pdf, .csv, .txt, .doc, .docx, .xlsx, .rtf or .odt files|
-|`400`|`BadRequestError: Unsupported value for retention_period '(PERIOD)'. Supported periods are from 1 to 78 weeks.`|Choose a period between 1 and 78 weeks|
-|`400`|`BadRequestError: Unsupported value for confirm_email_before_download: '(VALUE)'. Use a boolean true or false value.`|Use either true or false|
+|`400`|`BadRequestError: Unsupported value for retention_period '(PERIOD)'. Supported periods are from 1 to 78 weeks.`|`BadRequestError`|Choose a period between 1 and 78 weeks|
+|`400`|`BadRequestError: Unsupported value for confirm_email_before_download: '(VALUE)'. Use a boolean true or false value.`|`BadRequestError`|Use either true or false|
|`400`|`BadRequestError: File did not pass the virus scan`|`BadRequestError`|The file contains a virus|
|`400`|`BadRequestError: Send files by email has not been set up - add contact details for your service at https://www.notifications.service.gov.uk/services/(SERVICE ID)/service-settings/send-files-by-email`|`BadRequestError`|See how to [add contact details to the file download page](#add-contact-details-to-the-file-download-page)|
|`400`|`BadRequestError: Can only send a file by email` | `BadRequestError`|Make sure you are using an email template|
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
@@ -463,11 +460,13 @@
personalisation: {
address_line_1: 'The Occupier', # mandatory address field
address_line_2: '123 High Street', # mandatory address field
address_line_3: 'SW14 6BH', # mandatory address field
name: 'John Smith', # field from template
- application_date: '2018-01-01' # field from template
+ application_date: '2018-01-01' # field from template,
+ # pass in an array and it will appear as bullet points in the letter:
+ required_documents: ["passport", "utility bill", "other id"],
},
```
##### reference (optional)
@@ -758,11 +757,11 @@
|:---|:---|
|#`created`|GOV.UK Notify has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds.|
|#`sending`|GOV.UK Notify has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. GOV.UK Notify is waiting for delivery information.|
|#`pending`|GOV.UK Notify is waiting for more delivery information.<br>GOV.UK Notify received a callback from the provider but the recipient’s device has not yet responded. Another callback from the provider determines the final status of the text message.|
|#`sent`|The message was sent to an international number. The mobile networks in some countries do not provide any more delivery information. The GOV.UK Notify website displays this status as 'Sent to an international number'.|
-|#`delivered`|The message was successfully delivered.|
+|#`delivered`|The message was successfully delivered. If a recipient blocks your sender name or mobile number, your message will still show as delivered.|
|#`permanent-failure`|The provider could not deliver the message. This can happen if the phone number was wrong or if the network operator rejects the message. If you’re sure that these phone numbers are correct, you should [contact GOV.UK Notify support](https://www.notifications.service.gov.uk/support). If not, you should remove them from your database. You’ll still be charged for text messages that cannot be delivered.
|#`temporary-failure`|The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages.|
|#`technical-failure`|Your message was not sent because there was a problem between Notify and the provider.<br>You’ll have to try sending your messages again. You will not be charged for text messages that are affected by a technical failure.|
### Letter status descriptions
@@ -1057,10 +1056,13 @@
You can also set up [callbacks](#callbacks) for received text messages.
### Enable received text messages
-Contact the GOV.UK Notify team using the [support page](https://www.notifications.service.gov.uk/support) or [chat to us on Slack](https://ukgovernmentdigital.slack.com/messages/C0E1ADVPC) to request a unique number for text message replies.
+To receive text messages:
+
+1. Go to the **Text message settings** section of the **Settings** page.
+1. Select **Change** on the **Receive text messages** row.
### Get a page of received text messages
#### Method