GOV.UK Notify Ruby client
API client for GOV.UK Notify written in Ruby.
Installation
Prior to usage an account must be created through the Notify admin console. This will allow access to the API credentials you application.
You can then install the gem or require it in your application.
gem install 'notifications-ruby-client'
Getting started
require 'notifications-ruby-client'
client = Notifications::Client.new(service_id, secret_id)
you can also override api endpoint
client = Notifications::Client.new(service_id, secret_id, base_url)
client.base_url # => Notifications::Client::PRODUCTION_BASE_URL
Generate an API key by logging in to GOV.UK Notify GOV.UK Notify and going to the API integration page.
You will find your service ID on the API integration page.
Send a message
Text message:
sms = client.send_sms(to: number,
template: template_id,
personalisation: {
name: "name",
year: "2016"
}
)
Email:
email = client.send_email(to: number, template: template_id)
sms = client.send_sms(
to: number,
template: template_id,
personalisation: {
name: "name",
year: "2016"
}
) # => Notifications::Client::ResponseNotification
Find template_id
by clicking API info for the template you want to send.
If a template has placeholders, you need to provide their values in personalisation
. Otherwise do not pass in personalisation
If successful the response is a Notifications::Client::ResponseNotification
, which has the notification id.
Otherwise a Notifications::Client::RequestError is returned.
Get the status of one message
notification = client.get_notification(id) # => Notifications::Client::Notification
notification.id # => uuid for the notification
notification.to # => recipient email address or mobile number
notification.status # => status of the message "created|pending|sent|delivered|permanent-failure|temporary-failure"
notification.created_at # => Date time the message was created
notification.api_key # => uuid for the api key (not the actual api key)
notification.billable_units # => units billable or nil for email
notification.subject # => Subject of email or nil for sms
notification.body # => Body of message
notification.job # => job id if created by a csv or nil if message sent via api
notification.notification_type # => sms | email
notification.service # => uuid for service
notification.sent_at # => Date time the message is sent to the provider or nil if status = "created"
notification.sent_by # => Name of the provider that sent the message or nil if status = "created"
notification.template # => Hash containing template id, name, version, template type sms|email
notification.template_version # Template version number
notification.reference # => reference of the email or nil for sms
notification.updated_at # => Date time that the notification was last updated
Get the status of all messages
notifications = client.get_notifications
notifications.links # => {"last"=>"/notifications?page=4", "next"=>"/notifications?page=2"}
notifications.total # => 202
notifications.page_size # => 50
notifications.collection # => [] (array of notification objects)
Query parameters are also supported
client.get_notifications(
page: 2,
limit_days: 3,
page_size: 20,
status: "delivered",
template_type: "sms"
)
Exceptions
Raised exceptions will contain error message and response status code
client = Notifications::Client.new(base_url, invalid, invalid)
rescue Notifications::Client::RequestError => e
e.code # => 403
e.message # => Invalid credentials
Code | Message |
403 | token: signature"] |
403 | token: expired"] |
429 | Exceeded send limits (50) for today |
400 | Can’t send to this recipient using a team-only API key |
400 | Can’t send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode |