-
-
Callback documentation
-
A callback lets you receive messages from Notify to a URL you choose.
-
You’ll need to provide a bearer token, for security. We’ll add this to the authorisation header of the callback request.
-
The callback message is in JSON.
-
-
Email and text message delivery receipts
-
When you send an email or text message through Notify, we can send a receipt to your callback URL to tell you if we were able to deliver it or not.
-
- {% call mapping_table(
- caption='Callback message format',
- field_headings=['Key', 'Description', 'Format'],
- field_headings_visible=True,
- caption_visible=False
- ) %}
- {% for key, description, format in [
- ('id', 'Notify’s id for the status receipts', 'UUID'),
- ('reference', 'The reference sent by the service', '12345678'),
- ('to', 'The email address of the recipient', 'hello@gov.uk'),
- ('status', 'The status of the notification', 'delivered | permanent-failure | temporary-failure | technical-failure'),
- ('created_at', 'The time the service sent the request', '2017-05-14T12:15:30.000000Z'),
- ('completed_at', 'The last time the status was updated', '2017-05-14T12:15:30.000000Z'),
- ('sent_at', 'The time the notification was sent', '2017-05-14T12:15:30.000000Z or nil'),
- ('notification_type', 'The notification type', 'email | sms | letter')
- ] %}
- {% call row() %}
- {% call row_heading() %} {{ key }} {% endcall %}
- {{ text_field(description) }}
- {{ text_field(format) }}
- {% endcall %}
- {% endfor %}
- {% endcall %}
-
-
-
Text messages you receive
-
If your service receives text messages in Notify, we can forward them to your callback URL as soon as they arrive.
-
- {% call mapping_table(
- caption='Callback message format',
- field_headings=['Key', 'Description', 'Format'],
- field_headings_visible=True,
- caption_visible=False
- ) %}
- {% for key, description, format in [
- ('id', 'Notify’s id for the received message', 'UUID'),
- ('source_number', 'The phone number the message was sent from', '447700912345'),
- ('destination_number', 'The number the message was sent to (your number)', '07700987654'),
- ('message', 'The received message', 'Hello Notify!'),
- ('date_received', 'The UTC datetime that the message was received by Notify', '2017-05-14T12:15:30.000000Z')
- ] %}
- {% call row() %}
- {% call row_heading() %} {{ key }} {% endcall %}
- {{ text_field(description) }}
- {{ text_field(format) }}
- {% endcall %}
- {% endfor %}
- {% endcall %}
-
-{% endblock %}
diff --git a/app/templates/views/design-patterns-content-guidance.html b/app/templates/views/design-patterns-content-guidance.html
deleted file mode 100644
index c8df6810f..000000000
--- a/app/templates/views/design-patterns-content-guidance.html
+++ /dev/null
@@ -1,145 +0,0 @@
-{% from "components/banner.html" import banner_wrapper %}
-{% extends "withoutnav_template.html" %}
-
-{% block per_page_title %}
-Design patterns and content guidance
-{% endblock %}
-
-{% block maincolumn_content %}
-
-
-
-
-
- Design patterns and content guidance
-
-
- {% call banner_wrapper(type='warning') %}
-
This content is a work in progress
-
-
It should not be relied upon
- {% endcall %}
-
-
-
-
- When to send notifications
-
- Send notifications to reduce anxiety
-
- Talk to your call centre staff to find out why people call – this is probably why they are anxious. For example:
-
-
- - I made a claim online – did it go through?
- - I sent you an application – did you receive it?
- - I sent you some supporting documents – did you receive them?
- - Did you approve my application?
- - Have you sent my new passport yet?
- - Has my application got lost or stuck somewhere?
-
-
- Tell users if they need to do something
-
- If someone needs to do something, tell them. For example:
-
- Your MOT expires on 28 September – get an MOT
-
- The deadline for tax returns is 31 January – complete your self assessment tax return
-
- Your passport photo didn’t meet our standards – take a new photo
-
- Security checks
-
- When someone does something important, send a security check to the people who might be affected. For example:
-
-
- - We registered a Lasting Power of Attorney in your name
- - You no longer own the freehold for 1 Candle Street, Mile End, London
- - Sainsburys Ltd applied for planning permission for 3 Candle Street, Mile End, London
-
-
- 2-factor code
-
- When someone wants to sign in, send a 2-factor authentication code to the number you have on file. For example: Your GOV.UK verification code is 123 456
-
-
-
- Design patterns
-
-
-
- Use radio buttons to ask the user how they’d like to be contacted:
-
-
- - by post
- - be email
- - by text message
- - by phone call
-
-
- When the user selects a contact method, dynamically prompt them for contact details (if you don’t already have them)
-
- Ask the user to pick one primary contact method. Users don’t like duplicate notifications.
-
- You can still contact them by other contact methods if appropriate.
-
- Collect these using the patterns in the Government Service Manual and the Hackpad.
-
- Tell the user they’re going to receive notifications
-
- Tell the user that you will send them notifications. For example:
-
-
- We will email you about this petition, and nothing else. You can unsubscribe at any time
-
-
-
-
- Content guidance
-
- Include one important message
-
- Don’t explain the whole process – just tell the user what will happen next.
-
-
- - If the user needs to do something, tell them what they have to do. Include a link if possible – see our Information security guidelines
- - When will the next thing happen? If the next step is important, tell them when it will happen. For example, we’ll make a decision by 28th October.
- - How long until they are done? If the next step isn’t important, just tell them when they’ll be completely finished. For example, you’ll get your new passport by 2nd November.
-
-
- Don’t send a message for steps that aren’t important to the user. For example, you don’t need to tell the user about background checks unless they fail one of the checks.
-
- Writing for notifications
-
-
- - Write tailored content. You’re writing to just one person – so tell them exactly what they need to know
- - Write as if you’re speaking – use personal language (you, we etc)
- - Tell the user when you’ll do something (by Tuesday, by 28th October) not how long you’ll take (within 3 working days, within 6 weeks)
- - Follow GOV.UK content guidance
-
-
- Writing for SMS
-
-
- - Get the most important message in the first sentence
- - Write one idea per sentence
- - Make it as short as possible – but don’t use jargon or acronyms without explanation
- - Don’t say ‘Dear’ or ‘Hi’ – just launch straight in
-
-
- Writing for emails and letters
-
- Say ‘Dear’, not ‘Hi’ – some people prefer ‘Hi’ and some prefer ‘Dear’, but only the people who prefer ‘Dear’ care enough to complain when we say ‘Hi’
-
-
-
-
-{% endblock %}
diff --git a/tests/app/main/views/test_index.py b/tests/app/main/views/test_index.py
index 473e4bf0a..70156a878 100644
--- a/tests/app/main/views/test_index.py
+++ b/tests/app/main/views/test_index.py
@@ -72,7 +72,7 @@ def test_robots(client):
@pytest.mark.parametrize('view', [
'cookies', 'privacy', 'pricing', 'terms', 'roadmap',
- 'features', 'callbacks', 'documentation', 'security',
+ 'features', 'documentation', 'security',
'message_status', 'features_email', 'features_sms',
'features_letters', 'how_to_pay',
])
@@ -94,6 +94,7 @@ def test_static_pages(
('information_security', 'using_notify'),
('old_using_notify', 'using_notify'),
('delivery_and_failure', 'message_status'),
+ ('callbacks', 'documentation'),
])
def test_old_static_pages_redirect(
client,