alphagov/notifications-php-client

1.6.2 2017-12-05 13:48 UTC

README

This documentation is for developers interested in using this PHP client to integrate their government service with GOV.UK Notify.

Table of Contents

Installation

The Notify PHP Client can be installed with Composer. Run this command:

composer require php-http/guzzle6-adapter alphagov/notifications-php-client

PSR-7 HTTP

The Notify PHP Client is based on a PSR-7 HTTP model. You therefore need to pick your preferred HTTP Client library to use.

We will show examples here using the Guzzle v6 Adapter.

Setup instructions are also available for Curl and Guzzle v5.

Getting started

Assuming you’ve installed the package via Composer, the Notify PHP Client will be available via the autoloader.

Create a (Guzzle v6 based) instance of the Client using:

$notifyClient = new \Alphagov\Notifications\Client([
    'apiKey' => '{your api key}',
    'httpClient' => new \Http\Adapter\Guzzle6\Client
]);

Generate an API key by logging in to GOV.UK Notify and going to the API integration page.

Send messages

Text message

Method

Click here to expand for more information.

The method signature is:

sendSms( $phoneNumber, $templateId, array $personalisation = array(), $reference = '', $smsSenderId = NULL  )

An example request would look like:

try {

    $response = $notifyClient->sendSms(
        '+447777111222',
        'df10a23e-2c6d-4ea5-87fb-82e520cbf93a', [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968'
        ],
        'unique_ref123',
        '862bfaaf-9f89-43dd-aafa-2868ce2926a9'
    );

} catch (NotifyException $e){}

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "id" => "bfb50d92-100d-4b8b-b559-14fa3b091cda",
    "reference" => None,
    "content" => [
        "body" => "Some words",
        "from_number" => "40604"
    ],
    "uri" => "https =>//api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd",
    "template" => [
        "id" => "ceb50d92-100d-4b8b-b559-14fa3b091cda",
       "version" => 1,
       "uri" => "https://api.notifications.service.gov.uk/v2/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
    ]
]

Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:

exc->getCode() exc->getErrors()
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
}]
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
400 [{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
400 [{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]

Arguments

Click here to expand for more information.
$phoneNumber

The mobile number the SMS notification is sent to.

$templateId

Find by clicking API info for the template you want to send.

$reference

An optional identifier you generate if you don’t want to use Notify’s id. It can be used to identify a single notification or a batch of notifications.

$personalisation

If a template has placeholders, you need to provide their values, for example:

personalisation = [
    'name' => 'Betty Smith',
    'dob'  => '12 July 1968'
]

Otherwise the parameter can be omitted.

smsSenderId

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'.

If you omit this argument your default sms sender will be set for the notification.

Email

Method

Click here to expand for more information.

The method signature is:

sendEmail( $emailAddress, $templateId, array $personalisation = array(), $reference = '', $emailReplyToId = NULL )

An example request would look like:

try {

    $response = $notifyClient->sendEmail(
        'betty@example.com',
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c', [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968'
        ],
        'unique_ref123',
        '862bfaaf-9f89-43dd-aafa-2868ce2926a9'
        );

} catch (NotifyException $e){}

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "id" => "bfb50d92-100d-4b8b-b559-14fa3b091cda",
    "reference" => None,
    "content" => [
        "subject" => "Licence renewal",
        "body" => "Dear Bill, your licence is due for renewal on 3 January 2016.",
        "from_email" => "the_service@gov.uk"
    ],
    "uri" => "https://api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd",
    "template" => [
        "id" => "ceb50d92-100d-4b8b-b559-14fa3b091cda",
        "version" => 1,
        "uri" => "https://api.notificaitons.service.gov.uk/service/your_service_id/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
    ]
]

Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:

exc->getCode() exc->getErrors()
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
}]
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
400 [{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
400 [{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]

Arguments

Click here to expand for more information.
$emailAddress

The email address the email notification is sent to.

$templateId

Find by clicking API info for the template you want to send.

$personalisation

If a template has placeholders you need to provide their values. For example:

personalisation = [
    'name' => 'Betty Smith',
    'dob'  => '12 July 1968'
]

Otherwise the parameter can be omitted.

$reference

An optional identifier you generate if you don’t want to use Notify’s id. It can be used to identify a single notification or a batch of notifications.

$emailReplyToId

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'.

If you omit this argument your default email reply-to address will be set for the notification.

Letter

Method

Click here to expand for more information.

The method signature is:

sendLetter( $templateId, array $personalisation = array(), $reference = '' )

An example request would look like:

try {

    $response = $notifyClient->sendEmail(
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c',
        [
            'name'=>'Fred',
            'address_line_1' => 'Foo',
            'address_line_2' => 'Bar',
            'postcode' => 'Baz'
        ],
        'unique_ref123'
    );

} catch (NotifyException $e){}

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "id" => "bfb50d92-100d-4b8b-b559-14fa3b091cda",
    "reference" => "unique_ref123",
    "content" => [
        "subject" => "Licence renewal",
        "body" => "Dear Bill, your licence is due for renewal on 3 January 2016.",
    ],
    "uri" => "https://api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd",
    "template" => [
        "id" => "ceb50d92-100d-4b8b-b559-14fa3b091cda",
        "version" => 1,
        "uri" => "https://api.notificaitons.service.gov.uk/service/your_service_id/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
    ],
    "scheduled_for" => null
]

Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:

exc->getCode() exc->getErrors()
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
}]
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
400 [{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
400 [{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]

Arguments

Click here to expand for more information.
templateId

Find by clicking API info for the template you want to send.

personalisation

If a template has placeholders you need to provide their values. For example:

personalisation = [
    'name' => 'Betty Smith',
    'dob'  => '12 July 1968'
]

Otherwise the parameter can be omitted.

reference

An optional identifier you generate if you don’t want to use Notify’s id. It can be used to identify a single notification or a batch of notifications.

Get the status of one message

Method

Click here to expand for more information.

The method signature is:

getNotification( $notificationId )

An example request would look like:

try {

    $response = $notifyClient->getNotification( 'c32e9c89-a423-42d2-85b7-a21cd4486a2a' );

} catch (NotifyException $e){}

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "id" => "notify_id",
    "body" => "Hello Foo",
    "subject" => "null|email_subject",
    "reference" => "client reference",
    "email_address" => "email address",
    "phone_number" => "phone number",
    "line_1" => "full name of a person or company",
    "line_2" => "123 The Street",
    "line_3" => "Some Area",
    "line_4" => "Some Town",
    "line_5" => "Some county",
    "line_6" => "Something else",
    "postcode" => "postcode",
    "type" => "sms|letter|email",
    "status" => "current status",
    "template" => [
        "version" => 1,
        "id" => 1,
        "uri" => "/template/{id}/{version}"
     ],
    "created_at" => "created at",
    "sent_at" => "sent to provider at",
]

Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:

error["status_code"] error["message"]
404 [{
"error": "NoResultFound",
"message": "No result found"
}]
400 [{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]

Arguments

Click here to expand for more information.
$notificationId

The ID of the notification.

Get the status of all messages

Method

Click here to expand for more information.

The method signature is:

listNotifications( array $filters = array() )

An example request would look like:

    $response = $notifyClient->listNotifications([
        'older_than' => 'c32e9c89-a423-42d2-85b7-a21cd4486a2a',
        'reference' => 'weekly-reminders',
        'status' => 'delivered',
        'template_type' => 'sms'
    ]);

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "notifications" => [
            "id" => "notify_id",
            "reference" => "client reference",
            "email_address" => "email address",
            "phone_number" => "phone number",
            "line_1" => "full name of a person or company",
            "line_2" => "123 The Street",
            "line_3" => "Some Area",
            "line_4" => "Some Town",
            "line_5" => "Some county",
            "line_6" => "Something else",
            "postcode" => "postcode",
            "type" => "sms | letter | email",
            "status" => sending | delivered | permanent-failure | temporary-failure | technical-failure
            "template" => [
            "version" => 1,
            "id" => 1,
            "uri" => "/template/{id}/{version}"
        ],
        "created_at" => "created at",
        "sent_at" => "sent to provider at",
        ],

  ],
  "links" => [
     "current" => "/notifications?template_type=sms&status=delivered",
     "next" => "/notifications?older_than=last_id_in_list&template_type=sms&status=delivered"
  ]
]

Otherwise the client will raise a Alphagov\Notifications\Exception\NotifyException:

error["status_code"] error["message"]
400 [{
"error": "ValidationError",
"message": "bad status is not one of [created, sending, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure]"
}]
400 [{
"error": "Apple is not one of [sms, email, letter]"
}]

Arguments

Click here to expand for more information.
older_than

If omitted 250 of the most recent messages are returned. Otherwise the next 250 messages older than the given notification id are returned.

template_type

If omitted all messages are returned. Otherwise you can filter by:

  • email
  • sms
  • letter
status

email

You can filter by:

  • sending - the message is queued to be sent by the provider.
  • delivered - the message was successfully delivered.
  • failed - this will return all failure statuses permanent-failure, temporary-failure and technical-failure.
  • permanent-failure - the provider was unable to deliver message, email does not exist; remove this recipient from your list.
  • temporary-failure - the provider was unable to deliver message, email box was full; you can try to send the message again.
  • technical-failure - Notify had a technical failure; you can try to send the message again.

You can omit this argument to ignore this filter.

text message

You can filter by:

  • sending - the message is queued to be sent by the provider.
  • delivered - the message was successfully delivered.
  • failed - this will return all failure statuses permanent-failure, temporary-failure and technical-failure.
  • permanent-failure - the provider was unable to deliver message, phone number does not exist; remove this recipient from your list.
  • temporary-failure - the provider was unable to deliver message, the phone was turned off; you can try to send the message again.
  • technical-failure - Notify had a technical failure; you can try to send the message again.

You can omit this argument to ignore this filter.

letter

You can filter by:

  • accepted - Notify is in the process of printing and posting the letter
  • technical-failure - Notify had an unexpected error while sending to our printing provider

You can omit this argument to ignore this filter.

reference

This is the reference you gave at the time of sending the notification. This can be omitted to ignore the filter.

Get a template by ID

Method

Click here to expand for more information.
    $response = $notifyClient->getTemplate( 'templateId' );

Response

If the request is successful, response will be an array.

Click here to expand for more information.
{
    "id" => "template_id",
    "type" => "sms|email|letter",
    "created_at" => "created at",
    "updated_at" => "updated at",
    "version" => "version",
    "created_by" => "someone@example.com",
    "body" => "body",
    "subject" => "null|email_subject"
}
error["status_code"] error["errors"]
404 [{
"error" => "NoResultFound",
"message" => "No result found"
}]

Arguments

Click here to expand for more information.
templateId

Find by clicking API info for the template you want to send.

Get a template by ID and version

Method

Click here to expand for more information.
    $response = $notifyClient->getTemplateVersion( 'templateId', 1 );

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "id" => "template_id",
    "type" => "sms|email|letter",
    "created_at" => "created at",
    "updated_at" => "updated at",
    "version" => "version",
    "created_by" => "someone@example.com",
    "body" => "body",
    "subject" => "null|email_subject"
]
error["status_code"] error["errors"]
404 [{
"error" => "NoResultFound",
"message" => "No result found"
}]

Arguments

Click here to expand for more information.
templateId

Find by clicking API info for the template you want to send.

version

The version number of the template

Get all templates

Method

Click here to expand for more information.
    $this->getAllTemplates(
      $template_type  // optional
    );

This will return the latest version for each template

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "templates"  => [
        [
            "id" => "template_id",
            "type" => "sms|email|letter",
            "created_at" => "created at",
            "updated_at" => "updated at",
            "version" => "version",
            "created_by" => "someone@example.com",
            "body" => "body",
            "subject" => "null|email_subject"
        ],
        [
            ... another template
        ]
    ]
]

If no templates exist for a template type or there no templates for a service, the response will be a Dictionarywith an emptytemplates` list element:

[
    "templates"  => []
]

Arguments

Click here to expand for more information.
$templateType

If omitted all messages are returned. Otherwise you can filter by:

  • email
  • sms
  • letter

Generate a preview template

Method

Click here to expand for more information.
    $personalisation = [ "foo" => "bar" ];
    $this->previewTemplate( $templateId, $personalisation );

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "id" => "notify_id",
    "type" => "sms|email|letter",
    "version" => "version",
    "body" => "Hello bar" // with substitution values,
    "subject" => "null|email_subject"
]
error["status_code"] error["errors"]
400 [{
"error" => "BadRequestError",
"message" => "Missing personalisation => [name]"
}]
404 [{
"error" => "NoResultFound",
"message" => "No result found"
}]

Arguments

Click here to expand for more information.
$templateId

Find by clicking API info for the template you want to send.

$personalisation

If a template has placeholders you need to provide their values. For example:

$personalisation = [
    'first_name' => 'Amala',
    'reference_number' => '300241',
];

Otherwise the parameter can be omitted or null can be passed in its place.

Get received text messages

Method

Click here to expand for more information.
    $this->listReceivedTexts(
      $older_than  // optional
    );

Response

If the request is successful, response will be an array.

Click here to expand for more information.
[
    "received_text_messages" => [
        [
            "id" => "notify_id",
            "user_number" => "user number",
            "notify_number" => "notify number",
            "created_at" => "created at",
            "service_id" => "service id",
            "content" => "text content"
        ],
        [
            ... another received text message
        ]
    ]
  ],
  "links" => [
     "current" => "/received-text-messages",
     "next" => "/received-text-messages?older_than=last_id_in_list"
  ]
]

Arguments

Click here to expand for more information.
$older_than

If omitted 250 of the most recently received text messages are returned. Otherwise the next 250 received text messages older than the given id are returned.