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.
- checksums.yaml +5 -5
- data/.github/PULL_REQUEST_TEMPLATE.md +1 -1
- data/CHANGELOG.md +5 -0
- data/CONTRIBUTING.md +39 -0
- data/DOCUMENTATION.md +544 -529
- data/README.md +6 -812
- data/bin/test_client.rb +1 -0
- data/lib/notifications/client/response_template.rb +1 -0
- data/lib/notifications/client/version.rb +1 -1
- metadata +4 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: a7ebfa7945a861630914de5251f291bb5fac91f6d594b819364ca745072e6129
|
4
|
+
data.tar.gz: 8374e982bd9a519d85446dae5a4cb4808308ba80443f431ec1841f7ddbea54cb
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: eb25a50ca0b7b0571f6908711ede2a3212fad478f7243538a88acc8c6bd7254eec1d670ba54dd6953281bf353d85b94ca05ecd99aa9de89bb4386306c74bdb18
|
7
|
+
data.tar.gz: 1e94b34627e331bb61e4e549efec4b8a6a50318665d3639b75b021f0d5b080f40ec7d73507d21b73c87db686d4f934016287ab65fd1ed0c0a92280eca91571d8
|
@@ -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
|
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
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
|
-
#
|
1
|
+
# Ruby client documentation
|
2
2
|
|
3
|
-
This documentation is for developers interested in using
|
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
|
-
|
5
|
+
# Set up the client
|
6
6
|
|
7
|
-
##
|
7
|
+
## Install the client
|
8
8
|
|
9
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
28
|
+
# Send a message
|
40
29
|
|
41
|
-
|
30
|
+
You can use GOV.UK Notify to send text messages, emails or letters.
|
42
31
|
|
43
|
-
|
32
|
+
## Send a text message
|
44
33
|
|
45
|
-
|
46
|
-
<summary>
|
47
|
-
Click here to expand for more information.
|
48
|
-
</summary>
|
34
|
+
### Method
|
49
35
|
|
50
36
|
```ruby
|
51
|
-
|
52
|
-
phone_number:
|
53
|
-
template_id:
|
54
|
-
|
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
|
-
|
43
|
+
### Arguments
|
64
44
|
|
65
|
-
####
|
45
|
+
#### phone_number (required)
|
66
46
|
|
67
|
-
|
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
|
-
|
50
|
+
phone_number:"+447900900123"
|
51
|
+
```
|
75
52
|
|
76
|
-
|
77
|
-
|
78
|
-
|
79
|
-
|
80
|
-
|
81
|
-
|
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
|
-
|
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
|
-
|
90
|
-
|
91
|
-
|
92
|
-
|
93
|
-
|
94
|
-
|
65
|
+
```ruby
|
66
|
+
personalisation: {
|
67
|
+
name: "John Smith",
|
68
|
+
ID: "300241",
|
69
|
+
}
|
70
|
+
```
|
95
71
|
|
96
|
-
|
72
|
+
You can leave out this argument if a template does not have any placeholder fields for personalised information.
|
97
73
|
|
98
|
-
####
|
74
|
+
#### reference (optional)
|
99
75
|
|
100
|
-
|
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
|
-
|
78
|
+
```ruby
|
79
|
+
reference: "your_reference_string"
|
80
|
+
```
|
106
81
|
|
107
|
-
|
82
|
+
You can leave out this argument if you do not have a reference.
|
108
83
|
|
109
|
-
|
84
|
+
#### sms_sender_id (optional)
|
110
85
|
|
111
|
-
|
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
|
-
|
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
|
-
|
93
|
+
You can then either:
|
116
94
|
|
117
|
-
|
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
|
-
|
99
|
+
For example:
|
122
100
|
|
123
|
-
```
|
124
|
-
|
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
|
-
|
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
|
121
|
+
If you are using the [test API key](/ruby.html#test), all your messages come back with a `delivered` status.
|
134
122
|
|
135
|
-
|
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
|
-
|
127
|
+
If the request is not successful, the client returns a `Notifications::Client::RequestError` and an error code.
|
139
128
|
|
140
|
-
|
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
|
-
|
143
|
-
|
144
|
-
|
145
|
-
</summary>
|
139
|
+
## Send an email
|
140
|
+
|
141
|
+
### Method
|
146
142
|
|
147
143
|
```ruby
|
148
|
-
|
149
|
-
email_address:
|
150
|
-
template_id:
|
151
|
-
|
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
|
-
|
150
|
+
### Arguments
|
161
151
|
|
152
|
+
#### email_address (required)
|
162
153
|
|
163
|
-
|
154
|
+
The email address of the recipient. For example:
|
164
155
|
|
165
|
-
|
156
|
+
```ruby
|
157
|
+
email_address: "sender@something.com"
|
158
|
+
```
|
159
|
+
|
160
|
+
#### template_id (required)
|
166
161
|
|
167
|
-
|
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
|
-
|
165
|
+
template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a"
|
166
|
+
```
|
174
167
|
|
175
|
-
|
176
|
-
|
177
|
-
|
178
|
-
|
179
|
-
|
180
|
-
|
181
|
-
|
182
|
-
|
183
|
-
|
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
|
-
|
179
|
+
You can leave out this argument if a template does not have any placeholder fields for personalised information.
|
187
180
|
|
188
|
-
|
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
|
-
|
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
|
-
|
189
|
+
You can leave out this argument if you do not have a reference.
|
199
190
|
|
200
|
-
|
201
|
-
<summary>
|
202
|
-
Click here to expand for more information.
|
203
|
-
</summary>
|
191
|
+
#### email_reply_to_id (optional)
|
204
192
|
|
205
|
-
|
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
|
-
|
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
|
-
|
202
|
+
For example:
|
213
203
|
|
214
|
-
|
204
|
+
```ruby
|
205
|
+
email_reply_to_id: '8e222534-7f05-4972-86e3-17c5d9f894e2'
|
206
|
+
```
|
215
207
|
|
216
|
-
You can
|
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
|
-
|
210
|
+
### Response
|
219
211
|
|
220
|
-
|
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
|
-
|
214
|
+
You can then call different methods on this object to return the requested information.
|
223
215
|
|
224
|
-
|
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
|
-
|
224
|
+
### Error codes
|
227
225
|
|
228
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
243
|
-
<summary>
|
244
|
-
Click here to expand for more information.
|
245
|
-
</summary>
|
246
|
+
### Method
|
246
247
|
|
247
248
|
```ruby
|
248
|
-
|
249
|
-
template_id:
|
249
|
+
letterresponse = client.send_letter(
|
250
|
+
template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a",
|
250
251
|
personalisation: {
|
251
|
-
address_line_1: '
|
252
|
-
address_line_2: '
|
253
|
-
|
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
|
-
|
259
|
-
) # => Notifications::Client::ResponseNotification
|
256
|
+
)
|
260
257
|
```
|
261
258
|
|
262
|
-
|
263
|
-
|
264
|
-
|
265
|
-
#### Response
|
259
|
+
### Arguments
|
266
260
|
|
267
|
-
|
261
|
+
#### template_id (required)
|
268
262
|
|
269
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
273
|
+
- `address_line_1`
|
274
|
+
- `address_line_2`
|
275
|
+
- `postcode`
|
299
276
|
|
300
|
-
|
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
|
-
|
309
|
-
|
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
|
-
|
290
|
+
#### personalisation (optional)
|
312
291
|
|
313
|
-
|
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
|
-
|
318
|
-
|
319
|
-
|
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
|
-
|
303
|
+
#### reference (optional)
|
324
304
|
|
325
|
-
|
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
|
-
|
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
|
-
|
311
|
+
### Response
|
341
312
|
|
342
|
-
|
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
|
-
|
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
|
-
|
350
|
-
<summary>
|
351
|
-
Click here to expand for more information.
|
352
|
-
</summary>
|
326
|
+
### Error codes
|
353
327
|
|
354
|
-
|
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
|
-
|
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
|
-
|
343
|
+
Message status depends on the type of message that you have sent.
|
362
344
|
|
363
|
-
|
345
|
+
You can only get the status of messages that are 7 days old or less.
|
364
346
|
|
365
|
-
|
366
|
-
<summary>
|
367
|
-
Click here to expand for more information.
|
368
|
-
</summary>
|
347
|
+
## Status - text and email
|
369
348
|
|
370
|
-
|
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
|
-
|
394
|
-
|
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
|
-
|
356
|
+
## Status - text only
|
397
357
|
|
398
|
-
|
399
|
-
|
400
|
-
|
401
|
-
|
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
|
-
|
363
|
+
## Status - letter
|
408
364
|
|
409
|
-
|
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
|
371
|
+
## Get the status of one message
|
412
372
|
|
413
|
-
|
373
|
+
You can only get the status of messages that are 7 days old or less.
|
414
374
|
|
415
|
-
|
416
|
-
<summary>
|
417
|
-
Click here to expand for more information.
|
418
|
-
</summary>
|
375
|
+
### Method
|
419
376
|
|
420
377
|
```ruby
|
421
|
-
|
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
|
-
|
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
|
-
|
425
|
+
If the request is not successful, the client returns a `Notification::Client::RequestError` and an error code:
|
436
426
|
|
437
|
-
|
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
|
-
|
440
|
-
|
441
|
-
|
442
|
-
|
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
|
-
|
446
|
-
|
447
|
-
|
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
|
-
|
452
|
+
You can leave out the `older_than` argument to get the 250 most recent messages.
|
451
453
|
|
452
|
-
|
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
|
-
|
456
|
+
### Arguments
|
458
457
|
|
459
|
-
|
458
|
+
You can leave out these arguments to ignore these filters.
|
460
459
|
|
461
|
-
|
460
|
+
#### status (optional)
|
462
461
|
|
463
|
-
|
464
|
-
|
465
|
-
|
466
|
-
|
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
|
-
|
476
|
+
#### templateType (optional)
|
469
477
|
|
470
|
-
|
478
|
+
You can filter by:
|
471
479
|
|
472
480
|
* `email`
|
473
481
|
* `sms`
|
474
482
|
* `letter`
|
475
483
|
|
476
|
-
|
484
|
+
#### reference (optional)
|
477
485
|
|
478
|
-
|
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
|
-
|
481
|
-
|
482
|
-
|
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
|
-
|
492
|
+
#### older_than (optional)
|
490
493
|
|
491
|
-
|
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
|
-
|
496
|
+
```ruby
|
497
|
+
older_than: 'e194efd1-c34d-49c9-9915-e4267e01e92e'
|
498
|
+
```
|
494
499
|
|
495
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
562
|
+
response = client.get_template_by_id(id)
|
519
563
|
```
|
520
564
|
|
521
|
-
|
565
|
+
### Arguments
|
522
566
|
|
567
|
+
#### id (required)
|
523
568
|
|
524
|
-
|
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
|
-
|
527
|
-
|
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
|
-
|
543
|
-
|
544
|
-
</details>
|
545
|
-
|
575
|
+
### Response
|
546
576
|
|
547
|
-
|
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
|
-
|
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
|
-
|
555
|
-
|
556
|
-
|`
|
557
|
-
|`
|
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
|
-
|
560
|
-
The template id is visible on the template page in the application.
|
593
|
+
### Error codes
|
561
594
|
|
562
|
-
|
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
|
-
|
606
|
+
### Method
|
568
607
|
|
569
|
-
This
|
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
|
-
|
611
|
+
response = client.get_template_version(id, version)
|
577
612
|
```
|
578
613
|
|
579
|
-
|
580
|
-
|
614
|
+
### Arguments
|
581
615
|
|
582
|
-
####
|
616
|
+
#### id (required)
|
583
617
|
|
584
|
-
|
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
|
-
|
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
|
-
|
624
|
+
#### version (required)
|
602
625
|
|
603
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
619
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
659
|
+
### Method
|
630
660
|
|
631
|
-
This
|
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
|
-
|
665
|
+
type: 'sms'
|
641
666
|
}
|
642
|
-
|
667
|
+
response = client.get_all_templates(args)
|
643
668
|
```
|
644
669
|
|
670
|
+
### Arguments
|
645
671
|
|
646
|
-
|
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
|
-
|
676
|
+
- `email`
|
677
|
+
- `sms`
|
678
|
+
- `letter`
|
650
679
|
|
651
|
-
|
652
|
-
<summary>
|
653
|
-
Click here to expand for more information.
|
654
|
-
</summary>
|
680
|
+
### Response
|
655
681
|
|
656
|
-
|
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
|
-
|
684
|
+
You must then call the `.collection` method on this object to return an array of the required templates.
|
662
685
|
|
663
|
-
|
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
|
-
|
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
|
-
|
702
|
+
### Error codes
|
669
703
|
|
670
|
-
|
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
|
-
|
676
|
-
|
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
|
-
|
679
|
-
* `sms`
|
680
|
-
* `letter`
|
710
|
+
## Generate a preview template
|
681
711
|
|
682
|
-
|
712
|
+
### Method
|
683
713
|
|
714
|
+
This generates a preview version of a template.
|
684
715
|
|
685
|
-
|
716
|
+
```ruby
|
717
|
+
response = client.generate_template_preview(id)
|
718
|
+
```
|
686
719
|
|
687
|
-
|
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
|
-
|
722
|
+
### Arguments
|
690
723
|
|
691
|
-
|
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
|
-
|
699
|
-
personalisation: {
|
700
|
-
name: "name",
|
701
|
-
year: "2016",
|
702
|
-
})
|
729
|
+
'f33517ff-2a88-4f6e-b855-c550268ce08a'
|
703
730
|
```
|
704
731
|
|
705
|
-
|
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
|
-
|
736
|
+
```ruby
|
737
|
+
personalisation: {
|
738
|
+
name: "John Smith",
|
739
|
+
ID: "300241",
|
740
|
+
}
|
741
|
+
```
|
709
742
|
|
710
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
759
|
+
### Error codes
|
732
760
|
|
733
|
-
|
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
|
-
|
739
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
747
|
-
#### Method
|
774
|
+
You can only get the status of messages that are 7 days old or less.
|
748
775
|
|
749
|
-
|
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
|
-
|
780
|
+
older_than: 'e194efd1-c34d-49c9-9915-e4267e01e92e'
|
759
781
|
}
|
760
|
-
|
782
|
+
response = client.get_received_texts(args)
|
761
783
|
```
|
762
784
|
|
763
|
-
|
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
|
-
|
787
|
+
If you leave out the `older_than` argument, the client returns the most recent 250 notifications.
|
767
788
|
|
768
|
-
|
789
|
+
### Arguments
|
769
790
|
|
770
|
-
|
771
|
-
<summary>
|
772
|
-
Click here to expand for more information.
|
773
|
-
</summary>
|
791
|
+
#### older_than (optional)
|
774
792
|
|
775
|
-
|
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
|
-
|
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
|
-
`
|
799
|
+
If you leave out the `older_than` argument, the client returns the most recent 250 notifications.
|
784
800
|
|
785
|
-
|
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
|
-
|
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
|
-
|
807
|
+
You must then call either the `.links` method or the `.collection` method on this object.
|
798
808
|
|
799
|
-
|
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
|
-
|
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
|
-
|
807
|
-
|
808
|
-
|
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
|
-
|
825
|
+
If the notification specified in the `older_than` argument is older than 7 days, the client returns an empty `collection` response.
|