Send 'Instant' Message

Description

This endpoint is used to send documents to registered GP (General Practice) systems when a clinical user of the conneQt Toolbar has completed an activity in your system and previewed the document for inclusion in the patient's local record. To use this endpoint, your system must follow the principles and functions of instant messaging, as detailed in - Pre-approved Messaging.

Message expiry

In the case of 'instant' messages, the user must have logged in and run the toolbar for the message to be processed. To ensure messages are not held indefinitely, after a certain period, 'instant' messages are automatically converted to standard toolbar messages. They can then be processed through regular procedures

'Instant' Message Failure to import

If an 'instant' message cannot be automatically imported into the patient record, it will be converted into a standard toolbar message with a 'PENDING' status and a sub-status of 'Failed instant message import.' It will then be processed through the regular procedures.

Permitted attachment types

The service supports the following content types for attachments:

  • PDF (application/pdf): Documents in Portable Document Format.
  • JPEG (image/jpeg): Images in JPEG format.
  • Plain Text (text/plain): Unformatted text content.
  • Consultation Notes (text/vnd.qxlva.conneqt.consultation): Custom-defined content type used to carry plain text consultation notes.

Consultation Notes

Attachments defined as the 'Consultation Notes' MIME type ('text/vnd.qxlva.conneqt.consultation') will be applied to the patient record as user-searchable text, rather than as a file upload. Therefore, the content of attachments of this type must be in plain text format. The exact way this text appears in the patient record may vary depending on the GP System.

The transport process for attachments of this type via the API is otherwise identical to other attachment types. The content is included in the API message as a Base64 encoded block along with a filename.

Attachment size limit

There is a 5MB size limit for each attachment. This limit is set by the receiving GP systems and applies to each individual attachment.

Allowed number of attachments

You can include a maximum of 10 attachments in a single message.

HTTP Definition

Method: POST
Endpoint URL: /api/v1/messages/instant

Headers

The following HTTP headers are required with this request:

Name Data Type Notes
ApiKey string The unique key issued by Quicksilva to identify your system.
Content-Type string Must define the request content as 'application/json'.
AccessToken string The token used to verify the authorization of a user to perform instant messaging.

URL Parameters

The request contains no URL parameters.

Request JSON Definition

Name Cardinality Data Type Notes
messageId 1..1 uuid A unique identifier for this specific message instance.
type 1..1 string Fixed value that must be 'ToolbarInstantMessage'.
topic 1..1 string A system-defined category used to classify this message.
recipient 1..1 object The intended recipient of this message.
recipient.id 1..1 object An object containing identification data for the recipient.
recipient.id.type 1..1 string A string indicating the type of recipient ID being used.
recipient.id.value 1..1 string The value of the recipient ID, such as an organisation's ODS code.
subject 1..1 object The subject (i.e. patient) of this message
subject.id 1..1 object An object containing identification data for the subject.
subject.id.type 1..1 string Specifies the type of subject ID being used, like "VerifiedNhsNumber."
subject.id.value 1..1 string The value of the subject ID being used, such as a patient's verified NHS number.
expiryDateTime 0..1 date-time The date and time when the message will expire, and it will no longer be eligible for delivery. Use a full RFC3339 timestamp with 'Z' or offset. It should be set in the future.
body 0..1 object Free-text information that will be displayed to the message recipient, if needed.
body.mimeType 1..1 string Specifies the type of content being conveyed, influencing its presentation.
body.content 1..1 string The textual representation of the message's body content.
attachments 1..10 array An array containing one or more (max 10) file attachments to be included with the message sent to the recipient.
attachments[0].mimeType 1..1 string Denotes the type of attachment being included in the message. See Permitted attachment types for allowed MIME types.
attachments[0].fileName 1..1 string The name of the file represented by the attachment. The file name provided may appear in recipient systems where supported. File name must be a valid Windows file name following the rules given here https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions, and may not have leading and/or trailing whitespace or periods.
attachments[0].content 1..1 string The content of the attachment, encoded in Base64.
codedDataItems 0..* array Optional SNOMED Coded Data Items; a list of SNOMED coded data items representing the content of the attachment included in this message.
codedDataItems[0].code 1..1 string The specific SNOMED code.
codedDataItems[0].value 0..1 number A value associated with the SNOMED code, if applicable.
codedDataItems[0].unit 0..1 string Units of measurement associated with the value, if applicable.
codedDataItems[0].additionalText 0..1 string Additional descriptive free text linked to the code.
Note

This endpoint requires the type field to be populated with the value "ToolbarInstantMessage" to ensure your system has not sent a request intended for the standard messaging endpoint.

POST https://int.conneqt.health/api/v1/messages/instant HTTP/1.1
Content-Type: application/json; charset=utf-8
ApiKey: <API-KEY-PLACEHOLDER>
AccessToken: ad2ae93e-f2e4-4722-8c20-42ba5a71b3ff

{
  "messageId": "869c3439-fcb8-4546-b372-2af2bf54e197",
  "type": "ToolbarInstantMessage",
  "topic": "DispenseEventNotification",
  "recipient": {
    "id": {
      "value": "GPPRAC001",
      "type": "OcsClientIdentifier"
    }
  },
  "subject": {
    "id": {
      "value": "9547852140",
      "type": "VerifiedNhsNumber"
    }
  },
  "body": {
    "mimeType": "text/plain",
    "fileName": "Dispense Notification.pdf",
    "content": "Dispense Event Notification: Copy of prescription form in attached PDF"
  },
  "attachments": [
    {
      "mimeType": "application/pdf",
      "content": "QW4gZXhhbXBsZSBvZiBhIHBheWxvYWQgYmVpbmcgZW5jb2RlZCBmb3IgdHJhbnNmZXIKVGhpcyBpcyBhIHNpbXBsZSB0ZXh0IHBheW"
    }
  ],
  "codedDataItems": [
    {
      "code": "407554009",
      "value": 140,
      "units": "mmHg",
      "additionalText": "Sitting systolic blood pressure"
    },
    {
      "code": "407555005",
      "value": 80,
      "units": "mmHg",
      "additionalText": "Sitting diastolic blood pressure"
    },
    {
      "code": "248223005",
      "additionalText": "Feeling faint"
    }
  ]
}
Note

The example attachment content provided is truncated and should not be considered a valid Base64-encoded PDF file.

Response JSON Definition

Name Cardinality Data Type Notes
messageStatusEndpoint 1..1 url The endpoint location to obtain delivery status data for the sent message. 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "messageStatusEndpoint": "/api/v1/messages/869c3439-fcb8-4546-b372-2af2bf54e197/status"
}

Error Responses

If there was an issue processing your request, a HTTP error response will be returned, containing details of the issue. Common problems include:

  • One or more invalid data items were found in the request.
  • The intended recipient organisation is not one that uses our system.

The system uses the definition of an IETF Problem, as described in RFC 7807, in error responses to provide machine-readable details of why a request was rejected. The content of the Problem returned depends on the nature of the issue.

HTTP Response Code HTTP Reason Code Description
400 Bad Request Validation issues found in your request.
401 Unauthorized Missing or Invalid API Key in the Request Header.
403 Forbidden Unauthorized Client System - The Provided API Key Is Valid but Not Authorized.
500 Internal Server Error Internal Server Error - An Internal Server Error Prevented the Request from Being Processed. 
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https//qxlva.com/im1toolbar/documentation/api/v1/validation-error",
  "title": "Request Validation Error",
  "status": 400,
  "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000",
  "invalidParameters": [
    {
      "name": "recipient",
      "reason": "Unknown Recipient"
    },
    {
      "name": "body.mimeType",
      "reason": "Must be 'text/plain' or 'text/html'",
      "value": "application/pdf"
    }
  ]
}

See Also