---
title: "Send an in-app message"
method: POST
path: "/communication/in-app/FHIR/R4/CommunicationRequest"
tags: ["communication"]
---

# Send an in-app message

`POST /communication/in-app/FHIR/R4/CommunicationRequest`

## 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](mailto:app.onboarding@nhs.net).

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](https://en.wikipedia.org/wiki/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](https://www.hl7.org/fhir/communicationrequest.html) 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](https://www.hl7.org/fhir/communicationrequest-definitions.html#CommunicationRequest.doNotPerform) or [priority](https://www.hl7.org/fhir/communicationrequest-definitions.html#CommunicationRequest.priority) fields.

The outcome of communication requests can be determined using the [daily receipt report endpoint](#api-Communication-get-receipt-report). 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](https://github.com/NHSDigital/nhs-app-api/tree/master/specifications-callbacks/realtime-receipts) 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](https://github.com/NHSDigital/nhs-app-api/tree/master/specifications-callbacks/realtime-replies) detailing the format/behaviour of the response that will be posted.

## Request body

- object — Communication request to send a in-app message
  - `resourceType` string, required — FHIR Resource Type – this must be `CommunicationRequest`.
  - `identifier` object[] — An array of identifiers used to identify this request for later analysis. We have defined the following systems for identifiers that will be stored with the request: * Campaign ID – denoted by system https://fhir.nhs.uk/NHSApp/campaign-id . This is an optional campaign identifier, used for later identification of a group of multiple communication requests. For example, this could be used to identify all messages that pertain to invitations for a particular vaccination programme. * Request Reference – denoted by system https://fhir.nhs.uk/NHSApp/request-id . This is an optional request identifier, used for later identification of a specific request. * On Behalf Of - denoted by system https://fhir.nhs.uk/NHSApp/on-behalf-of . This field is used to record the entity for which your communication is being sent on behalf of. This field is only applicable if your application is registered as an intermediary between suppliers and the NHS App. Such registration is handled during onboarding and cannot be changed without discussion with the NHS App team. It is an error to provide this field if your application is not registered as an intermediary. Note that these identifier system names are case-sensitive. The values provided for each of these identifiers are limited to 128 characters, and must not match the regular expression `<(.|\n)*?>`. It is an error to provide duplicate fields in a single request. The API will not reject requests that contain other identifier systems, but these values will be ignored and not recorded against the request. When a `CommunicationRequest` resource is returned in the response body to a successful request, this array will also include a globally unique identifier assigned by the API, with the system `https://fhir.nhs.uk/Id/nhs-app-communication-id`. This is the same logical ID contained within the `Location` header of the successful response.
    - `system` string, uri — The namespace for the identifier value
    - `value` string — The value of the identifier
  - `status` string, required — Request Status of the message. This must always be `active` (case-sensitive).
  - `payload` object[], required — The body text of the message to be displayed in the NHS App
    - `contentString` string, required — The body text of the message to be displayed in the NHS App. We support a subset of [Markdown](https://en.wikipedia.org/wiki/Markdown) for in-app messages. Currently supported Markdown syntax: * Emphasis * Bold text \*\*Bold\*\* * Headings * Heading 2 \#\# Heading 2 * Heading 3 \#\#\# Heading 3 * Lists * Bulleted list: \* Item1 \* Item2 \* Item3 * Ordered lists 1\. Item1 2\. Item2 3\. Item3 * Links with text \[Link text](https://en.wikipedia.org/wiki/Markdown) * Links with title \[Link text](https://en.wikipedia.org/wiki/Markdown\, "Title text") * Images \!\[NHS Logo](https://assets.nhs.uk/images/nhs-logo.png) * Line break, two or more spaces followed by return > Forcing a line-break &nbsp;&nbsp;<--(two spaces) > Next line Note that HTML encoded characters will be decoded in the NHS App upon displaying them to the user.
  - `contained` object[] — An optional array of FHIR resource object used for a keyword & free text replies. Must contain only one item in the array.
    - `resourceType` string, required — FHIR Resource Type – this must be `Questionnaire`
    - `id` string, required — Id of the Questionnaire resource type
    - `status` string, required — Questionnaire status for the message. This must always be `active` (case-sensitive)
    - `item` object[], required — An array containing the type of the message reply. Must contain only one item in the array
      - `linkId` string, required — Any unique Id which must be a string
      - `type` string, required — Type must be `text` for the free text and `choice` for the keyword replies messages
      - `answerOption` object[] — An optional array containing valueCoding objects for keyword replies. Only required for keyword reply messages
        - `valueCoding` object — An optional object contains code. Only required for keyword reply messages
          - `code` string — A string code that would be shown to the patient for selection. Only required for keyword reply messages
  - `extension` object[] — An optional array of FHIR extension resource used for a keyword & free text replies. Must be present when the contained field is available in the request
    - `url` string, required — This should be `https://fhir.nhs.uk/NHSApp/answers`
    - `valueReference` object, required
      - `reference` string, required — The reference value should be same as Questionnaire resource Id. Must have '#' prefix
  - `recipient` object[], required — An array containing a single NHS number corresponding to the patient to whom this in-app message should be sent. Each communication may be sent to only a single recipient.
    - `type` string — FHIR resource type that the reference refers to. This should be `Patient`.
    - `identifier` object — Identifier of a recipient. This should be an NHS number.
      - `system` string, uri, required — The system that the identifier belongs to. This should be https://fhir.nhs.uk/Id/nhs-number
      - `value` string, required — The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).
  - `requester` object, required — The requester who initiated the communication and would like to send an in-app message to the patient.
    - `type` string — FHIR resource type that the organization code refers to. This should be `Organization`.
    - `identifier` object — Identifier and system of identification used for this Organisation.
      - `system` string, uri, required — URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care. This should be https://fhir.nhs.uk/Id/ods-organization-code
      - `value` string, required — ODS code of the requester who initiated the communication and would like to send an in-app message to the patient.

## Response `201`

Request successfully received by the server and queued for sending to recipient.

## Other responses

- `400` — There is an error in your request.
- `401` — Authorisation issue, for example a missing or expired bearer token.
- `403` — You are not authorised to perform this operation. For example, some onboarded client applications may be permitted to send Push Notifications but not In-app Messages, or vice versa.
- `429` — You have exceeded your application’s [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits) or the API is currently receiving a high volume of requests.

---

[API](https://skmtc.dev/nhs/apis/nhs-app-api.md) · [All operations](https://skmtc.dev/nhs/apis/nhs-app-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/nhs-app-api/revisions/0afa2c6452b1/schema)