Messages

A message sent or received via the CRM.

Received messages are associated with a location based on the email address or VMN (virtual mobile number) they were received via. Where possible they are then associated with a care seeker, service user (and potentially a service user key contact) or location contact.

The message object

Attributes

  • _id
    string

    A unique Id for the message.

  • anonymized
    string

    Date/time flag indicating when (if) the message's details were anonymized.

  • care_enquiry
    string

    The Id of the care enquiry this message relates to.

  • channel
    string

    The channel the message was sent or received over; email, sms.

  • content
    string

    The compiled content of the message.

  • correspondent
    string

    The name and email address of the person being corresponded with.

  • created
    string

    The date/time the message was created.

  • date_time
    string

    The date/time the message was sent or received.

  • delivery_status
    string

    The message delivery status (only applicable to messages sent via the application, based on the response from the sender service; sent, failed, queued, unknown.

  • destination
    string

    The email address or telephone number that the message was sent to.

  • direction
    string

    The direction of the message; inbound, outbound.

  • download_id
    string

    An Id used to associated the message with a download.

  • external_service
    string

    The service used to send or relay the message.

  • invoices
    list of strings

    A list of Ids for invoices sent with the email (invoices are attached as PDFs).

  • literature_items
    list of strings

    A list of Ids for literature items sent with the email.

  • literature_items_downloaded
    list of strings

    A list of Ids for the literature items the recipient has downloaded by the recipient of the email.

  • location
    string

    The Id of the location this message relates to.

  • location_contact
    string

    The Id of the location contact this message relates to.

  • modified
    string

    The date/time the group was modified.

  • origin
    string

    The email address or telephone number that the message originates from.

  • read
    string

    Date/time flag indicating when the message was marked as read.

  • read_by
    string

    The Id of the user that flagged the message as read.

  • reply_to
    string

    The Id of the user that this message is in reply to.

  • resolved
    string

    Date/Time flag indicating when the issue against message was set as resolved.

  • resolved_by
    string

    The Id of the user that flagged the message as resolved.

  • sent_by
    string

    The Id of the user the message was sent by.

  • service_user
    string

    The Id of the service user this message relates to.

  • service_user_contact
    string

    The Id of the service user contact this message relates to.

  • subject
    string

    The subject of the message (if sending/receiving an email).

  • tags
    list of strings

    A list of tags assigned to the message.

  • thread_id
    string

    An Id used to associated the message with a other messages in a thread.

The message object
{
    "_id": "66bfb4c19ab4e3d6eb735966",
    "anonymized": null,
    "care_enquiry": "66bfb4c09ab4e3d6eb735694",
    "channel": "email",
    "content": "Dear Gordon,\n\nIt was lovely to speak to you earlier, please find a link below to download the brochure for Douglas Court. There's lots of information in the brochure but if you have any further questions please don't hesitate to get in touch.\n\nBest regards,\n\nMark Walford / Owner\n",
    "correspondent": "Gordon Parker gordon.parker@ee.co.uk",
    "created": "2024-08-16 20:21:21",
    "date_time": "2024-08-13 13:00:00",
    "delivery_status": "sent",
    "destination": "gordon.parker@ee.co.uk",
    "direction": "outbound",
    "download_id": "fcfe2927-04a3-4579-aac1-3e7dcf8db7db",
    "external_service": "oakridge",
    "invoices": null,
    "literature_items": [
        "66bfb4bc9ab4e3d6eb734912"
    ],
    "literature_items_downloaded": [],
    "location": "66bfb4bb9ab4e3d6eb734900",
    "location_contact": null,
    "modified": "2024-08-16 20:21:21",
    "origin": "demo@marshallcare.carehq.co.uk",
    "read": null,
    "read_by": null,
    "reply_to": null,
    "resolved": null,
    "resolved_by": null,
    "sent_by": "66bfb4bb9ab4e3d6eb73490c",
    "service_user": null,
    "service_user_contact": null,
    "subject": "Douglas Court brochure",
    "tags": [],
    "thread_id": null
}

List all messages

Return a list of messages.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

  • filters-anonymized
    optional
    default unset

    A filter that allows messages to be filtered by whether the message is anonymized.

    • unset
    • yes
    • no
  • filters-care_enquiry
    optional

    A filter that accepts a list of care enquiry Ids and filters messages to those where the receipient or sender is one of the care enquiries.

  • filters-channel
    optional

    A filter that accepts a list of delivery statuses and filters messages by the channel they were sent through.

    • email
    • sms
  • filters-delivery_status
    optional

    A filter that accepts a list of delivery statuses and filters messages by the status of their delivery.

    • sent
    • failed
    • queued
    • unknown
  • filters-direction
    optional

    A filter that allows messages to be filtered by the direction messages were sent in.

    • inbound
    • outbound
  • filters-end_date
    optional

    A filter that accepts a date and filters messages to those sent or received on or before the given date.

  • filters-ids
    optional

    A filter that accepts a list of Ids and filters the items returned to those with an Id in the list.

  • filters-location
    optional

    A filter that accepts a list of location Ids and filters messages by the location they were received for.

  • filters-location_contact
    optional

    A filter that accepts a list of location contact Ids and filters messages to those where the receipient or sender is one of the location contacts.

  • filters-modified_after
    optional

    A filter that accepts a date/time and filters the items returned to those modified after the date/time.

  • filters-modified_before
    optional

    A filter that accepts a date/time and filters the items returned to those modified before the date/time.

  • filters-q
    optional

    A case insensitive keyword filter applied to the following fields; correspondent, destination, origin.

  • filters-read
    optional
    default unset

    A filter that allows messages to be filtered by whether the message is flagged as having been read.

    • unset
    • yes
    • no
  • filters-reply_to_user
    optional

    A filter that accepts a list of user Ids and filters messages to those in reply to one of the users.

  • filters-sent_by
    optional

    A filter that accepts a list of user Ids and filters messages to those sent by one of the users.

  • filters-service_user
    optional

    A filter that accepts a list of service user Ids and filters messages to those where the receipient or sender is one of the service users.

  • filters-service_user_contact
    optional

    A filter that accepts a list of service user contact Ids and filters messages to those where the receipient or sender is one of the service user contacts.

  • filters-start_date
    optional

    A filter that accepts a date and filters messages to those sent or received on or after the given date.

  • page
    optional
    default 1

    The page number to fetch.

  • per_page
    optional
    default 10

    The number of items to return per page.

  • sort_by
    optional
    default _id

    A list of fields the returned items can be sorted by. Fields prefixed with minus (-) sign are sorted in descending order.

    • _id
    • created
    • modified
    • date_time

Response

Returns a page of messages.

GET
/v1/messages
var messages = apiClient.Request(
    HttpMethod.Get,
    "messages",
    new MultiValueDict()
        .Add("attributes", "content", "correspondent", "date_time")
        .Add("filters-channel", "sms")
        .Add("filters-direction", "inbound")
        .Add("sort_by", "date_time")
);
<?php

$messages = $api_client->request(
    'GET',
    'messages',
    [
        'attributes'=>['content', 'correspondent', 'date_time'],
        'filters-channel'=>['sms'],
        'filters-direction'=>['inbound'],
        'sort_by'=>'date_time'
    ]
);
messages = api_client(
    'GET',
    'messages',
    params={
        'attributes': ['content', 'correspondent', 'date_time'],
        'filters-channel': ['sms'],
        'sort_by': 'date_time'
    }
)
messages = api_client.request(
    'GET',
    'messages',
    params: {
        'attributes' => ['content', 'correspondent', 'date_time'],
        'filters-channel' => ['sms'],
        'filters-direction' => ['inbound'],
        'sort_by' => 'date_time'
    }
)
Response
{
    "item_count": 1,
    "items": [
        {
            "_id": "66bfb4c19ab4e3d6eb73596a",
            "content": "Hi Jason, this is Mark from Marshall Care, I know you normally pop into see your grandmother on the weekend so I just wanted to let you know she's having her hair cut Saturday between 2pm-4pm.",
            "correspondent": "Justin Wall +447790483280",
            "date_time": "2024-07-18 11:06:00"
        }
    ],
    "page": 1,
    "page_count": 1,
    "per_page": 10
}

Retrieve a message

Retrieve a message object.

Response

Returns a message object.

GET
/v1/messages/<message_id>
var message = apiClient.Request(HttpMessage.Get, $"messages/{messageId}");
<?php

$message = $api_client->request('GET', 'messages/' . $message_id);
message = api_client('GET', f'messages/{message_id}')
message = api_client.request('GET', "messages/#{message_id}")
Response
{
    "_id": "66bfb4c19ab4e3d6eb735966",
    "anonymized": null,
    "care_enquiry": "66bfb4c09ab4e3d6eb735694",
    "channel": "email",
    "content": "Dear Gordon,\n\nIt was lovely to speak to you earlier, please find a link below to download the brochure for Douglas Court. There's lots of information in the brochure but if you have any further questions please don't hesitate to get in touch.\n\nBest regards,\n\nMark Walford / Owner\n",
    "correspondent": "Gordon Parker gordon.parker@ee.co.uk",
    "created": "2024-08-16 20:21:21",
    "date_time": "2024-08-13 13:00:00",
    "delivery_status": "sent",
    "destination": "gordon.parker@ee.co.uk",
    "direction": "outbound",
    "download_id": "fcfe2927-04a3-4579-aac1-3e7dcf8db7db",
    "external_service": "oakridge",
    "invoices": null,
    "literature_items": [
        "66bfb4bc9ab4e3d6eb734912"
    ],
    "literature_items_downloaded": [],
    "location": "66bfb4bb9ab4e3d6eb734900",
    "location_contact": null,
    "modified": "2024-08-16 20:21:21",
    "origin": "demo@marshallcare.carehq.co.uk",
    "read": null,
    "read_by": null,
    "reply_to": null,
    "resolved": null,
    "resolved_by": null,
    "sent_by": "66bfb4bb9ab4e3d6eb73490c",
    "service_user": null,
    "service_user_contact": null,
    "subject": "Douglas Court brochure",
    "tags": [],
    "thread_id": null
}