v1
latestOpenAPI 3.0.02026-07-144080.8 KBSend an in-app message
Overview
Use this endpoint to send an in-app message followed by an associated native Apple or Android push notification to a single NHS App user.
Push notifications will not be sent to users between the hours of 10pm and 6am UK time. If a valid request to send an in-app message with an associated push notification is processed between these hours, the in-app message will be delivered immediately, and the push notification will be scheduled for delivery at 6am.
Recipients are specified by NHS number. A single request to this endpoint can send a message and push notification to a single NHS App user. In-app messages and push notifications will only be sent to users who have had their identity verified to 'high' (P9) level.
If a recipient is an active NHS App user but has not registered a device to receive native push notifications, they will still receive the in-app message.
This endpoint allows you to specify the content that will appear in the in-app message. It does not allow you to specify the content that will appear in the associated push notification. By default, the content of the associated push notification will read "NHS App. You have a new message." To discuss changing this standard push notification content for your application, contact the NHS App team.
When a recipient taps the native notification, the NHS App will open on the in-app messaging inbox page.
We support a subset of Markdown for describing the body text of in-app messages. For details of the subset see the 'payload' property of the schema. Note that HTML encoded characters will be decoded on displaying them in the NHS App to the user. The length of each in-app message is limited to 5000 characters, including any markdown characters and embedded hyperlinks.
The body of requests made to this endpoint are instances of HL7 FHIR R4 CommunicationRequest resources. This schema documentation describes which fields on that resource we require and support. The API is tolerant of (but will silently ignore) any additionally supplied optional fields. For example, we do not currently honour the doNotPerform or priority fields.
The outcome of communication requests can be determined using the daily receipt report endpoint. You may also create an endpoint into which NHS App can post the outcome of individual communication requests in realtime — we call this feature "realtime receipts". We have created an Open API specification detailing the behaviour of the endpoint that you should create to subscribe to realtime receipts. Similarly, you can subscribe to the realtime replies responses to the same or different endpoint, we have created an Open API specification detailing the format/behaviour of the response that will be posted.
Request body
Example request
{
"identifier": [
{
"system": "https://fhir.nhs.uk/NHSApp/campaign-id",
"value": "Optional campaign ID"
}
],
"payload": [
{
"contentString": "You have a new appointment, please confirm you can attend. Open the Onboarded Third Party appointment here https://www.nhsapp.service.nhs.uk/appointments/hospital-appointments"
}
],
"recipient": [
{
"type": "Patient",
"identifier": {
"value": "9903002157"
}
}
],
"requester": {
"type": "Organization",
"identifier": {
"value": "B82041"
}
}
}Response
Request successfully received by the server and queued for sending to recipient.