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