NHS App Messaging Service: Integrating Partner Requirements and guidance

The NHS App Messaging Service (previously called NHS account messaging) is currently in public beta and - at the moment - does not support all the same message scenarios as SMS (for example time-critical messages). We’re working towards this goal. 

Ultimately, the best experience for patients is for communications from a given sender to come through a single channel that meets their needs. 

Therefore you should consider: 

• using the NHS App Messaging Service where possible to send communications to citizens 

• leveraging additional features of the NHS App Messaging Service, as they become available to support more messaging scenarios 

Any capitalised terms are either defined in this document or in the Connection Agreement.

The Sending Organisation is defined in this document as the End User Organisation of the Integrating Partner.

A Message is defined as a communication that goes through the NHS App Messaging Service.

A Notification is any method we use to alert a citizen to the presence of a message in their NHS App Messaging Service inbox, such as a push notification.

A Status is any status sent using the delivery (‘real-time’) receipts feature in the NHS App Messaging Service.

This document forms part of the Integration Process for Integrating Partners of the NHS App Messaging Service.  

It is intended for product managers and delivery leads of Integrating Partners.  

The document provides: 

•  the Requirements you need to follow to use the Service (prefaced with either ‘The Integrating Partner must’ or ‘The Integrating Partner and Sending Organisation must’, and numbered)  

•  additional guidance and recommendations 

The Integrating Partner must: 

1.1. Assure in the Conformance Documentation that the Requirements have been met, and ensure that the Conformance Documentation remains true, accurate and complete. 

1.2. Comply with any Changes made to the Requirements in accordance with the change management process set out in the Connection Agreement. 

1.3. Ensure that Sending Organisations are made aware of these Requirements and guidance and the obligations on them. 

1.4. Have in place measures or features to ensure that the Sending Organisations meets these requirements, for example by providing guidance and templates. 

The Integrating Partner and Sending Organisation must: 

1.5. Ensure that all communication, from each Sending Organisation, follow these requirements. 

Before integration, you must tell us if you cannot meet a Requirement and provide:

• any mitigating actions
• reason for exceptions

We’ll assess your circumstances and work with you to resolve any problems.

Contact us if you have:

• questions about how to meet the Requirements or follow our guidance
• any feedback or recommendations

Messages are addressed to citizens using their NHS number, which is linked to their NHS login IDs.

A citizen can have multiple NHS login IDs registered with the same NHS number. Each NHS login ID can only access Messages that were sent after its creation.

Citizens can access Messages in the NHS App Messaging Service through the native NHS App and via nhs.uk using an internet browser.

The Integrating Partner and Sending Organisation must:

2.1. Only send Messages to an NHS number that the Sending Organisation has the legal basis to contact regarding the purpose of that specific communication.

The Integrating Partner and the Sending Organisation must put in place reasonable measures to:

2.2. Only send Messages that are relevant to the recipient/cohort targeted.

2.3. Only send Messages that are relevant to an individual's or their dependent's care.

2.4. Listen to feedback from citizens who report inappropriate or undesired Messages.

As part of the integration process, you will be asked to complete a Use Case Request to ensure that the Messages you plan to send will meet these requirements.

NHS England research has shown that citizen engagement with messages falls if they receive too many Messages that are not relevant to them. You should avoid sending too many Messages to an individual that might be considered a nuisance, unless necessary for their care.

The Integrating Partner and the Sending Organisation must:

2.5. Take responsibility if you send communication with time critical content and the citizen does not read or receive it in time. NHS England does not guarantee how quickly Messages will be processed through the API.

Time critical content is anything medically important, where there would be a clinical risk if the user was either not informed or did not perform a requested action in a specific time-frame.

Examples of time critical content include:

• reminding a diabetic user to take their insulin
• informing a citizen their appointment later that day has been cancelled and they need to rearrange
• requesting information, for example requesting photographs during a telephone appointment

If you are unsure whether your content is time critical, time sensitive or neither, send it to us as a Use Case Request for assessment.

NHS England strongly advises that you do not send any Messages with time-critical content.

As part of the roll-out of this Service, Sending Organisations should plan how:

• to inform citizens of the new communications channel and what it means for how they’ll receive messages, for example by sending a welcome message through the NHS App Messaging Service and an existing channel
• how front-line staff will handle queries from citizens and resolve issues

You should consider that some messages from the Sending Organisation may already be sent through the NHS App Messaging Service.

NHS England can provide support or advice if you need help with the roll-out plan.

The Sending Organisation is responsible for managing citizen communication preferences. NHS App Messaging Service will process all Messages assuming the Sending Organisation has fulfilled this responsibility. 

You should plan how citizens can specify their preferred method for receiving communications, which could include citizens preferring to receive Messages via the NHS App Messaging Service or preferring to receive other communications via another channel.  

You could handle requests to stop receiving Messages by excluding this channel only and sending the communication using an alternative channel. 

The Integrating Partner and Sending Organisation must:

2.6. Respect citizen’s existing communications preference and only send through their preferred channels.

2.7. Offer citizens the option to stop receiving Messages through the NHS App Messaging Service. 

If NHS England directly receives any citizen requests to stop or start receiving communication through the NHS App Messaging Service, we will instruct them to contact the Sending Organisation.  

Notifications about Messages are handled by the business rules in the NHS App. You do not need to provide additional Notifications about the Message.  

Once we process a Message, we will usually send users a Notification (if they are opted-in), using methods such as push notifications. Citizens do not need to have the app open to receive a Notification. 

We recommend that you do not use multiple simultaneous communication channels to reduce the risk of over-burdening patients with communication traffic. For example, using both the NHS App and SMS to send the same communication to patients. 

We advocate using the NHS App as an initial communication channel and implementing a contingency fallback mechanism to another channel such as SMS if unsuccessful. 

The Integrating Partner must:

2.8. Have in place adequate contingency mechanisms between you and the Sending Organisation to make sure care is not affected if a citizen does not receive or act on a Message using this Service. 

2.9. Decide when it’s appropriate to use the contingency mechanism, taking into account: the purpose of the Message, the Status of the Message (or other signals from other systems), and the time elapsed since the last Status update.

Your contingency mechanism could be to send: 

• a fallback communication via another channel, such as SMS, email, letter or phone call 

• another message through the NHS App Messaging Service, for example a follow-up or reminder to the initial Message, or the same Message again  

If a user has expressed a preference to receive communications through another channel, you should send the same message to that channel right away.  

However, if a user prefers to receive communications through the NHS App Messaging Service, your contingency mechanism might be to send a communication via another channel to prompt citizens to check their NHS App Messaging Service.  

The NHS England API Service provides delivery (‘real-time’) receipts, which you can use to take into account when deciding to use a contingency mechanism. You may be able to supplement this information with indicators from other systems available to you as you would when sending from other channels. 

See more information about using real-time receipts in the ‘How to use this service’ section. 

In the event that an API request in unsuccessful, you will receive an error code to explain why the attempt failed.

We recommend that you attempt to re-send the request up to five times, with two-minute intervals in between. If the API request is still unsuccessful after five attempts, please refer to the Fallback logic (see contingency mechanism above).

Messages should be optimised for the capabilities and user experience of the NHS App Messaging Service, including:

• what personally identifiable information to include
• using Markdown syntax correctly
• making Messages usable, accessible and understandable
• sending full messages, without truncating or summarising the content

Read the NHS App API documentation for details of the current authoring capabilities.

Read this section for more information on optimising user experience within the NHS App Messaging Service.

As Messages are secured by the NHS Login authentication process and users have to be fully verified (P9), the contents of Messages in the NHS App Messaging Service can include:

• personal data
• special category data, such as about a citizen's care

The Integrating Partner and the Sending Organisation must:

3.1. Not include personal data in any URLs sent as part of the Message body.

Messages can display both rich content and interactive features, using a subset of the Markdown syntax.

The Integrating Partner and Sending Organisation must:

3.2. Supply correctly formatted Markdown as the Message body.

3.3. Only use the subset of Markdown supported as described in the NHS App API documentation.

3.4. Correctly format any interactive features as described in the NHS App API documentation.

3.5. Not send Messages with unsupported features, such as Messages requesting free-text replies.

3.6. Ensure, as far as is reasonably within its control, the content linked from Messages is available for as long as it is relevant. This is especially critical where the click-through directly relates to the individual’s care, such as archives of forms, documents, or test results.

3.7. Use the keyword reply functionality correctly (see the 'Keyword replies' section for more information). 

The Integrating Partner and Sending Organisation must:

3.8. Ensure Message formatting and content is accessible and usable.

3.9. Ensure Messages contain sufficient information for the citizen to understand the purpose of the Message and any actions they need to take.

3.10. Take reasonable measures to ensure any downstream services linked to from Messages are also accessible and usable.

3.11.  Take responsibility for the decision to send a Message in a language other than English and ensuring that this meets that citizen’s needs, taking into account:  

i) any relevant policies or guidance about language provision for the particular service 

ii) NHS England doesn’t collect language preferences; and  

iii) NHS App Messaging Service interfaces and NHS App notifications are only available in English. 

You can make accessible, usable, and understandable content by:

• following the NHS content style guide
• structuring Messages into paragraphs, with headings
• correctly formatting hyperlinks, headings, emphasis
• following the Public sector accessibility requirements, the NHS Accessible information standard and the Web Content Accessibility Guidelines (WCAG)
• testing content with its intended users
• using the correct Markdown syntax to display accessible components

In user research, we've found that citizens have difficulty reading long blocks of text, which led to them misunderstanding the message and instructions. 

The NHS App Messaging service has the functionality to allow two types of replies to Messages, which works in a comparable way to SMS replies. 

Free-Text Replies

These are Messages where citizens can write answers as free-form text.

Keyword Replies

These are Messages where citizens are asked to send a single-word, predetermined reply to a Message. Alongside the Message, the citizen will see a list of possible responses as radio buttons or a checkbox.

If using free-text or keyword reply features, the Integrating Partner and Sending Organisation must:

3.12. Have an endpoint that accepts keyword replies that is highly available and can process replies quickly.

3.13. Provide all the essential information needed to reply to the Message in the body of the Message.

3.14. Accept, store and process the first response, attribute it to the corresponding message, and act accordingly on it. 

3.15. Take responsibility for the contents of Messages. NHS England do not check Message contents or flag potentially sensitive information.

3.16. Be prepared to accept multiple responses to a Message - while we do restrict citizens to a single reply to a Message, there are circumstances where this can't be guaranteed. For example, if a citizen has multiple NHS logins and gets multiple Messages.

3.17. Explain in the body of the Message how citizens can contact you if they have a question, or they want to send a reply that is different to the available keywords. 

3.18. Be prepared to accept responses at any time after the Message is sent - we do not restrict citizens from replying after a certain amount of time and they will not be limited to only replying to the most recent Message. 

3.19. Be aware that NHS England strongly advises that you do not send any Messages containing time-sensitive questions which require a reply within a given timeframe and, if you do, you must follow the requirements in the section above titled 'Time critical content', including requirement 2.5. 

3.20. (If applicable) make it clear to citizens that their replies may not be read of responded to out of hours or before a specified period of time. 

For Messages that use keyword replies, the Integrating Partner and Sending Organisation must:

3.21. Send the full list of allowable replies as part of the Message API request that citizens will be given as options to choose from in the Message. 

For Messages that use free-text replies, the Integrating Partner and Sending Organisation must:

3.22. Accept and process replies up to 500 characters.

3.23. Enable free-text replies only for Messages that accept or require replies.

3.24. Take responsibility for managing the content of free-text replies, and any safeguarding processes applied. NHS England do not check reply contents or flag potentially sensitive information. 

Guidance on writing Messages for keyword replies 

Give users all the information they need to be confident they are choosing the right response. During research, we presented users with an appointment reminder message. Users understood that they should respond ‘Cancel’ to cancel an appointment or take no action to keep the appointment. However, most users expressed that they would expect to be able to confirm an appointment or reschedule it. The single reply option left them feeling uneasy or dissatisfied.  

Our research also found that users were less confident entering keyword replies if they did not make sense without the context of the message. For example, use ‘Reply ‘Confirm’ to confirm’ and ‘Reply ‘Decline’ to decline‘ instead of ‘Reply ‘1’ to confirm’ or ‘Reply ‘2’ to decline’. Users will only see the possible replies of ‘1’ and ‘2’.  

Guidance on writing Messages for free-text replies

Free-text questions should be clearly worded to encourage users to provide only the information required and not disclose more sensitive information than necessary. 

Messages are sent using the NHS England API Management platform (APIM), which operates a per-supplier rate limit. Requests will be processed in the order they are received.

The Integrating Partner must:

4.1. Comply with requirements and constraints set out in NHS App API documentation.

4.2. Respond if we have an urgent patch release as set out in the Connection Agreement.

4.3. Develop its own change processes and undertake any development work required to ensure compliance with any changes made to the Requirements, the NHS App Messaging Service and/or the associated API's (including upgrades, new versions and deprecation) in accordance with the change management process set out in the Connection Agreement. 

We create a unique identifier (the ‘Communication ID’), for each Message processed through the API. The communication ID is given in the API response (HTTP status: 201).  

The communication ID is used for tracking events, for example using the real-time receipts feature.  

The Integrating Partner must:  

4.4. Keep a record of each generated communication ID against the initial communication sent to the API and the corresponding Message, which is used for auditing and traceability between the organisations.  

The Sending Organisation’s ODS code must be used for the sender ID. This is used to:

• identify the sender organisation for auditing and monitoring purposes
• group Messages by the same sender in the citizen’s NHS App Messaging Service inbox
• provide citizen-facing information about the sender, for example the name

The name associated with the ODS code on the central ODS dataset should be recognisable to the citizen, as this will be the name shown in their NHS App Messaging Service inbox.

The API will refuse any request that does not provide a valid ODS code.

The Integrating Partner must:

4.5. Provide the sender ID when sending a Message request through the API.

4.6. Supply a valid ODS code, from ODS Portal.

4.7. Use a live/current ODS code.

4.8. Use the correct ODS code of the organisation sending the Message.

4.9. Only represent a Sending Organisation that you have the legal right to represent.  

A campaign ID is an optional campaign identifier that you can use to group multiple communication requests for later analysis. It will not be seen by recipients.

The Integrating Partner must:

4.10. Ensure any campaign ID does not contain any personal data.

Real-time receipts provide you (or the Sending Organisation) a Status update about a Message as soon as it happens.

See the NHS App API documentation for more information about implementing real-time receipts.

If using Delivery (‘real-time’) Receipts, the Integrating Partner must:

4.11. Have an endpoint that accepts the delivery (‘real-time’) receipts and is highly available.

4.12. Use the status from receipt (or the absence of a receipt) as definitive measurement of citizen behaviour with the Message, and as a way to determine whether a contingency mechanism should be used.

4.13. Not process receipts (personal data) for any other purpose, without permission or instruction from the controller (Sending Organisation).

4.14. Use an appropriate contingency mechanism if you receive a ‘Rejected’ or ‘Unnotified’ Status and the citizen’s care may be affected because they have not successfully received the message.

4.15. Consider the Message has been successfully sent and delivered if you receive a ‘Notified’ status.

Using real-time receipts and contingency mechanisms 

There is a balance to be struck between ensuring care is not affected, and prematurely using a contingency mechanism, which could cost money and send a citizen unnecessary communication across different channels. 

Example 1

You may decide that if you receive a ‘Notified’ Status receipt within a certain number of days or hours, then you don’t need to use a contingency mechanism, as reading is a sufficient action for the Message purpose. If you receive an ‘Unnotified’ or ‘Rejected’ Status receipt, you must take this as an indication that a Message has not been delivered and use an appropriate contingency mechanism. 

Example 2

If a Message requires a response, for example booking a critical appointment, you may decide to use the contingency mechanism until the citizen has taken action on Message, even if you receive both ‘Read’ and ‘Notified’ Status receipts. 

Example 3

If you have sent multiple messages to a citizen and they have been ‘Notified’ but never ‘Read’, you may choose to use this as indication that they are not using this channel and could consider sending messages through another channel or asking them their preference

• Version 5.1, 13 February 2023 - This update introduces guidance on Retry logic, Fallback logic and API Deprecation.
• Version 5.0, 16 January 2023 - This update covers the introduction of Free-Text replies in the 'Replies to Messages' sub-section of section 3 'Authoring Messages'. This includes new requirements 3.19 to 3.24 and changes to existing requirements 3.12 to 3.18.
• Version 4.1, 14 December 2022 - This minor update covers two new Requirements. Requirement 3.11 covers sending Messages in languages other than English. Requirement 4.3 covers keeping a record of Communication IDs for communications and Messages. 
• Version 4.0, 16 November 2022 - Significant update for the release of keyword replies feature. In section 3 ‘Authoring messages’ you can find information on using the keyword replies feature, including: guidance on writing keyword replies and new requirements 3.11 to 3.18.
• Version 3.0, 1 November 2022 - Significant update for release of the delivery (‘real-time') receipts feature. In section 2 ‘How to use the service’, the information in ‘Ensuring a citizen’s care is not affected’ provides more guidance on using contingency mechanisms. In section 4 ‘How to use this service’ you can find information on using real-time receipts, including: types of receipt Statuses, how to use real-time receipts, and new requirements (4.9 to 4.13 to follow) to follow. NHS account messaging is now known throughout as the NHS App Messaging Service.
• Version 2.0, 5 July 2022 - Significant update for the NHS account messaging public beta release
• Version 1.0, 8 January 2022 – Original version for the NHS account messaging private beta release