# Send a Message

Send a message to a patient via SMS, email, NHS App, or as a Hero-only audit record.
**Message types:**
- `sms` — Sent via the practice's configured SMS provider (e.g. Firetext)
- `email` — Sent via Hero's email service (AWS SES)
- `nhs_app` — Delivered through the NHS App
- `hero` — Not delivered to the patient; used as an audit log for messages sent externally

Set `write_to_record: true` to persist the message in the patient's EHR (EMIS/TPP) after clinician approval.

Endpoint: POST /v1/messages/send
Version: 1.0.0
Security: apiKeyAuth, practiceGroupId

## Security:

  - `apiKeyAuth` (unknown)
    apiKey in header x-api-key

  - `practiceGroupId` (unknown)
    apiKey in header x-practice-group-id

## Request fields (application/json):

  - `patient_id` (string, required)
    The Hero patient the message relates to

  - `message_type` (string, required)
    Defines if the message will be sent on via Hero's comms tools, and by what method
    Enum: "hero", "sms", "email", "nhs_app"

  - `message_string` (string, required)
    Message content to be sent from Hero

  - `recipient_contact_detail` (string)
    Where the message will be sent (e.g. patient@email.com or +44 79000000000). If no value is provided a default will be picked from the patients record (for that contact method, SMS/Email).

  - `fallback_contact_detail` (string)

  - `fallback_message_type` (string)
    Enum: "sms", "email"

  - `write_to_record` (boolean)
    Flags if the message should be written to the EHR record post-approval

  - `encrypted` (any)
    Deprecated. This field is ignored — messages are no longer encrypted at the platform layer.

  - `snomed_code` (string)
    SNOMED code to be attached to the EHR record entry.  Default value applied if not passed and write_to_record is true

  - `snomed_term` (string)
    SNOMED term to be attached to the EHR record entry. Default value applied if not passed and write_to_record is true

  - `task_id` (string)
    Task ID to be attached to a task

  - `attachment_uuid` (string)

  - `short_link_id` (string)

  - `assignee_id` (number)
    Optional. ID of the Admin or AdminTeam assigned to the message

  - `assignee_type` (string)
    Type of the assignee, either Admin or AdminTeam, assigned to the message

  - `send_at` (string)
    Specifies the scheduled date and time to send the message.

  - `episode_id` (string)

## Response 200:

  - `200` (unknown)
    Ok

## Response 200 fields (application/json):

  - `message_id` (string, required)

  - `content` (string, required)

  - `created_at` (string, required)

  - `snomed_code` (string)

  - `write_to_record` (boolean, required)

  - `auth_token` (string)

  - `confirm_write_to_record_url` (string)

  - `submitted_by` (string)

  - `send_at` (string)

## Response 400:

  - `400` (unknown)
    Validation error — missing or invalid fields

## Response 400 fields (application/json):

  - `error` (boolean, required)
    Example: true

  - `statusCode` (number, required)
    Example: 400

  - `message` (array, required)

  - `message.code` (string, required)
    Example: invalid_type

  - `message.expected` (string, required)
    Example: string

  - `message.path` (array, required)
    Example: ["patient_id"]

  - `message.message` (string, required)
    Example: Required

## Response 403:

  - `403` (unknown)
    Forbidden - missing policy or scope

## Response 404:

  - `404` (unknown)
    Patient not found

## Response 422:

  - `422` (unknown)
    Unprocessable — patient does not have the required contact detail for the chosen message type

## Response 429:

  - `429` (unknown)
    Too Many Requests

## Response 500:

  - `500` (unknown)
    Unknown error