notifications-ruby-client 2.7.0 → 2.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (10) hide show
  1. checksums.yaml +5 -5
  2. data/.github/PULL_REQUEST_TEMPLATE.md +1 -1
  3. data/CHANGELOG.md +5 -0
  4. data/CONTRIBUTING.md +39 -0
  5. data/DOCUMENTATION.md +544 -529
  6. data/README.md +6 -812
  7. data/bin/test_client.rb +1 -0
  8. data/lib/notifications/client/response_template.rb +1 -0
  9. data/lib/notifications/client/version.rb +1 -1
  10. metadata +4 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: c9e8e3b5a9125d84b62e3015abf89f6aa7b8b7c9
4
- data.tar.gz: 37f15920e5d4b62f7c6187eebd07473758a29949
2
+ SHA256:
3
+ metadata.gz: a7ebfa7945a861630914de5251f291bb5fac91f6d594b819364ca745072e6129
4
+ data.tar.gz: 8374e982bd9a519d85446dae5a4cb4808308ba80443f431ec1841f7ddbea54cb
5
5
  SHA512:
6
- metadata.gz: 81a60d12905de3b4afe229431036fb8b8cb27c942e531e2e73bb378a5b632a435fc53426e548641545dedf36e5cdd861ea54a2136fe972d82405ec18ff39ca0f
7
- data.tar.gz: c8739e97c93b0a6ae027c94ddce821505e6e825d865e80c3d436f23576c67f2d2c8d7a995ad400c7470895f2dd6d0c64bb767e0fb62f94ff8dcac81eadee3492
6
+ metadata.gz: eb25a50ca0b7b0571f6908711ede2a3212fad478f7243538a88acc8c6bd7254eec1d670ba54dd6953281bf353d85b94ca05ecd99aa9de89bb4386306c74bdb18
7
+ data.tar.gz: 1e94b34627e331bb61e4e549efec4b8a6a50318665d3639b75b021f0d5b080f40ec7d73507d21b73c87db686d4f934016287ab65fd1ed0c0a92280eca91571d8
data/.github/PULL_REQUEST_TEMPLATE.md CHANGED
@@ -8,5 +8,5 @@
8
8
  <!--- All of the following are normally needed. Don’t worry if you haven’t done them or don’t know how – someone from the Notify team will be able to help. -->
9
9
  - [x] I’ve used the pull request template
10
10
  - [ ] I’ve written unit tests for these changes
11
- - [ ] I’ve update the documentation (in `README.md`)
11
+ - [ ] I’ve updated the documentation (in `DOCUMENTATION.md`)
12
12
  - [ ] I’ve bumped the version number (in `lib/notifications/client/version.rb`)
data/CHANGELOG.md CHANGED
@@ -1,3 +1,8 @@
1
+ ## 2.8.0
2
+
3
+ * Updated the Template class to have a `name` property, which is the name of the template as set in Notify.
4
+
5
+
1
6
  ## 2.7.0
2
7
 
3
8
  * The Notification class has a new `created_by_name` property.
data/CONTRIBUTING.md ADDED
@@ -0,0 +1,39 @@
1
+ # Contributing
2
+
3
+ Pull requests are welcome.
4
+
5
+ ## Tests
6
+
7
+ There are unit and integration tests that can be run to test functionality of the client.
8
+
9
+ ## Unit Tests
10
+
11
+ To run the unit tests:
12
+
13
+ ```
14
+ make test
15
+ ```
16
+
17
+ ## Integration Tests
18
+
19
+ Before running the integration tests, please ensure that the environment variables are set up.
20
+
21
+ ```sh
22
+ export NOTIFY_API_URL="https://example.notify-api.url"
23
+ export API_KEY="example_API_test_key"
24
+ export FUNCTIONAL_TEST_NUMBER="valid mobile number"
25
+ export FUNCTIONAL_TEST_EMAIL="valid email address"
26
+ export EMAIL_TEMPLATE_ID="valid email_template_id"
27
+ export SMS_TEMPLATE_ID="valid sms_template_id"
28
+ export LETTER_TEMPLATE_ID="valid letter_template_id"
29
+ export EMAIL_REPLY_TO_ID="valid email reply to id"
30
+ export SMS_SENDER_ID="valid sms_sender_id - to test sending to a receiving number, so needs to be a valid number"
31
+ export API_SENDING_KEY="API_whitelist_key for sending a SMS to a receiving number"
32
+ export INBOUND_SMS_QUERY_KEY="API_test_key to get received text messages"
33
+ ```
34
+
35
+ To run the integration tests:
36
+
37
+ ```
38
+ make integration-test
39
+ ```
data/DOCUMENTATION.md CHANGED
@@ -1,810 +1,825 @@
1
- # GOV.UK Notify Ruby client
1
+ # Ruby client documentation
2
2
 
3
- This documentation is for developers interested in using this Ruby client to integrate their government service with GOV.UK Notify.
3
+ This documentation is for developers interested in using the GOV.UK Notify Ruby client to send emails, text messages or letters.
4
4
 
5
- [![Gem Version](https://badge.fury.io/rb/notifications-ruby-client.svg)](https://badge.fury.io/rb/notifications-ruby-client)
5
+ # Set up the client
6
6
 
7
- ## Table of Contents
7
+ ## Install the client
8
8
 
9
- * [Installation](#installation)
10
- * [Getting started](#getting-started)
11
- * [Send messages](#send-messages)
12
- * [Get the status of one message](#get-the-status-of-one-message)
13
- * [Get the status of all messages](#get-the-status-of-all-messages)
14
- * [Get a template by ID](#get-a-template-by-id)
15
- * [Get a template by ID and version](#get-a-template-by-id-and-version)
16
- * [Get all templates](#get-all-templates)
17
- * [Generate a preview template](#generate-a-preview-template)
18
- * [Get received texts](#get-received-texts)
19
-
20
- ## Installation
21
-
22
- Prior to usage an account must be created through the Notify admin console. This will allow access to the API credentials you application.
23
-
24
- You can then install the gem or require it in your application.
9
+ Run the following in the command line:
25
10
 
26
11
  ```
27
12
  gem install 'notifications-ruby-client'
28
13
  ```
29
14
 
30
- ## Getting started
15
+ Refer to the [client changelog](https://github.com/alphagov/notifications-ruby-client/blob/master/CHANGELOG.md) for the version number and the latest updates.
16
+
17
+ ## Create a new instance of the client
18
+
19
+ Add this code to your application:
31
20
 
32
21
  ```ruby
33
22
  require 'notifications/client'
34
23
  client = Notifications::Client.new(api_key)
35
24
  ```
36
25
 
37
- Generate an API key by logging in to GOV.UK Notify [GOV.UK Notify](https://www.notifications.service.gov.uk) and going to the **API integration** page.
26
+ 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](/ruby.html#api-keys) section of this documentation.
38
27
 
39
- ## Send messages
28
+ # Send a message
40
29
 
41
- ### Text message
30
+ You can use GOV.UK Notify to send text messages, emails or letters.
42
31
 
43
- #### Method
32
+ ## Send a text message
44
33
 
45
- <details>
46
- <summary>
47
- Click here to expand for more information.
48
- </summary>
34
+ ### Method
49
35
 
50
36
  ```ruby
51
- sms = client.send_sms(
52
- phone_number: number,
53
- template_id: template_id,
54
- personalisation: {
55
- name: "name",
56
- year: "2016",
57
- },
58
- reference: "your_reference_string",
59
- sms_sender_id: sms_sender_id
60
- ) # => Notifications::Client::ResponseNotification
37
+ smsresponse = client.send_sms(
38
+ phone_number: "+447900900123",
39
+ template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a",
40
+ )
61
41
  ```
62
42
 
63
- </details>
43
+ ### Arguments
64
44
 
65
- #### Response
45
+ #### phone_number (required)
66
46
 
67
- If the request is successful, a `Notifications::Client:ResponseNotification` is returned.
68
- <details>
69
- <summary>
70
- Click here to expand for more information.
71
- </summary>
47
+ The phone number of the text message recipient. This can be a UK or international number. For example:
72
48
 
73
49
  ```ruby
74
- sms => Notifications::Client::ResponseNotification
50
+ phone_number:"+447900900123"
51
+ ```
75
52
 
76
- sms.id # => uuid for the notification
77
- sms.reference # => Reference string you supplied in the request
78
- sms.content # => Hash containing body => the message sent to the recipient, with placeholders replaced.
79
- # from_number => the sms sender number of your service found **Settings** page
80
- sms.template # => Hash containing id => id of the template
81
- # version => version of the template
82
- # uri => url of the template
83
- sms.uri # => URL of the notification
53
+ #### template_id (required)
54
+
55
+ 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:
56
+
57
+ ```ruby
58
+ template_id:"f33517ff-2a88-4f6e-b855-c550268ce08a"
84
59
  ```
85
60
 
61
+ #### personalisation (optional)
86
62
 
87
- Otherwise the client will raise a `Notifications::Client::RequestError`:
63
+ 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:
88
64
 
89
- |`error.code`|`error.message`|
90
- |:---|:---|
91
- |`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"`<br>`}]`|
92
- |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|
93
- |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient using a team-only API key"`<br>`]}`|
94
- |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|
65
+ ```ruby
66
+ personalisation: {
67
+ name: "John Smith",
68
+ ID: "300241",
69
+ }
70
+ ```
95
71
 
96
- </details>
72
+ You can leave out this argument if a template does not have any placeholder fields for personalised information.
97
73
 
98
- #### Arguments
74
+ #### reference (optional)
99
75
 
100
- <details>
101
- <summary>
102
- Click here to expand for more information.
103
- </summary>
76
+ A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. For example:
104
77
 
105
- ##### `phone_number`
78
+ ```ruby
79
+ reference: "your_reference_string"
80
+ ```
106
81
 
107
- The phone number of the recipient, only required for sms notifications.
82
+ You can leave out this argument if you do not have a reference.
108
83
 
109
- ##### `template_id`
84
+ #### sms_sender_id (optional)
110
85
 
111
- Find by clicking **API info** for the template you want to send.
86
+ A unique identifier of the sender of the text message notification. You can find this information on the __Text Message sender__ settings screen.
112
87
 
113
- ##### `reference`
88
+ 1. Sign in to your GOV.UK Notify account.
89
+ 1. Go to __Settings__.
90
+ 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.
91
+ 1. Go to the __Text Messages__ section and select __Manage__ on the __Text Message sender__ row.
114
92
 
115
- An optional identifier you generate. The `reference` can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.
93
+ You can then either:
116
94
 
117
- You can omit this argument if you do not require a reference for the notification.
95
+ - copy the sender ID that you want to use and paste it into the method
96
+ - select __Change__ to change the default sender that the service uses, and select __Save__
118
97
 
119
- ##### `personalisation`
120
98
 
121
- If a template has placeholders, you need to provide their values, for example:
99
+ For example:
122
100
 
123
- ```python
124
- personalisation={
125
- 'first_name': 'Amala',
126
- 'reference_number': '300241',
127
- }
101
+ ```ruby
102
+ sms_sender_id: "8e222534-7f05-4972-86e3-17c5d9f894e2"
128
103
  ```
129
- ##### `sms_sender_id`
130
104
 
131
- Optional. Specifies the identifier of the sms sender to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Text message sender'.
105
+ You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.
106
+
107
+ ### Response
108
+
109
+ If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](/ruby.html#method), the object is named `smsresponse`.
110
+
111
+ You can then call different methods on this object:
112
+
113
+ |Method|Information|Type|
114
+ |:---|:---|:---|
115
+ |`smsresponse.id`|Notification UUID|String|
116
+ |`smsresponse.reference`|`reference` argument|String|
117
+ |`smsresponse.content`|- `body`: Message body sent to the recipient<br>- `from_number`: SMS sender number of your service|Hash|
118
+ |`smsresponse.template`|Contains the `id`, `version` and `uri` of the template|Hash|
119
+ |`smsresponse.uri`|Notification URL|String|
132
120
 
133
- If you omit this argument your default sms sender will be set for the notification.
121
+ If you are using the [test API key](/ruby.html#test), all your messages come back with a `delivered` status.
134
122
 
135
- </details>
123
+ All messages sent using the [team and whitelist](#team-and-whitelist) or [live](#live) keys appear on your GOV.UK Notify dashboard.
136
124
 
125
+ ### Error codes
137
126
 
138
- ### Email
127
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code.
139
128
 
140
- #### Method
129
+ |error.code|error.message|How to fix|
130
+ |:---|:---|:---|
131
+ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient using a team-only API key"`<br>`]}`|Use the correct type of [API key](/ruby.html#api-keys)|
132
+ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
133
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
134
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
135
+ |`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"`<br>`}]`|Refer to [API rate limits](/ruby.html#api-rate-limits) for more information|
136
+ |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (LIMIT NUMBER) for today"`<br>`}]`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
137
+ |`500`|`[{`<br>`"error": "Exception",`<br>`"message": "Internal server error"`<br>`}]`|Notify was unable to process the request, resend your notification|
141
138
 
142
- <details>
143
- <summary>
144
- Click here to expand for more information.
145
- </summary>
139
+ ## Send an email
140
+
141
+ ### Method
146
142
 
147
143
  ```ruby
148
- email = client.send_email(
149
- email_address: email_address,
150
- template_id: template_id,
151
- personalisation: {
152
- name: "name",
153
- year: "2016"
154
- },
155
- reference: "your_reference_string",
156
- email_reply_to_id: email_reply_to_id
157
- ) # => Notifications::Client::ResponseNotification
144
+ emailresponse = client.send_email(
145
+ email_address: "sender@something.com",
146
+ template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a",
147
+ )
158
148
  ```
159
149
 
160
- </details>
150
+ ### Arguments
161
151
 
152
+ #### email_address (required)
162
153
 
163
- #### Response
154
+ The email address of the recipient. For example:
164
155
 
165
- If the request is successful, a `Notifications::Client:ResponseNotification` is returned.
156
+ ```ruby
157
+ email_address: "sender@something.com"
158
+ ```
159
+
160
+ #### template_id (required)
166
161
 
167
- <details>
168
- <summary>
169
- Click here to expand for more information.
170
- </summary>
162
+ 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:
171
163
 
172
164
  ```ruby
173
- email => Notifications::Client::ResponseNotification
165
+ template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a"
166
+ ```
174
167
 
175
- email.id # => uuid for the notification
176
- email.reference # => Reference string you supplied in the request
177
- email.content # => Hash containing body => the message sent to the recipient, with placeholders replaced.
178
- # subject => subject of the message sent to the recipient, with placeholders replaced.
179
- # from_email => the from email of your service found **Settings** page
180
- email.template # => Hash containing id => id of the template
181
- # version => version of the template
182
- # uri => url of the template
183
- email.uri # => URL of the notification
168
+ #### personalisation (optional)
169
+
170
+ 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:
171
+
172
+ ```ruby
173
+ personalisation: {
174
+ name: "John Smith",
175
+ year: "2016"
176
+ }
184
177
  ```
185
178
 
186
- Otherwise the client will raise a `Notifications::Client::RequestError`:
179
+ You can leave out this argument if a template does not have any placeholder fields for personalised information.
187
180
 
188
- |`error.code`|`error.message`|
189
- |:---|:---|
190
- |`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"`<br>`}]`|
191
- |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|
192
- |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient using a team-only API key"`<br>`]}`|
193
- |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|
181
+ #### reference (optional)
194
182
 
195
- </details>
183
+ A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. For example:
196
184
 
185
+ ```ruby
186
+ reference: "your_reference_string"
187
+ ```
197
188
 
198
- #### Arguments
189
+ You can leave out this argument if you do not have a reference.
199
190
 
200
- <details>
201
- <summary>
202
- Click here to expand for more information.
203
- </summary>
191
+ #### email_reply_to_id (optional)
204
192
 
205
- ##### `email_address`
206
- The email address of the recipient, only required for email notifications.
193
+ 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.
207
194
 
208
- ##### `template_id`
195
+ 1. Sign into your GOV.UK Notify account.
196
+ 1. Go to __Settings__.
197
+ 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.
198
+ 1. Go to the __Email__ section and select __Manage__ on the __Email reply-to addresses__ row.
199
+ 1. Select __Change__ to specify the email address to receive replies, and select __Save__.
209
200
 
210
- Find by clicking **API info** for the template you want to send.
211
201
 
212
- ##### `reference`
202
+ For example:
213
203
 
214
- An optional identifier you generate. The `reference` can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.
204
+ ```ruby
205
+ email_reply_to_id: '8e222534-7f05-4972-86e3-17c5d9f894e2'
206
+ ```
215
207
 
216
- You can omit this argument if you do not require a reference for the notification.
208
+ You can leave out this argument if your service only has one email reply-to address, or you want to use the default email address.
217
209
 
218
- ##### `email_reply_to_id`
210
+ ### Response
219
211
 
220
- Optional. Specifies the identifier of the email reply-to address to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Email reply to addresses'.
212
+ If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](/ruby.html#send-an-email-method), the object is named `emailresponse`.
221
213
 
222
- If you omit this argument your default email reply-to address will be set for the notification.
214
+ You can then call different methods on this object to return the requested information.
223
215
 
224
- ##### `personalisation`
216
+ |Method|Information|Type|
217
+ |:---|:---|:---|
218
+ |`emailresponse.id`|Notification UUID|String|
219
+ |`emailresponse.reference`|`reference` argument|String|
220
+ |`emailresponse.content`|- `body`: Message body<br>- `subject`: Message subject<br>- `from_email`: From email address of your service found on the **Settings** page|Hash|
221
+ |`emailresponse.template`|Contains the `id`, `version` and `uri` of the template|Hash|
222
+ |`emailresponse.uri`|Notification URL|String|
225
223
 
226
- If a template has placeholders, you need to provide their values, for example:
224
+ ### Error codes
227
225
 
228
- ```python
229
- personalisation={
230
- 'first_name': 'Amala',
231
- 'application_number': '300241',
232
- }
233
- ```
226
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code.
234
227
 
235
- </details>
228
+ |error.code|error.message|How to fix|
229
+ |:--- |:---|:---|
230
+ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient using a team-only API key"`<br>`]}`|Use the correct type of [API key](/ruby.html#api-keys)|
231
+ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
232
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
233
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
234
+ |`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"`<br>`}]`|Refer to [API rate limits](/ruby.html#api-rate-limits) for more information|
235
+ |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (LIMIT NUMBER) for today"`<br>`}]`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
236
+ |`500`|`[{`<br>`"error": "Exception",`<br>`"message": "Internal server error"`<br>`}]`|Notify was unable to process the request, resend your notification|
236
237
 
238
+ ## Send a letter
237
239
 
238
- ### Letter
240
+ 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.
239
241
 
240
- #### Method
242
+ 1. Sign in to [GOV.UK Notify](https://www.notifications.service.gov.uk/).
243
+ 1. Select __Using Notify__.
244
+ 1. Select __requesting to go live__.
241
245
 
242
- <details>
243
- <summary>
244
- Click here to expand for more information.
245
- </summary>
246
+ ### Method
246
247
 
247
248
  ```ruby
248
- letter = client.send_letter(
249
- template_id: template_id,
249
+ letterresponse = client.send_letter(
250
+ template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a",
250
251
  personalisation: {
251
- address_line_1: 'Her Majesty The Queen', # required
252
- address_line_2: 'Buckingham Palace', # required
253
- address_line_3: 'London',
254
- postcode: 'SW1 1AA', # required
255
-
256
- ... # any other personalisation found in your template
252
+ address_line_1: 'The Occupier',
253
+ address_line_2: '123 High Street',
254
+ postcode: 'SW14 6BH',
257
255
  },
258
- reference: "your_reference_string"
259
- ) # => Notifications::Client::ResponseNotification
256
+ )
260
257
  ```
261
258
 
262
- </details>
263
-
264
-
265
- #### Response
259
+ ### Arguments
266
260
 
267
- If the request is successful, a `Notifications::Client:ResponseNotification` is returned.
261
+ #### template_id (required)
268
262
 
269
- <details>
270
- <summary>
271
- Click here to expand for more information.
272
- </summary>
263
+ Sign in to GOV.UK Notify and go to the __Templates__ page to find the template ID. For example:
273
264
 
274
265
  ```ruby
275
- letter => Notifications::Client::ResponseNotification
276
-
277
- letter.id # => uuid for the notification
278
- letter.reference # => Reference string you supplied in the request
279
- letter.content # => Hash containing body => the body of the letter sent to the recipient, with placeholders replaced
280
- # subject => the main heading of the letter
281
- letter.template # => Hash containing id => id of the template
282
- # version => version of the template
283
- # uri => url of the template
284
- letter.uri # => URL of the notification
266
+ template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a"
285
267
  ```
286
268
 
287
- |`error.code`|`error.message`|
288
- |:---|:---|
289
- |`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"`<br>`}]`|
290
- |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (50) for today"`<br>`}]`|
291
- |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient using a team-only API key"`<br>`]}`|
292
- |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Can"t send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|
293
- |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "personalisation address_line_1 is a required property"`<br>`}]`|
294
-
295
- </details>
269
+ #### personalisation (required)
296
270
 
271
+ The personalisation argument always contains the following parameters for the letter recipient's address:
297
272
 
298
- #### Arguments
273
+ - `address_line_1`
274
+ - `address_line_2`
275
+ - `postcode`
299
276
 
300
- <details>
301
- <summary>
302
- Click here to expand for more information.
303
- </summary>
277
+ Any other placeholder fields included in the letter template also count as required parameters. You must provide their values in a hash. For example:
304
278
 
305
- #### `template_id`
306
- Find by clicking **API info** for the template you want to send.
307
279
 
308
- #### `reference`
309
- An optional identifier you generate. The `reference` can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.
280
+ ```ruby
281
+ personalisation: {
282
+ address_line_1: 'The Occupier', # mandatory address field
283
+ address_line_2: '123 High Street', # mandatory address field
284
+ postcode: 'SW14 6BH', # mandatory address field
285
+ name: 'John Smith', # field from template
286
+ application_date: '2018-01-01' # field from template
287
+ },
288
+ ```
310
289
 
311
- You can omit this argument if you do not require a reference for the notification.
290
+ #### personalisation (optional)
312
291
 
313
- #### `personalisation`
314
- If the template has placeholders you need to provide their values as a Hash, for example:
292
+ The following parameters in the letter recipient's address are optional:
315
293
 
316
294
  ```ruby
317
- personalisation: {
318
- 'first_name' => 'Amala',
319
- 'reference_number' => '300241',
320
- }
295
+ personalisation: {
296
+ address_line_3: 'Richmond', # optional address field
297
+ address_line_4: 'London', # optional address field
298
+ address_line_5: 'Middlesex', # optional address field
299
+ address_line_6: 'UK', # optional address field
300
+ },
321
301
  ```
322
302
 
323
- You can omit this argument if the template does not contain placeholders and is for email or sms.
303
+ #### reference (optional)
324
304
 
325
- #### `personalisation` (for letters)
326
-
327
- If you are sending a letter, you will need to provide the letter fields in the format `"address_line_#"`, for example:
305
+ A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. For example:
328
306
 
329
307
  ```ruby
330
- personalisation: {
331
- 'address_line_1' => 'The Occupier',
332
- 'address_line_2' => '123 High Street',
333
- 'address_line_3' => 'London',
334
- 'postcode' => 'SW14 6BH',
335
- 'first_name' => 'Amala',
336
- 'reference_number' => '300241',
337
- }
308
+ reference: 'your_reference_string'
338
309
  ```
339
310
 
340
- The fields `address_line_1`, `address_line_2` and `postcode` are required.
311
+ ### Response
341
312
 
342
- </details>
313
+ If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](/ruby.html#send-a-letter-method), the object is named `letterresponse`.
343
314
 
315
+ You can then call different methods on this object to return the requested information.
344
316
 
345
- ## Get the status of one message
317
+ |Method|Information|Type|
318
+ |:---|:---|:---|
319
+ |`letterresponse.id`|Notification UUID|String|
320
+ |`letterresponse.reference`|`reference` argument|String|
321
+ |`letterresponse.content`|- `body`: Letter body<br>- `subject`: Letter subject or main heading|Hash|
322
+ |`letterresponse.template`|Contains the `id`, `version` and `uri` of the template|Hash|
323
+ |`letterresponse.uri`|Notification URL|String|
346
324
 
347
- #### Method
348
325
 
349
- <details>
350
- <summary>
351
- Click here to expand for more information.
352
- </summary>
326
+ ### Error codes
353
327
 
354
- ```ruby
355
- notification = client.get_notification(id) # => Notifications::Client::Notification
356
- ```
328
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code.
357
329
 
358
- </details>
330
+ |error.code|error.message|How to fix|
331
+ |:--- |:---|:---|
332
+ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Cannot send letters with a team api key"`<br>`]}`|Use the correct type of [API key](/ruby.html#api-keys)|
333
+ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Cannot send letters when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"`<br>`}]`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
334
+ |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "personalisation address_line_1 is a required property"`<br>`}]`|Ensure that your template has a field for the first line of the address, refer to [personalisation](/ruby.html#personalisation-required) for more information|
335
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
336
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
337
+ |`429`|`[{`<br>`"error": "RateLimitError",`<br>`"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"`<br>`}]`|Refer to [API rate limits](/ruby.html#api-rate-limits) for more information|
338
+ |`429`|`[{`<br>`"error": "TooManyRequestsError",`<br>`"message": "Exceeded send limits (LIMIT NUMBER) for today"`<br>`}]`|Refer to [service limits](/ruby.html#service-limits) for the limit number|
339
+ |`500`|`[{`<br>`"error": "Exception",`<br>`"message": "Internal server error"`<br>`}]`|Notify was unable to process the request, resend your notification|
359
340
 
341
+ # Get message status
360
342
 
361
- #### Response
343
+ Message status depends on the type of message that you have sent.
362
344
 
363
- If successful a `Notifications::Client::Notification` is returned.
345
+ You can only get the status of messages that are 7 days old or less.
364
346
 
365
- <details>
366
- <summary>
367
- Click here to expand for more information.
368
- </summary>
347
+ ## Status - text and email
369
348
 
370
- ```ruby
371
- notification.id # => uuid for the notification
372
- notification.to # => recipient email address or mobile number
373
- notification.status # => status of the message "created|pending|sent|delivered|permanent-failure|temporary-failure"
374
- notification.created_at # => Date time the message was created
375
- notification.api_key # => uuid for the api key (not the actual api key)
376
- notification.billable_units # => units billable or nil for email
377
- notification.subject # => Subject of email or nil for sms
378
- notification.body # => Body of message
379
- notification.job # => job id if created by a csv or nil if message sent via api
380
- notification.notification_type # => sms | email
381
- notification.service # => uuid for service
382
- notification.sent_at # => Date time the message is sent to the provider or nil if status = "created"
383
- notification.sent_by # => Name of the provider that sent the message or nil if status = "created"
384
- notification.template # => Hash containing template id, name, version, template type sms|email
385
- notification.template_version # Template version number
386
- notification.reference # => reference of the email or nil for sms
387
- notification.updated_at # => Date time that the notification was last updated
388
- ```
389
- Otherwise a `Notification::Client::RequestError` is raised
390
-
391
- |`error.code`|`error.message`|
349
+ |Status|Information|
392
350
  |:---|:---|
393
- |`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
394
- |`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is not a valid UUID"`<br>`}]`|
351
+ |Created|The message is queued to be sent to the provider. The notification usually remains in this state for a few seconds.|
352
+ |Sending|The message is queued to be sent by the provider to the recipient, and GOV.UK Notify is waiting for delivery information.|
353
+ |Delivered|The message was successfully delivered.|
354
+ |Failed|This covers all failure statuses:<br>- `permanent-failure` - "The provider was unable to deliver message, email or phone number does not exist; remove this recipient from your list"<br>- `temporary-failure` - "The provider was unable to deliver message, email inbox was full or phone was turned off; you can try to send the message again"<br>- `technical-failure` - "Notify had a technical failure; you can try to send the message again"|
395
355
 
396
- </details>
356
+ ## Status - text only
397
357
 
398
- #### Arguments
399
-
400
- <details>
401
- <summary>
402
- Click here to expand for more information.
403
- </summary>
404
-
405
- ##### `id`
358
+ |Status|Information|
359
+ |:---|:---|
360
+ |Pending|GOV.UK Notify received a callback from the provider but the device has not yet responded. Another callback from the provider determines the final status of the notification.|
361
+ |Sent|The text message was delivered internationally. This only applies to text messages sent to non-UK phone numbers. GOV.UK Notify may not receive additional status updates depending on the recipient's country and telecoms provider.|
406
362
 
407
- The ID of the notification.
363
+ ## Status - letter
408
364
 
409
- </details>
365
+ |Status|information|
366
+ |:---|:---|
367
+ |Failed|The only failure status that applies to letters is `technical-failure`. GOV.UK Notify had an unexpected error while sending to our printing provider.|
368
+ |Accepted|GOV.UK Notify is printing and posting the letter.|
369
+ |Received|The provider has received the letter to deliver.|
410
370
 
411
- ## Get the status of all messages
371
+ ## Get the status of one message
412
372
 
413
- #### Method
373
+ You can only get the status of messages that are 7 days old or less.
414
374
 
415
- <details>
416
- <summary>
417
- Click here to expand for more information.
418
- </summary>
375
+ ### Method
419
376
 
420
377
  ```ruby
421
- # See section below for a description of the arguments.
422
- # This will return 250 of the most recent messages if `older_than` is omitted, the following 250 messages can be accessed through the hash `notifications.links["next"]`
423
- args = {
424
- 'template_type' => 'sms',
425
- 'status' => 'failed',
426
- 'reference' => 'your reference string'
427
- 'older_than' => 'e194efd1-c34d-49c9-9915-e4267e01e92e' # => Notifications::Client::Notification
428
- }
429
- notifications = client.get_notifications(args)
378
+ response = client.get_notification(id)
430
379
  ```
431
380
 
432
- </details>
381
+ ### Arguments
382
+
383
+ #### id (required)
384
+
385
+ The ID of the notification. You can find the notification ID in the response to the [original notification method call](/ruby.html#response).
386
+
387
+ You can also find it in your [GOV.UK Notify Dashboard](https://www.notifications.service.gov.uk).
388
+
389
+ 1. Sign into GOV.UK Notify and select __Dashboard__.
390
+ 1. Select either __emails sent__, __text messages sent__, or __letters sent__.
391
+ 1. Select the relevant notification.
392
+ 1. Copy the notification ID from the end of the page URL, for example `https://www.notifications.service.gov.uk/services/af90d4cb-ae88-4a7c-a197-5c30c7db423b/notification/ID`.
393
+
394
+ ### Response
395
+
396
+ If the request to the client is successful, the client returns a `Notifications::Client::Notification` object. In the example shown in the [Method section](/ruby.html#get-the-status-of-one-message-method), the object is named `response`.
397
+
398
+ You can then call different methods on this object to return the requested information.
399
+
400
+ |Method|Information|Type|
401
+ |:---|:---|:---|
402
+ |`response.id`|Notification UUID|String|
403
+ |`response.reference`| String supplied in `reference` argument|String|
404
+ |`response.email_address`|Recipient email address (email only)|String|
405
+ |`response.phone_number`|Recipient phone number (SMS only)|String|
406
+ |`response.line_1`|Recipient address line 1 of the address (letter only)|String|
407
+ |`response.line_2`|Recipient address line 2 of the address (letter only)|String|
408
+ |`response.line_3`|Recipient address line 3 of the address (letter only)|String|
409
+ |`response.line_4`|Recipient address line 4 of the address (letter only)|String|
410
+ |`response.line_5`|Recipient address line 5 of the address (letter only)|String|
411
+ |`response.line_6`|Recipient address line 6 of the address (letter only)|String|
412
+ |`response.postcode`|Recipient postcode (letter only)|String|
413
+ |`response.type`|Type of notification sent (sms, email or letter)|String|
414
+ |`response.status`|Notification status (sending / delivered / permanent-failure / temporary-failure / technical-failure)|String|
415
+ |`response.template`|Template UUID|String|
416
+ |`response.body`|Notification body|String|
417
+ |`response.subject`|Notification subject (email and letter)|String|
418
+ |`response.sent_at`|Date and time notification sent to provider|String|
419
+ |`response.created_at`|Date and time notification created|String|
420
+ |`response.completed_at`|Date and time notification delivered or failed|String|
421
+ |`response.created_by_name`|Name of sender if notification sent manually|String|
433
422
 
423
+ ### Error codes
434
424
 
435
- #### Response
425
+ If the request is not successful, the client returns a `Notification::Client::RequestError` and an error code:
436
426
 
437
- If the request is successful a `Notifications::Client::NotificationsCollection` is returned.
427
+ |error.code|error.message|How to fix|
428
+ |:---|:---|:---|
429
+ |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "id is not a valid UUID"`<br>`}]`|Check the notification ID|
430
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
431
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
432
+ |`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|Check the notification ID. This error occurs if the notification is more than 7 days old.|
438
433
 
439
- <details>
440
- <summary>
441
- Click here to expand for more information.
442
- </summary>
434
+ ## Get the status of multiple messages
435
+
436
+ This API call returns one page of up to 250 messages and statuses. You can get either the most recent messages, or get older messages by specifying a particular notification ID in the `older_than` argument.
437
+
438
+ You can only get messages that are 7 days old or less.
439
+
440
+ ### Method
443
441
 
444
442
  ```ruby
445
- notifications.links # => Hash containing current => "/notifications?template_type=sms&status=delivered"
446
- # next => "/notifications?older_than=last_id_in_list&template_type=sms&status=delivered"
447
- notifications.collection # => [] (array of notification objects)
443
+ args = {
444
+ template_type: 'sms',
445
+ status: 'failed',
446
+ reference: 'your_reference_string'
447
+ older_than: 'e194efd1-c34d-49c9-9915-e4267e01e92e'
448
+ }
449
+ response = client.get_notifications(args)
448
450
  ```
449
451
 
450
- Otherwise the client will raise a `Notifications::Client::RequestError`:
452
+ You can leave out the `older_than` argument to get the 250 most recent messages.
451
453
 
452
- |`error.status_code`|`error.message`|
453
- |:---|:---|
454
- |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "bad status is not one of [created, sending, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure]"`<br>`}]`|
455
- |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "Apple is not one of [sms, email, letter]"`<br>`}]`|
454
+ To get older messages, pass the ID of an older notification into the `older_than` argument. This returns the next 250 oldest messages from the specified notification ID.
456
455
 
457
- </details>
456
+ ### Arguments
458
457
 
459
- #### Arguments
458
+ You can leave out these arguments to ignore these filters.
460
459
 
461
- Omit the argument Hash if you do not want to filter the results.
460
+ #### status (optional)
462
461
 
463
- <details>
464
- <summary>
465
- Click here to expand for more information.
466
- </summary>
462
+ | status | description | text | email | letter |
463
+ |:--- |:--- |:--- |:--- |:--- |
464
+ |`created` |The message is queued to be sent to the provider|Yes|Yes||
465
+ |`sending` |The message is queued to be sent by the provider to the recipient|Yes|Yes||
466
+ |`delivered`|The message was successfully delivered|Yes|Yes||
467
+ |`pending`|GOV.UK Notify received a callback from the provider but the device has not yet responded|Yes|||
468
+ |`sent`|The text message was delivered internationally|Yes|Yes||
469
+ |`failed`|This returns all failure statuses:<br>- `permanent-failure`<br>- `temporary-failure`<br>- `technical-failure`|Yes|Yes||
470
+ |`permanent-failure`|The provider was unable to deliver message, email or phone number does not exist; remove this recipient from your list|Yes|Yes||
471
+ |`temporary-failure`|The provider was unable to deliver message, email inbox was full or phone was turned off; you can try to send the message again|Yes|Yes||
472
+ |`technical-failure`|Email / Text: Notify had a technical failure; you can try to send the message again. <br><br>Letter: Notify had an unexpected error while sending to our printing provider. <br><br>You can leave out this argument to ignore this filter.|Yes|Yes||
473
+ |`accepted`|Notify is printing and posting the letter|||Yes|
474
+ |`received`|The provider has received the letter to deliver|||Yes|
467
475
 
468
- ##### `template_type`
476
+ #### templateType (optional)
469
477
 
470
- If omitted all messages are returned. Otherwise you can filter by:
478
+ You can filter by:
471
479
 
472
480
  * `email`
473
481
  * `sms`
474
482
  * `letter`
475
483
 
476
- You can omit this argument to ignore the filter.
484
+ #### reference (optional)
477
485
 
478
- ##### `status`
486
+ A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. For example:
479
487
 
480
- You can filter by:
481
-
482
- * `sending` - the message is queued to be sent by the provider.
483
- * `delivered` - the message was successfully delivered.
484
- * `failed` - this will return all failure statuses `permanent-failure`, `temporary-failure` and `technical-failure`.
485
- * `permanent-failure` - the provider was unable to deliver message, email or phone number does not exist; remove this recipient from your list.
486
- * `temporary-failure` - the provider was unable to deliver message, email box was full or the phone was turned off; you can try to send the message again.
487
- * `technical-failure` - Notify had a technical failure; you can try to send the message again.
488
+ ```ruby
489
+ reference: 'your_reference_string'
490
+ ```
488
491
 
489
- You can omit this argument to ignore the filter.
492
+ #### older_than (optional)
490
493
 
491
- ##### `reference`
494
+ Input the ID of a notification into this argument. If you use this argument, the client returns the next 250 received notifications older than the given ID. For example:
492
495
 
493
- This is the `reference` you gave at the time of sending the notification. The `reference` can be a unique identifier for the notification or an identifier for a batch of notifications.
496
+ ```ruby
497
+ older_than: 'e194efd1-c34d-49c9-9915-e4267e01e92e'
498
+ ```
494
499
 
495
- You can omit this argument to ignore the filter.
500
+ If you leave out this argument, the client returns the most recent 250 notifications.
496
501
 
502
+ The client only returns notifications that are 7 days old or less. If the notification specified in this argument is older than 7 days, the client returns an empty response.
497
503
 
498
- ##### `older_than`
499
- You can get the notifications older than a given `Notification.id`.
500
- You can omit this argument to ignore this filter.
504
+ ### Response
501
505
 
502
- </details>
506
+ If the request to the client is successful, the client returns a `Notifications::Client::NotificationsCollection` object. In the example shown in the [Method section](/ruby.html#get-the-status-of-multiple-messages-method), the object is named `response`.
503
507
 
508
+ You must then call either the `.links` method or the `.collection` method on this object.
504
509
 
510
+ |Method|Information|
511
+ |:---|:---|
512
+ |`response.links`|Returns a hash linking to the requested notifications (limited to 250)|
513
+ |`response.collection`|Returns an array of the required notifications|
514
+
515
+ If you call the `collection` method on this object to return a notification array, you must then call the following methods on the notifications in this array to return information on those notifications:
516
+
517
+ |Method|Information|Type|
518
+ |:---|:---|:---|
519
+ |`response.id`|Notification UUID|String|
520
+ |`response.reference`| String supplied in `reference` argument|String|
521
+ |`response.email_address`|Recipient email address (email only)|String|
522
+ |`response.phone_number`|Recipient phone number (SMS only)|String|
523
+ |`response.line_1`|Recipient address line 1 of the address (letter only)|String|
524
+ |`response.line_2`|Recipient address line 2 of the address (letter only)|String|
525
+ |`response.line_3`|Recipient address line 3 of the address (letter only)|String|
526
+ |`response.line_4`|Recipient address line 4 of the address (letter only)|String|
527
+ |`response.line_5`|Recipient address line 5 of the address (letter only)|String|
528
+ |`response.line_6`|Recipient address line 6 of the address (letter only)|String|
529
+ |`response.postcode`|Recipient postcode (letter only)|String|
530
+ |`response.type`|Type of notification sent (sms, email or letter)|String|
531
+ |`response.status`|Notification status (sending / delivered / permanent-failure / temporary-failure / technical-failure)|String|
532
+ |`response.template`|Template UUID|String|
533
+ |`response.body`|Notification body|String|
534
+ |`response.subject`|Notification subject (email and letter)|String|
535
+ |`response.sent_at`|Date and time notification sent to provider|String|
536
+ |`response.created_at`|Date and time notification created|String|
537
+ |`response.completed_at`|Date and time notification delivered or failed|String|
538
+ |`response.created_by_name`|Name of sender if notification sent manually|String|
539
+
540
+ If the notification specified in the `older_than` argument is older than 7 days, the client returns an empty `collection` response.
541
+
542
+ ### Error codes
543
+
544
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code.
545
+
546
+ |error.code|error.message|How to fix|
547
+ |:---|:---|:---|
548
+ |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "bad status is not one of [created, sending, sent, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure, accepted, received]"`<br>`}]`|Contact the Notify team|
549
+ |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "Template type is not one of [sms, email, letter]"`<br>`}]`|Contact the Notify team|
550
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
551
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
552
+
553
+ # Get a template
505
554
 
506
555
  ## Get a template by ID
507
556
 
508
- #### Method
509
-
510
- This will return the latest version of the template. Use [getTemplateVersion](#get-a-template-by-id-and-version) to retrieve a specific template version.
557
+ ### Method
511
558
 
512
- <details>
513
- <summary>
514
- Click here to expand for more information.
515
- </summary>
559
+ This returns the latest version of the template.
516
560
 
517
561
  ```ruby
518
- template = client.get_template_by_id(id)
562
+ response = client.get_template_by_id(id)
519
563
  ```
520
564
 
521
- </details>
565
+ ### Arguments
522
566
 
567
+ #### id (required)
523
568
 
524
- #### Response
569
+ The ID of the template. Sign into GOV.UK Notify and go to the __Templates__ page to find this. For example:
525
570
 
526
- <details>
527
- <summary>
528
- Click here to expand for more information.
529
- </summary>
530
-
531
- ```Ruby
532
- template.id # => uuid for the template
533
- template.type # => type of template one of email|sms|letter
534
- template.created_at # => date and time the template was created
535
- template.updated_at # => date and time the template was last updated, may be null if version 1
536
- template.created_by # => email address of the person that created the template
537
- template.version # => version of the template
538
- template.body # => content of the template
539
- template.subject # => subject for email templates, will be empty for other template types
571
+ ```
572
+ 'f33517ff-2a88-4f6e-b855-c550268ce08a'
540
573
  ```
541
574
 
542
- Otherwise the client will raise a `Notifications::Client::RequestError`.
543
-
544
- </details>
545
-
575
+ ### Response
546
576
 
547
- #### Arguments
577
+ If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](/ruby.html#get-a-template-by-id-method), the object is named `response`.
548
578
 
549
- <details>
550
- <summary>
551
- Click here to expand for more information.
552
- </summary>
579
+ You can then call different methods on this object to return the requested information.
553
580
 
554
- |`error.code`|`error.message`|
555
- |:---|:---|
556
- |`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
557
- |`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is is not a valid UUID"`<br>`}]`|
581
+ |Method|Information|Type|
582
+ |:---|:---|:---|
583
+ |`response.id`|Template UUID|String|
584
+ |`response.name`|Template name|String|
585
+ |`response.type`|Template type (email/sms/letter)|String|
586
+ |`response.created_at`|Date and time template created|String|
587
+ |`response.updated_at`|Date and time template last updated (may be nil if version 1)|String|
588
+ |`response.created_by`|Email address of person that created the template|String|
589
+ |`response.version`|Template version|String|
590
+ |`response.body`|Template content|String|
591
+ |`response.subject`|Template subject (email and letter)|String|
558
592
 
559
- ##### `id`
560
- The template id is visible on the template page in the application.
593
+ ### Error codes
561
594
 
562
- </details>
595
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code:
563
596
 
597
+ |error.code|error.message|How to fix|
598
+ |:---|:---|:---|
599
+ |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "id is not a valid UUID"`<br>`}]`|Check the notification ID|
600
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
601
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
602
+ |`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No Result Found"`<br>`}]`|Check your [template ID](/ruby.html#get-a-template-by-id-arguments-id-required)|
564
603
 
565
604
  ## Get a template by ID and version
566
605
 
567
- #### Method
606
+ ### Method
568
607
 
569
- This will return the template for the given id and version.
570
- <details>
571
- <summary>
572
- Click here to expand for more information.
573
- </summary>
608
+ This returns the latest version of the template.
574
609
 
575
610
  ```ruby
576
- Template template = client.get_template_version(id, version)
611
+ response = client.get_template_version(id, version)
577
612
  ```
578
613
 
579
- </details>
580
-
614
+ ### Arguments
581
615
 
582
- #### Response
616
+ #### id (required)
583
617
 
584
- <details>
585
- <summary>
586
- Click here to expand for more information.
587
- </summary>
618
+ The ID of the template. Sign in to GOV.UK Notify and go to the __Templates__ page to find this. For example:
588
619
 
589
-
590
- ```Ruby
591
- template.id # => uuid for the template
592
- template.type # => type of template one of email|sms|letter
593
- template.created_at # => date and time the template was created
594
- template.updated_at # => date and time the template was last updated, may be null if version 1
595
- template.created_by # => email address of the person that created the template
596
- template.version # => version of the template
597
- template.body # => content of the template
598
- template.subject # => subject for email templates, will be empty for other template types
620
+ ```ruby
621
+ 'f33517ff-2a88-4f6e-b855-c550268ce08a'
599
622
  ```
600
623
 
601
- Otherwise the client will raise a `Notifications::Client::RequestError`.
624
+ #### version (required)
602
625
 
603
- |`error.code`|`error.message`|
604
- |:---|:---|
605
- |`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
606
- |`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is is not a valid UUID"`<br>`}]`|
607
-
608
- </details>
626
+ The version number of the template.
609
627
 
628
+ ### Response
610
629
 
611
- #### Arguments
630
+ If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](/ruby.html#get-a-template-by-id-and-version-method), the object is named `response`.
612
631
 
613
- <details>
614
- <summary>
615
- Click here to expand for more information.
616
- </summary>
632
+ You can then call different methods on this object to return the requested information.
617
633
 
618
- #### `id`
619
- The template id is visible on the template page in the application.
634
+ |Method|Information|Type|
635
+ |:---|:---|:---|
636
+ |`response.id`|Template UUID|String|
637
+ |`response.name`|Template name|String|
638
+ |`response.type`|Template type (email/sms/letter)|String|
639
+ |`response.created_at`|Date and time template created|String|
640
+ |`response.updated_at`|Date and time template last updated (may be nil if it is the first version)|String|
641
+ |`response.created_by`|Email address of person that created the template|String|
642
+ |`response.version`|Template version|String|
643
+ |`response.body`|Template content|String|
644
+ |`response.subject`|Template subject (email and letter)|String|
620
645
 
621
- #### `version`
622
- A history of the template is kept. There is a link to `See previous versions` on the template page in the application.
646
+ ### Error codes
623
647
 
624
- </details>
648
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code:
625
649
 
650
+ |error.code|error.message|How to fix|
651
+ |:---|:---|:---|
652
+ |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "id is not a valid UUID"`<br>`}]`|Check the notification ID|
653
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
654
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
655
+ |`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No Result Found"`<br>`}]`|Check your [template ID](/ruby.html#get-a-template-by-id-and-version-arguments-id-required) and [version](/ruby.html#version-required)|
626
656
 
627
657
  ## Get all templates
628
658
 
629
- #### Method
659
+ ### Method
630
660
 
631
- This will return the latest version of each template for your service.
632
-
633
- <details>
634
- <summary>
635
- Click here to expand for more information.
636
- </summary>
661
+ This returns the latest version of all templates inside a collection object.
637
662
 
638
663
  ```ruby
639
664
  args = {
640
- 'template_type' => 'sms'
665
+ type: 'sms'
641
666
  }
642
- templates = client.get_all_templates(args)
667
+ response = client.get_all_templates(args)
643
668
  ```
644
669
 
670
+ ### Arguments
645
671
 
646
- </details>
672
+ #### type (optional)
647
673
 
674
+ If you do not use `type`, the client returns all templates. Otherwise you can filter by:
648
675
 
649
- #### Response
676
+ - `email`
677
+ - `sms`
678
+ - `letter`
650
679
 
651
- <details>
652
- <summary>
653
- Click here to expand for more information.
654
- </summary>
680
+ ### Response
655
681
 
656
- ```ruby
657
- TemplateCollection templates;
658
- ```
659
- If the response is successful, a TemplateCollection is returned.
682
+ If the request to the client is successful, the client returns a `Notifications::Client::TemplateCollection` object. In the example shown in the [Method section](/ruby.html#get-all-templates-method), the object is named `response`.
660
683
 
661
- If no templates exist for a template type or there no templates for a service, the templates list will be empty.
684
+ You must then call the `.collection` method on this object to return an array of the required templates.
662
685
 
663
- Otherwise the client will raise a `Notifications::Client::RequestError`.
686
+ Once the client has returned a template array, you must then call the following methods on the templates in this array to return information on those templates.
664
687
 
665
- </details>
688
+ |Method|Information|Type|
689
+ |:---|:---|:---|
690
+ |`response.id`|Template UUID|String|
691
+ |`response.name`|Template name|String|
692
+ |`response.type`|Template type (email/sms/letter)|String|
693
+ |`response.created_at`|Date and time template created|String|
694
+ |`response.updated_at`|Date and time template last updated (may be nil if it is the first version)|String|
695
+ |`response.created_by`|Email address of person that created the template|String|
696
+ |`response.version`|Template version|String|
697
+ |`response.body`|Template content|String|
698
+ |`response.subject`|Template subject (email and letter)|String|
666
699
 
700
+ If no templates exist for a template type or there no templates for a service, the templates array will be empty.
667
701
 
668
- #### Arguments
702
+ ### Error codes
669
703
 
670
- <details>
671
- <summary>
672
- Click here to expand for more information.
673
- </summary>
704
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code:
674
705
 
675
- ##### `template_type`
676
- If omitted all templates are returned. Otherwise you can filter by:
706
+ |error.code|error.message|How to fix|
707
+ |:---|:---|:---|
708
+ |`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "Template type is not one of [sms, email, letter]"`<br>`}]`|Contact the Notify team|
677
709
 
678
- * `email`
679
- * `sms`
680
- * `letter`
710
+ ## Generate a preview template
681
711
 
682
- </details>
712
+ ### Method
683
713
 
714
+ This generates a preview version of a template.
684
715
 
685
- ## Generate a preview template
716
+ ```ruby
717
+ response = client.generate_template_preview(id)
718
+ ```
686
719
 
687
- #### Method
720
+ The parameters in the personalisation argument must match the placeholder fields in the actual template. The API notification client ignores any extra fields in the method.
688
721
 
689
- This will return the contents of a template with the placeholders replaced with the given personalisation.
722
+ ### Arguments
690
723
 
691
- <details>
692
- <summary>
693
- Click here to expand for more information.
694
- </summary>
724
+ #### id (required)
695
725
 
726
+ The ID of the template. Sign into GOV.UK Notify and go to the __Templates__ page. For example:
696
727
 
697
728
  ```ruby
698
- templatePreview = client.generate_template_preview(id,
699
- personalisation: {
700
- name: "name",
701
- year: "2016",
702
- })
729
+ 'f33517ff-2a88-4f6e-b855-c550268ce08a'
703
730
  ```
704
731
 
705
- </details>
732
+ #### personalisation (optional)
706
733
 
734
+ If a template has placeholder fields for personalised information such as name or application date, you must provide their values in a hash. For example:
707
735
 
708
- #### Response
736
+ ```ruby
737
+ personalisation: {
738
+ name: "John Smith",
739
+ ID: "300241",
740
+ }
741
+ ```
709
742
 
710
- <details>
711
- <summary>
712
- Click here to expand for more information.
713
- </summary>
743
+ You can leave out this argument if a template does not have any placeholder fields for personalised information.
714
744
 
715
- ```Ruby
716
- template.id # => uuid for the template
717
- template.version # => version of the template
718
- template.body # => content of the template
719
- template.subject # => subject for email templates, will be empty for other template types
720
- ```
721
- Otherwise a `Notifications::Client::RequestError` is thrown.
745
+ ### Response
722
746
 
723
- |`error.code`|`error.message`|
724
- |:---|:---|
725
- |`404`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|
726
- |`404`|`[{`<br>`"error": "ValidationError",`<br>`"message": "is is not a valid UUID"`<br>`}]`|
747
+ If the request to the client is successful, the client returns a `Notifications::Client::TemplatePreview` object. In the example shown in the [Method section](/ruby.html#generate-a-preview-template-method), the object is named `response`.
727
748
 
728
- </details>
749
+ You can then call different methods on this object to return the requested information.
729
750
 
751
+ |Method|Information|Type|
752
+ |:---|:---|:---|
753
+ |`response.id`|Template UUID|String|
754
+ |`response.version`|Template version|String|
755
+ |`response.body`|Template content|String|
756
+ |`response.subject`|Template subject (email and letter)|String|
757
+ |`response.type`|Template type (sms/email/letter)|String|
730
758
 
731
- #### Arguments
759
+ ### Error codes
732
760
 
733
- <details>
734
- <summary>
735
- Click here to expand for more information.
736
- </summary>
761
+ If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code:
737
762
 
738
- ##### `id`
739
- The template id is visible on the template page in the application.
763
+ |error.code|error.message|How to fix|
764
+ |:---|:---|:---|
765
+ |`400`|`[{`<br>`"error": "BadRequestError",`<br>`"message": "Missing personalisation: [PERSONALISATION FIELD]"`<br>`}]`|Check that the personalisation arguments in the method match the placeholder fields in the template|
766
+ |`400`|`[{`<br>`"error": "NoResultFound",`<br>`"message": "No result found"`<br>`}]`|Check the [template ID](/ruby.html#generate-a-preview-template-arguments-id-required)|
767
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Error: Your system clock must be accurate to within 30 seconds"`<br>`}]`|Check your system clock|
768
+ |`403`|`[{`<br>`"error": "AuthError",`<br>`"message": "Invalid token: signature, api token not found"`<br>`}]`|Use the correct API key. Refer to [API keys](/ruby.html#api-keys) for more information|
740
769
 
741
- ##### `personalisation`
742
- If a template has placeholders, you need to provide their values. `personalisation` can be an empty or null in which case no placeholders are provided for the notification.
770
+ # Get received text messages
743
771
 
744
- </details>
772
+ This API call returns one page of up to 250 received text messages. You can get either the most recent messages, or get older messages by specifying a particular notification ID in the `older_than` argument.
745
773
 
746
- ## Get received texts
747
- #### Method
774
+ You can only get the status of messages that are 7 days old or less.
748
775
 
749
- <details>
750
- <summary>
751
- Click here to expand for more information.
752
- </summary>
776
+ ### Method
753
777
 
754
778
  ```ruby
755
- # See section below for a description of the arguments.
756
- # This will return 250 of the most recent messages if `older_than` is omitted, the following 250 messages can be accessed through the hash `received_texts.links["next"]`
757
779
  args = {
758
- 'older_than' => 'e194efd1-c34d-49c9-9915-e4267e01e92e' # => Notifications::Client::ReceivedText
780
+ older_than: 'e194efd1-c34d-49c9-9915-e4267e01e92e'
759
781
  }
760
- received_texts = client.get_received_texts(args)
782
+ response = client.get_received_texts(args)
761
783
  ```
762
784
 
763
- </details>
764
-
785
+ To get older messages, pass the ID of an older notification into the `older_than` argument. This returns the next oldest messages from the specified notification ID.
765
786
 
766
- #### Response
787
+ If you leave out the `older_than` argument, the client returns the most recent 250 notifications.
767
788
 
768
- If the request is successful a `Notifications::Client::ReceivedTextCollection` is returned.
789
+ ### Arguments
769
790
 
770
- <details>
771
- <summary>
772
- Click here to expand for more information.
773
- </summary>
791
+ #### older_than (optional)
774
792
 
775
- `ReceivedTextCollection` -
793
+ Input the ID of a received text message into this argument. If you use this argument, the client returns the next 250 received text messages older than the given ID. For example:
776
794
 
777
795
  ```ruby
778
- received_texts.links # => Hash containing current => "/v2/received-text-messages"
779
- # next => "/v2/received-text-messages?older_than=last_id_in_list"
780
- received_texts.collection # => [] (array of ReceivedText objects)
796
+ older_than: '8e222534-7f05-4972-86e3-17c5d9f894e2'
781
797
  ```
782
798
 
783
- `ReceivedText` -
799
+ If you leave out the `older_than` argument, the client returns the most recent 250 notifications.
784
800
 
785
- ```ruby
786
- received_text.id # => uuid for the received text
787
- received_text.created_at # => created_at of the received text
788
- received_text.content # => content of the received text
789
- received_text.notify_number # => number received text was sent to
790
- received_text.service_id # => service id of the received text
791
- received_text.user_number # => number received text was sent from
801
+ The client only returns notifications that are 7 days old or less. If the notification specified in this argument is older than 7 days, the client returns an empty `collection` response.
792
802
 
793
- ```
803
+ ### Response
794
804
 
795
- </details>
805
+ If the request to the client is successful, the client returns a `Notifications::Client::ReceivedTextCollection` object. In the example shown in the [Method section](/ruby.html#get-received-text-messages-method), the object is named `response`.
796
806
 
797
- #### Arguments
807
+ You must then call either the `.links` method or the `.collection` method on this object.
798
808
 
799
- Omit the argument Hash if you do not want to filter the results.
809
+ |Method|Information|
810
+ |:---|:---|
811
+ |`response.links`|Returns a hash linking to the requested texts (limited to 250)|
812
+ |`response.collection`|Returns an array of the required texts|
800
813
 
801
- <details>
802
- <summary>
803
- Click here to expand for more information.
804
- </summary>
814
+ If you call the `collection` method on this object to return an array, you must then call the following methods on the received texts in this array to return information on those texts:
805
815
 
806
- ##### `older_than`
807
- You can get the notifications older than a given `received_text.id`.
808
- You can omit this argument to ignore this filter.
816
+ |Method|Information|Type|
817
+ |:---|:---|:---|
818
+ |`response.id`|Received text UUID|String|
819
+ |`response.created_at`|Date and time of received text|String|
820
+ |`response.content`|Received text content|String|
821
+ |`response.notify_number`|Number that received text was sent to|String|
822
+ |`response.service_id`|Received text service ID|String|
823
+ |`response.user_number`|Number that received text was sent from|String|
809
824
 
810
- </details>
825
+ If the notification specified in the `older_than` argument is older than 7 days, the client returns an empty `collection` response.