API client for GOV.UK Notify written in Ruby.
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'
require 'notifications/client'
client = Notifications::Client.new(api_key)
Generate an API key by logging in to GOV.UK Notify GOV.UK Notify and going to the API integration page.
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.
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
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"
)
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"=>["Invalid token: signature"]} |
403 | {"token"=>["Invalid 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 |