Buy Now

⋅

Using WPResidence API for Messages: A Complete Guide

wpresidence-api

Effective communication between agents, property owners, and clients is crucial for any real estate platform. The WPResidence API provides comprehensive endpoints for managing messages programmatically, enabling developers to create custom messaging solutions that integrate with existing systems. This guide explores how to leverage the API for efficient message management.

What Are Messages in WPResidence?

In WPResidence real estate wordpress theme, messages are stored as custom post types (wpestate_message) that facilitate communication between users of the platform. Messages have several key characteristics:

  • They connect two users: a sender and a recipient
  • Each message has a status (read/unread, new)
  • Messages can be deleted by either participant
  • They may contain text content and metadata
  • Messages can form conversation threads

Messages serve multiple purposes in a real estate context:

  • Property inquiries from potential buyers/renters
  • Client-agent communications
  • Inter-agent collaboration
  • Property viewing arrangement
  • Offer and negotiation discussions

Each message is stored with metadata including:

  • message_from_user: ID of the sender
  • message_to_user: ID of the recipient
  • message_status: Read/unread status
  • mess_status: General status (new, etc.)
  • first_content: Flag for conversation starters
  • Deletion flags for both participants

Listing Messages: Retrieving Data via API

To retrieve messages for the current user, use the messages endpoint.

Endpoint: POST /wpresidence/v1/messages

Authentication Requirements

  • Valid JWT token required
  • User must be logged in

Request Parameters

{
  "page": 1,
  "posts_per_page": 20,
  "fields": "ID,title,description,message_status,mess_status,other_user",
  "message_status": "unread",
  "mess_status": "new",
  "other_user": 42
}

Key parameters include:

  • page: Pagination control (default: 1)
  • posts_per_page: Results per page (default: 10)
  • fields: Comma-separated list of fields to include
  • message_status: Filter by message status (read, unread)
  • mess_status: Filter by general status (new)
  • other_user: Filter by conversation partner (user ID)
  • meta: Additional metadata filters (complex structure)

Response Structure

{
  "status": "success",
  "data": [
    {
      "ID": 1234,
      "title": "Message from user_login",
      "description": "I'm interested in viewing the property at 123 Main St...",
      "message_status": "unread",
      "mess_status": "new",
      "other_user": 42,
      "from_user_data": {
        "display_name": "John Smith",
        "user_email": "john@example.com",
        "user_login": "johnsmith"
      },
      "to_user_data": {
        "display_name": "Jane Realtor",
        "user_email": "jane@example.com",
        "user_login": "janerealtor"
      }
    },
    // Additional messages...
  ],
  "total": 15,
  "pages": 1
}

Best Practices for Message Listing

  1. Use Pagination: Implement paging for better performance with many messages
  2. Field Selection: Request only needed fields to reduce payload size
  3. Filter Appropriately: Use status filters to separate read/unread messages
  4. Conversation View: Group messages by other_user to create conversation threads
  5. Real-time Updates: Implement polling or websockets for near real-time messaging

Viewing Message Information

To retrieve details for a specific message, use the single message endpoint.

Endpoint: GET /wpresidence/v1/message/{id}

Request Parameters

  • id: (Required) Message ID (path parameter)
  • fields: (Optional) Comma-separated list of fields to include

Authentication and Permissions

Access is restricted to:

  • The message sender
  • The message recipient

Response Example

{
  "ID": 1234,
  "title": "Message from johnsmith",
  "description": "I'm interested in viewing the property at 123 Main St. Is it available this weekend?",
  "message_status": "read",
  "mess_status": "new",
  "other_user": 42,
  "from_user_data": {
    "display_name": "John Smith",
    "user_email": "john@example.com",
    "user_login": "johnsmith"
  },
  "to_user_data": {
    "display_name": "Jane Realtor",
    "user_email": "jane@example.com",
    "user_login": "janerealtor"
  }
}

Note: When a recipient views a message, it’s automatically marked as read (message_status is updated to “read”).

Adding a New Message (Request Structure & Fields)

New messages can be created using the message creation endpoint.

Endpoint: POST /wpresidence/v1/message/add

Authentication Requirements

  • Valid JWT token required
  • User must be logged in

Required Fields

  • to_user: Recipient user ID
  • subject: Message subject
  • message: Message content

Full Request Example

{
  "to_user": 42,
  "subject": "Property Inquiry - 123 Main St",
  "message": "Hello, I'm interested in scheduling a viewing for the property at 123 Main St this Saturday. Would 2pm work for you?",
  "first_content": "new_conversation"
}

Optional Fields

  • first_content: Set to any non-empty value to mark this as the start of a new conversation

Response

{
  "status": "success",
  "message_id": 1234,
  "message": "Message sent successfully."
}

System Actions on Creation

When a message is created:

  1. The message post is created with the sender as author
  2. Metadata is set for sender and recipient IDs
  3. Message status is set to “unread” for recipient
  4. Unread message counter is incremented for recipient
  5. Deletion flags are initialized to 0 for both users

Updating Messages

WPResidence’s API doesn’t provide a direct endpoint for updating message content after creation. This is by design to maintain the integrity of communications.

However, the system does update message metadata automatically:

  • When a recipient views a message, its status changes to “read”
  • Unread message counters are updated accordingly

Removing a Message from the System

Messages can be “deleted” by either participant using the message deletion endpoint.

Endpoint: DELETE /wpresidence/v1/message/delete/{id}

Authentication and Permissions

  • Valid JWT token required
  • User must be either the sender or recipient

How Message Deletion Works

WPResidence implements a “soft delete” approach:

  1. When a user deletes a message, it’s marked as deleted for that user only
  2. The message is only completely removed when both sender and recipient have deleted it
  3. When a message is fully deleted, any child messages (replies) are also deleted

Response

{
  "status": "success",
  "message": "Message deleted successfully."
}

Linking Messages to Users

Messages in WPResidence are inherently linked to users through their metadata.

Message-User Relationships

Each message connects two users:

  1. Sender: Stored in message_from_user metadata and as the post author
  2. Recipient: Stored in message_to_user metadata

Creating User-Specific Message Views

To display messages for a specific user:

  1. Inbox View: Filter messages where the current user is the recipient
{
  "meta": {
    "message_to_user": {
      "value": 123, // Current user ID
      "compare": "=",
      "type": "NUMERIC"
    },
    "delete_destination123": { // Current user ID
      "value": 0,
      "compare": "=",
      "type": "NUMERIC"
    }
  }
}
  1. Sent Messages View: Filter messages where the current user is the sender
{
  "meta": {
    "message_from_user": {
      "value": 123, // Current user ID
      "compare": "=",
      "type": "NUMERIC"
    },
    "delete_destination123": { // Current user ID
      "value": 0,
      "compare": "=",
      "type": "NUMERIC"
    }
  }
}
  1. Conversation View: Filter messages between two specific users
{
  "meta": {
    "relation": "OR",
    [
      {
        "relation": "AND",
        [
          {
            "message_from_user": {
              "value": 123, // Current user ID
              "compare": "=",
              "type": "NUMERIC"
            }
          },
          {
            "message_to_user": {
              "value": 456, // Other user ID
              "compare": "=",
              "type": "NUMERIC"
            }
          }
        ]
      },
      {
        "relation": "AND",
        [
          {
            "message_from_user": {
              "value": 456, // Other user ID
              "compare": "=",
              "type": "NUMERIC"
            }
          },
          {
            "message_to_user": {
              "value": 123, // Current user ID
              "compare": "=",
              "type": "NUMERIC"
            }
          }
        ]
      }
    ]
  }
}

Debugging API Errors

Common Error Types

  1. Authentication Errors
    • jwt_auth_failed: Invalid/missing JWT token
    • rest_forbidden: User not logged in
  2. Permission Errors
    • rest_forbidden: User doesn’t have permission to access the message
  3. Validation Errors
    • rest_missing_field: Required field missing (to_user, subject, message)
    • rest_invalid_message: Message ID not found or incorrect type
    • rest_message_not_found: Message doesn’t exist

Troubleshooting Techniques

  1. Verify Authentication
    • Check JWT token validity and expiration
    • Confirm the user is properly logged in
  2. Validate Request Format
    • Ensure JSON payload is well-formed
    • Check that all required fields are present
  3. Test With Postman
    • Use Postman or similar tools to verify API behavior
    • Save working requests as templates
  4. Enable Debugging
    • Turn on WordPress debugging for more detailed error messages
    • Check server logs for PHP errors not reported in API responses

Best Practices for Error Handling

  1. Implement Client-Side Validation
    • Validate required fields before sending requests
    • Check recipient exists before sending messages
  2. Use Try-Catch Blocks
    • Wrap API calls in try-catch blocks
    • Handle different error types appropriately
  3. User-Friendly Error Messages
    • Translate API error codes to user-friendly messages
    • Provide clear instructions on how to resolve issues
  4. Add Retry Logic
    • Implement automatic retries for network errors
    • Use exponential backoff for repeated failures

Best Practices for Message Management

  1. Optimized UI Design
    • Group messages in conversations
    • Clearly distinguish read/unread messages
    • Show sender details and timestamps
  2. Real-Time Updates
    • Implement polling or WebSockets for live updates
    • Update unread message counters in real-time
  3. Notification Integration
    • Send email or push notifications for new messages
    • Allow users to customize notification preferences
  4. Conversation Context
    • Show property details when messages relate to a listing
    • Link messages to relevant transactions or documents
  5. Message Templates
    • Provide pre-written templates for common inquiries
    • Enable quick responses with templated content
  6. Privacy Considerations
    • Ensure messages are only accessible to participants
    • Implement proper message retention policies
    • Consider encryption for sensitive communications

Conclusion

The WPResidence messaging API serves as an excellent foundation for crafting personalized communication systems within real estate platforms. By leveraging these endpoints, developers can create intuitive messaging experiences that enhance collaboration among agents, property owners, and clients alike.

Whether you are developing a tailored messaging interface, connecting with external communication tools, or establishing automated messaging workflows, the WPResidence API offers the necessary flexibility and functionality to effectively manage real estate communications.

Official documentation is here : https://www.postman.com/universal-eclipse-339362/wpresidence/overview

FAQ

How are messages stored in WPResidence, and what metadata links them to users?

In WPResidence, messages are stored as a custom post type named wpestate_message. Each message connects two users (a sender and a recipient) and is linked through metadata such as message_from_user (sender ID) and message_to_user (recipient ID). Messages also store status metadata like message_status (read/unread) and mess_status (for example, new), along with deletion flags for both participants and an optional first_content flag to mark conversation starters.

How do I list messages for the current user via the WPResidence API, and what filters are available?

To list messages for the current user, call POST /wpresidence/v1/messages with a valid JWT token while the user is logged in. You can paginate with page (default 1) and posts_per_page (default 10), reduce payload by specifying fields, and filter by message_status (read or unread), mess_status (for example, new), and other_user (a conversation partner user ID). The endpoint also supports a meta parameter for additional metadata-based filtering.

What happens to message read status when a user views a message?

When you retrieve a specific message via GET /wpresidence/v1/message/{id}, access is restricted to the sender and the recipient. When the recipient views the message, WPResidence automatically marks it as read by updating message_status to read, and unread counters are updated accordingly.

How do I create a new message using the WPResidence messaging API, and what fields are required?

Create a message by sending a POST request to /wpresidence/v1/message/add with a valid JWT token for a logged-in user. The required fields are to_user (recipient user ID), subject (message subject), and message (message content). You can optionally include first_content with any non-empty value to mark the message as the start of a new conversation; on creation, the message is stored with the sender as author, recipient status is set to unread, the recipient unread counter is incremented, and deletion flags are initialized for both users.

How does message deletion work in WPResidence, and when is a message fully removed?

WPResidence uses a soft delete model through DELETE /wpresidence/v1/message/delete/{id}, which requires a valid JWT token and that the user is either the sender or recipient. When one participant deletes a message, it is marked as deleted only for that user. The message is fully removed from the system only after both the sender and the recipient have deleted it, and when fully deleted, any child messages (replies) are also deleted.

Latest Posts

Read next