Messages

The Messages service allows messages exchanged between consumers and agents.

  1. Supported Roles
  2. Available Services
    1. Messages
    2. Unread Message Count
    3. Marking All Messages as Read
    4. Individual Message
    5. Message Replies
    6. Individual Message Reply
  3. Messages Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads Writes Notes
IDX No Yes
Public No No
VOW Yes Yes
Portal Yes Yes
Private Yes Yes
More information about roles may be found here.

Available Services

Messages

/<API Version>/messages
/<API Version>/contacts/<Contact.Id>/messages

Messages are ordered by time sent, with the most recent messages first.

HTTP Method Description Conditional Notes
GET Returns messages sent or received by the current user No
POST Creates a new message No Cannot be accessed as a subservice of /v1/contacts
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
Parameter Required Notes
Standard search and paging syntax No With an _orderby of LastMessageInThreadTimestamp, messages will be ordered by the most recent timestamp of any reply in the thread.
Standard expansion parameters No

GET Response

{
  "D": {
    "Success": true,
    "Results": [{
      "Id": "20110353423434130982000000",
      "ResourceUri": "/v1/messages/20110353423434130982000000",
      "Type": "ShowingRequest",
      "SenderId": "20110112234857732941000000",
      "Sender": {
        "Id": "20110112234857732941000000",
        "ResourceUri": "/v1/accounts/20110112234857732941000000",
        "UserType": "Member",
        "Name": "Joe Realtor",
        "OfficeId": "20100113238853732842000000",
        "Office": "Joe's Realty",
        "CompanyId": null,
        "Company": null
      },
      "RecipientIds": ["20120212334957232744000000"],
      "Recipients": [{
        "Id": "20120212334957232744000000",
        "ResourceUri": "/v1/accounts/20120212334957232744000000",
        "UserType": "Member",
        "Name": "Sue Realtor",
        "OfficeId": "20100113238853732842000000",
        "Office": "Joe's Realty",
        "CompanyId": null,
        "Company": null
      }],
      "ThreadInfo": {
        "HasReplies": true,
        "UnreadInThread": true,
        "LastMessageTimestamp": "2013-06-11T11:00:00"
      },
      "Subject": "Showing Request For 123 Main St, MLS # 12-345",
      "Body": "A showing is requested for ...",
      "ListingId": "20110112234857732941000000",
      "ReplyToId": null,
      "RecipientIds": "20130212233857332441000000",
      "CreatedTimestamp": "2013-06-11T11:00:00",
      "ModificationTimestamp": "2013-06-11T11:00:00"
    }]
  }
}

POST Request

Request body: 
{
    "D": {
        "Messages": [
            {
                "Type": "ShowingRequest",
                "EventTimestamp": "2011-09-15T14:00:00",
                "SenderId": "20110112234857732941000000",
                "Subject": "Showing Request For 123 Main St, MLS # 12-345",
                "Body": "A showing is requested for ...",
                "ListingId": "20110112234857732941000000"
            }
        ]
    }
}

POST Response

The standard success/fail response is returned.

Unread Message Count

/<API Version>/messages/unread
/<API Version>/contacts/<Contact.Id>/messages/unread

Returns the unread message count in the Pagination attribute

HTTP Method Description Conditional Notes
GET Returns unread message count No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
  • None

GET Response

{
  "D": {
    "Success": true,
    "Results": [],
    "Pagination": {
      "TotalRows": 78,
      "PageSize": 1,
      "TotalPages": 1,
      "CurrentPage": 1
    }
  }
}

Marking All Messages as Read

/<API Version>/messages/before/<Datetime>

Marks all messages as Read if sent prior to a given date.

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Flags as read No
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

PUT Request

Request body: 
{
   "D":{
     "Read": true
   }
}

PUT Response

The standard success/fail response is returned.

Individual Message

/<API Version>/messages/<Message.Id>
/<API Version>/contacts/<Contact.Id>/messages/<Message.Id>

HTTP Method Description Conditional Notes
GET Returns an individual message sent or received by the current user No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Marks a message as Read No Cannot be accessed as a subservice of /v1/contacts
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
Parameter Required Notes
Standard expansion parameters No

GET Response

See the GET request section for for the Messages service.

PUT Request

Request body: 
{
    "D": {
      "Read": true
    }
}

PUT Response

The standard success/fail response is returned.

Message Replies

/<API Version>/messages/<Message.Id>/replies
/<API Version>/contacts/<Contact.Id>/messages/<Message.Id>/replies

Messages returned by this service are replies to the message identified by Message.Id in the URI. You can only create message replies for top level messages, as only a single level of message threads is supported.

HTTP Method Description Conditional Notes
GET Returns direct responses to the message specified by Message.Id No
POST Creates a reply. ReplyTo is detected from Message.Id, and need not be supplied with the POST request. No Cannot be accessed as a subservice of /v1/contacts
PUT Marks all replies as Read. No Cannot be accessed as a subservice of /v1/contacts
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
Parameter Required Notes
Standard search and paging syntax No With an _orderby of LastMessageInThreadTimestamp, messages will be ordered by the most recent timestamp of any reply in the thread.
Standard expansion parameters No

GET Response

See the GET request section for for the Messages service.

POST Request

Request body:

See the POST request section for for the Message service.

POST Response

The standard success/fail response is returned.

PUT Request

Request body: 
{
    "D": {
      "Read": true
    }
}

PUT Response

The standard success/fail response is returned.

Individual Message Reply

/<API Version>/messages/<Message.Id>/replies/<Message.Id>
/<API Version>/contacts/<Contact.Id>/messages/<Message.Id>/replies/<Message.Id>

HTTP Method Description Conditional Notes
GET Returns an individual reply to the message specified by Message.Id No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
Parameter Required Notes
Standard expansion parameters No

GET Response

See the GET request section for for the Messages service.

Messages Description

Attribute Data Type Writeable Required Searchable Description
ResourceUri Character No No No The resource URI to the message.
Id Character No No No The Id for the message.
Type Character Yes Yes No See the list of available message types below.
Body Character Yes No No The body of the message.
CreatedTimestamp Timestamp No No Yes The timestamp when the message was originally sent.
EventDate Date No When Type=showingFdbk or Type=ShowingRequest No The requested showing/feedback date.
EventTimestamp Timestamp Yes When Type=ShowingRequest No The requested showing date. The provided timestamp is assumed to be the date and time in the MLSs timezone.
ListingId Character Yes No Yes The Id of the listing related to the message, when applicable.
Read Boolean Yes No No If false, the message has not been flagged as "read" by the current user.
ReadTimestamp Timestamp Yes No No The time when the message was read by the current user. If null, the message has not been read.
Note: If the message is not explicitly read, but instead flagged as read by the service that bulk reads messages, this timestamp will be set to the most recent DateTime values supplied to that service.
RecipientIds CharacterList Yes No No An array of Account or Contact IDs for the recipients of the message. Only populated if the current user is the message sender.
ReplyToId Character No No Yes The message Id the current message is a response to. If null, the current message is not a reply to another message. Use the Message Replies service to create replies.
SenderId Character Yes No Yes Used when the sender will not be the current user. Supported only for IDX roles when a contact not logged in to their VOW/Portal account wishes to contact their agent.
Subject Character Yes No No The subject of the message. 500 characters max.
Recipients Expansion More detail about users whose Ids are specified in the RecipientIds array.
Id Character No No No The Id for the user or contact record.
ResourceUri Character No No No The URI to the user or contact record.
UserType Character No No No The type of account. Possible values are Contact, Member, Office and Mls.
Name Character No No No The recipient's full name.
OfficeId Character No No No The Id of the office the member belongs to, when applicable.
Office Character No No No The full name of the office the member belongs to, when applicable.
CompanyId Character No No No The Id of the company the member belongs to, when applicable.
Company Character No No No The full name of the office the member belongs to, when applicable.
Sender Expansion This has the same attributes as the expansion above.
ThreadInfo Expansion
HasReplies Boolean No No No true if there are replies to this message that can be viewed.
LastMessageTimestamp DateTime No No No The timestamp of the most recent message in the thread.
UnreadInThread Boolean No No No true if any messages in the thread are unread.

Message Types

Type Creation Supported? Description
ContactMe No A request by a consumer to be contacted by an agent.
General Yes A basic message between an agent and a client.
Note No A private note.
OpenHouseFeedback No Feedback about an open house.
RemapRecommendation No A recommendation to remap a listing.
Reply Yes Any message that is a response (e.g. has a ReplyToId value) to another message.
ShowingConfirmation No Either a confirmation or rejection response to a ShowingRequest.
ShowingFeedback No Feedback after a showing.
ShowingRequest No A request for a showing appointment.
ShowingFeedbackRequest No A request for feedback after a showing appointment.

Expansions

Expansion Roles Single Record Only? Selection Support? Description
Body All No No The full body of the message.
BodyText All No No The full body of the message excluding all html.
ThreadInfo All No No Additional details about the thread of replies to the message.
ThreadPreview All No No Returns the first unread message or if none, the last message, in the thread.This message will include its Body.
Recipients All No No A list of basic recipient data, including name, user type, and office information.
Sender All No No A list of basic sender data, including name, user type, and office information.

API Explorer

The API Explorer does not currently support this service.