DOCUMENTATION.md in notifications-ruby-client-5.1.0 vs DOCUMENTATION.md in notifications-ruby-client-5.1.1

- old
+ new

@@ -21,11 +21,11 @@ ```ruby require 'notifications/client' client = Notifications::Client.new(api_key) ``` -To get an API key, [sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/) and go to the __API integration__ page. You can find more information in the [API keys](#api-keys) section of this documentation. +To get an API key, [sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __API integration__ page. You can find more information in the [API keys](#api-keys) section of this documentation. # Send a message You can use GOV.UK Notify to send text messages, emails or letters. @@ -50,12 +50,18 @@ phone_number:"+447900900123" ``` #### template_id (required) -Sign in to [GOV.UK Notify](https://www.notifications.service.gov.uk/) and go to the __Templates__ page to find the template ID. For example: +To find the template ID: +1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in). +1. Go to the __Templates__ page and select the relevant template. +1. Select __Copy template ID to clipboard__. + +For example: + ```ruby template_id:"f33517ff-2a88-4f6e-b855-c550268ce08a" ``` #### personalisation (optional) @@ -81,17 +87,18 @@ You can leave out this argument if you do not have a reference. #### sms_sender_id (optional) -A unique identifier of the sender of the text message notification. You can find this information on the __Text Message sender__ settings screen. +A unique identifier of the sender of the text message notification. -1. Sign in to your GOV.UK Notify account. -1. Go to __Settings__. -1. If you need to change to another service, select __Switch service__ in the top right corner of the screen and select the correct one. -1. Go to the __Text Messages__ section and select __Manage__ on the __Text Message sender__ row. +To find the text message sender: +1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in). +1. Go to the __Settings__ page. +1. In the __Text Messages__ section, select __Manage__ on the __Text Message sender__ row. + You can then either: - copy the sender ID that you want to use and paste it into the method - select __Change__ to change the default sender that the service uses, and select __Save__ @@ -157,12 +164,18 @@ email_address: "sender@something.com" ``` #### template_id (required) -Sign in to [GOV.UK Notify](https://www.notifications.service.gov.uk/) and go to the __Templates__ page to find the template ID. For example: +To find the template ID: +1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in). +1. Go to the __Templates__ page and select the relevant template. +1. Select __Copy template ID to clipboard__. + +For example: + ```ruby template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a" ``` #### personalisation (optional) @@ -188,18 +201,19 @@ You can leave out this argument if you do not have a reference. #### email_reply_to_id (optional) -This is an email reply-to address specified by you to receive replies from your users. Your service cannot go live until you set up at least one of these email addresses. +This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live. -1. Sign into your GOV.UK Notify account. -1. Go to __Settings__. -1. If you need to change to another service, select __Switch service__ in the top right corner of the screen and select the correct one. -1. Go to the __Email__ section and select __Manage__ on the __Email reply-to addresses__ row. -1. Select __Change__ to specify the email address to receive replies, and select __Save__. +To add a reply-to email address: +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 __Reply-to email addresses__ row. +1. Select __Add reply-to address__. +1. Enter the email address you want to use, and select __Add__. For example: ```ruby email_reply_to_id: '8e222534-7f05-4972-86e3-17c5d9f894e2' @@ -217,19 +231,20 @@ The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file. ### Add a placeholder field to the template -1. Sign in to [GOV.UK Notify](https://www.notifications.service.gov.uk/). +1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in). 1. Go to the __Templates__ page and select the relevant email template. +1. Select __Edit__. 1. Add a placeholder field to the email template using double brackets. For example: "Download your file at: ((link_to_document))" ### Upload your file -The file you upload must be a PDF file smaller than 2MB. +The file you upload must be a PDF or CSV file 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: @@ -277,16 +292,18 @@ |`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification| |-|`ArgumentError: Document is larger than 2MB")`|-|Document size was too large, upload a smaller document| ## Send a letter -When your service first signs up to GOV.UK Notify, you’ll start in trial mode. You can only send letters in live mode. You must ask GOV.UK Notify to make your service live. +When you add a new service it will start in [trial mode](https://www.notifications.service.gov.uk/features/trial-mode). You can only send letters when your service is live. -1. Sign in to [GOV.UK Notify](https://www.notifications.service.gov.uk/). -1. Select __Using Notify__. -1. Select __requesting to go live__. +To send Notify a request to go live: +1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in). +1. Go to the __Settings__ page. +1. In the __Your service is in trial mode__ section, select __request to go live__. + ### Method ```ruby letterresponse = client.send_letter( template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a", @@ -300,19 +317,25 @@ ### Arguments #### template_id (required) -Sign in to GOV.UK Notify and go to the __Templates__ page to find the template ID. For example: +To find the template ID: +1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in). +1. Go to the __Templates__ page and select the relevant template. +1. Select __Copy template ID to clipboard__. + +For example: + ```ruby template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a" ``` #### personalisation (required) -The personalisation argument always contains the following parameters for the letter recipient's address: +The personalisation argument always contains the following parameters for the letter recipient’s address: - `address_line_1` - `address_line_2` - `postcode` @@ -329,11 +352,11 @@ }, ``` #### personalisation (optional) -The following parameters in the letter recipient's address are optional: +The following parameters in the letter recipient’s address are optional: ```ruby personalisation: { address_line_3: 'Richmond', # optional address field address_line_4: 'London', # optional address field @@ -486,11 +509,11 @@ #### id (required) The ID of the notification. You can find the notification ID in the response to the [original notification method call](#response). -You can also find it by signing in to [GOV.UK Notify](https://www.notifications.service.gov.uk) and going to the __API integration__ page. +You can also find it by [signing in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and going to the __API integration__ page. ### Response If the request to the client is successful, the client returns a `Notifications::Client::Notification` object. In the example shown in the [Method section](#get-the-status-of-one-message-method), the object is named `response`. @@ -669,19 +692,20 @@ #### id (required) The ID of the notification. You can find the notification ID in the response to the [original notification method call](#get-the-status-of-one-message-response). -You can also find it by signing in to [GOV.UK Notify](https://www.notifications.service.gov.uk) and going to the __API integration__ page. +You can also find it by [signing in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and going to the __API integration__ page. ### Response If the request to the client is successful, the client will return a `string` containing the raw PDF data. ### Error codes If the request is not successful, the client throws a `Notifications::Client::RequestError` and an error code. + |error.code|error.message|class|How to fix| |:---|:---|:---|:---| |`400`|`ValidationError: id is not a valid UUID`|`BadRequestError`|Check the notification ID| |`400`|`PDFNotReadyError: PDF not available yet, try again later`|`BadRequestError`|Wait for the notification to finish processing. This usually takes a few seconds| |`400`|`BadRequestError: Document did not pass the virus scan`|`BadRequestError`|You cannot retrieve the contents of a letter notification that contains a virus| @@ -706,11 +730,11 @@ ### Arguments #### id (required) -The ID of the template. Sign into GOV.UK Notify and go to the __Templates__ page to find this. For example: +The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __Templates__ page to find it. For example: ``` 'f33517ff-2a88-4f6e-b855-c550268ce08a' ``` @@ -753,11 +777,11 @@ ### Arguments #### id (required) -The ID of the template. Sign in to GOV.UK Notify and go to the __Templates__ page to find this. For example: +The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __Templates__ page to find it. For example: ```ruby 'f33517ff-2a88-4f6e-b855-c550268ce08a' ``` @@ -861,11 +885,11 @@ ### Arguments #### id (required) -The ID of the template. Sign into GOV.UK Notify and go to the __Templates__ page. For example: +The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __Templates__ page to find it. For example: ```ruby 'f33517ff-2a88-4f6e-b855-c550268ce08a' ``` @@ -916,10 +940,10 @@ You can also set up [callbacks](#callbacks) for received text messages. ## Enable received text messages -Contact the GOV.UK Notify team on the [support page](https://www.notifications.service.gov.uk/support) or through the [Slack channel](https://ukgovernmentdigital.slack.com/messages/C0E1ADVPC) to enable receiving text messages for your service. +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. ## Get a page of received text messages ### Method