Messages

The Messages service allows messages exchanged between consumers and agents.

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

Supported Roles

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

Available Services

Messages

URI: /<API Version>/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
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
Pagination No
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
      },
      "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

URI: /<API Version>/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
    }
  }
}

Individual Message

URI: /<API Version>/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
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

URI: /<API Version>/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
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
Pagination No
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.

Individual Message Reply

URI: /<API Version>/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 Description
ResourceUri Character No No The resource URI to the message.
Id Character No No The Id for the message.
Type Character Yes Yes See the list of available message types below.
Body Character Yes No The body of the message.
CreatedTimestamp Timestamp No No The timestamp when the message was originally sent.
EventTimestamp Timestamp Yes When Type=ShowingRequest The requested showing date. The provided timestamp is assumed to be the date and time in the MLSs timezone.
ListingId Character Yes No The Id of the listing related to the message, when applicable.
Read Boolean Yes No If false, the message has not been flagged as "read" by the current user.
ReadTimestamp Timestamp Yes No The time when the message was read by the current user. If null, the message has not been read.
RecipientIds CharacterList Yes 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 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 Used when the sender will not be the current user. Supported only for IDX roles when a contact not logged in to their VOW account wishes to contact their agent.
Subject Character Yes 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 The Id for the user or contact record.
ResourceUri Character No No The URI to the user or contact record.
UserType Character No No The type of account. Possible values are Contact, Member, Office and Mls.
Name Character No No The recipient's full name.
OfficeId Character No No The Id of the office the member belongs to, when applicable.
Office Character No No The full name of the office the member belongs to, when applicable.
CompanyId Character No No The Id of the company the member belongs to, when applicable.
Company Character 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 true if there are replies to this message that can be viewed.
UnreadInThread Boolean 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 Yes No The full body of the message
ThreadInfo All No No Additional details about the thread of replies to the message.
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.