Start New Conversation API

Endpoint #

POST /wp-json/rtcl/v1/my/chat/conversation

Description #

Start a new conversation and send the first message.

Authentication #

This endpoint is protected and requires:

• REST API enabled
• Valid API Key
• Valid JWT Bearer Token

Required Headers #

Header	Value
Authorization	Bearer YOUR_JWT_TOKEN
X-API-KEY	YOUR_API_KEY
Content-Type	application/json

Request Parameters #

Parameter	Type	Required	Description
listing_id	integer	✅ Yes	Listing ID to start chat
text	string	✅ Yes	Message text
files	array	❌ No	Optional: Images or files
temp_id	number	❌ No	Temporary frontend ID for message tracking

cURL Example (JSON Body) #

curl -X POST https://example.com/wp-json/rtcl/v1/my/chat/conversation \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "listing_id": 101,
  "text": "Hello, is this still available?",
  "temp_id": 123
}'

Success Response (200) #

{
    "con_id": 1,
    "listing": {
        "id": 101,
        "title": "Demo Listing House",
        "url": "http://example.com/listing/demo-listing-house/",
        "images": [
            {
                "ID": 201,
                "title": "demo_image1",
                "caption": "",
                "url": "http://example.com/wp-content/uploads/demo_image1.jpg",
                "alt": "",
                "src": "http://example.com/wp-content/uploads/demo_image1-924x462.jpg",
                "srcset": false,
                "sizes": {
                    "full": { "src": "http://example.com/wp-content/uploads/demo_image1.jpg", "width": 1170, "height": 640 },
                    "medium": { "src": "http://example.com/wp-content/uploads/demo_image1.jpg", "width": 300, "height": 164 },
                    "thumbnail": { "src": "http://example.com/wp-content/uploads/demo_image1.jpg", "width": 150, "height": 82 }
                },
                "mime_type": "image/jpeg",
                "src_w": 870,
                "src_h": 435,
                "srcset_sizes": "(max-width: 870px) 100vw, 870px"
            },
            {
                "ID": 202,
                "title": "demo_image2",
                "caption": "",
                "url": "http://example.com/wp-content/uploads/demo_image2.jpg",
                "alt": "",
                "src": "http://example.com/wp-content/uploads/demo_image2-924x462.jpg",
                "srcset": false,
                "sizes": {
                    "full": { "src": "http://example.com/wp-content/uploads/demo_image2.jpg", "width": 1024, "height": 529 },
                    "medium": { "src": "http://example.com/wp-content/uploads/demo_image2.jpg", "width": 300, "height": 155 },
                    "thumbnail": { "src": "http://example.com/wp-content/uploads/demo_image2.jpg", "width": 150, "height": 77 }
                },
                "mime_type": "image/jpeg",
                "src_w": 870,
                "src_h": 435,
                "srcset_sizes": "(max-width: 870px) 100vw, 870px"
            }
        ],
        "amount": "<div class=\"rtcl-price price-type-fixed\"><span class=\"rtcl-price-amount amount\"><bdi>1,000<span class=\"rtcl-price-currencySymbol\">&#36;</span></bdi></span></div>",
        "raw_price": "1000",
        "location": [],
        "category": [
            {
                "term_id": 1,
                "name": "Demo Category",
                "slug": "demo-category",
                "term_group": 0,
                "term_taxonomy_id": 1,
                "taxonomy": "rtcl_category",
                "description": "",
                "parent": 0,
                "count": 3,
                "filter": "raw"
            }
        ]
    },
    "unread_count": 0,
    "sender": {
        "id": 1,
        "name": "Demo User 1",
        "email": "user1@example.com",
        "phone": "",
        "whatsapp": "",
        "website": "",
        "profile_picture": "https://www.gravatar.com/avatar/demo1?s=96&d=mm&r=g"
    },
    "recipient": {
        "id": 2,
        "name": "Demo User 2",
        "email": "user2@example.com",
        "phone": "",
        "whatsapp": "",
        "website": "",
        "profile_picture": "https://www.gravatar.com/avatar/demo2?s=96&d=mm&r=g"
    },
    "listing_id": 101,
    "sender_id": 1,
    "recipient_id": 2,
    "sender_delete": false,
    "recipient_delete": false,
    "last_message_id": 1,
    "sender_review": false,
    "recipient_review": false,
    "invert_review": false,
    "created_at": "2026-01-27 11:15:27",
    "updated_at": "2026-01-27 11:15:27",
    "last_message": "Hello",
    "last_message_created_at": "2026-01-27 11:15:27",
    "newMessage": {
        "message_id": 1,
        "con_id": 1,
        "source_id": 1,
        "message": "Hello",
        "meta": null,
        "attachments": null,
        "type": "text",
        "is_read": 0,
        "created_at": "2026-01-27 11:15:27",
        "temp_id": ""
    }
}

Error Responses #

Not Logged In (403) #

{
  "code": "FORBIDDEN",
  "message": "You are not logged in."
}

Invalid Conversation / No Access (403) #

{
  "code": "FORBIDDEN",
  "message": "You are not permitted to access this conversation."
}

Missing Authorization Header #

{
  "status": "error",
  "error": "MISSING_AUTHORIZATION_HEADER",
  "code": "401",
  "error_message": "Authorization header not received. Either authorization header was not sent or it was removed by your server due to security reasons."
}

Invalid Authorization Token Type #

{
  "status": "error",
  "error": "INVALID_AUTHORIZATION_HEADER_TOKEN_TYPE",
  "code": "401",
  "error_message": "Authorization header must be type of Bearer Token."
}

Invalid JWT Format (Segment Fault) #

{
  "status": "error",
  "error": "SEGMENT_FAULT",
  "code": "401",
  "error_message": "Incorrect JWT Format."
}

Invalid JWT Signature #

{
  "status": "error",
  "error": "INVALID_TOKEN",
  "code": "401",
  "error_message": "JWT signature verification failed."
}

REST API Access Disabled #

{
  "code": "DENIED_REST_API",
  "message": "Denied api call",
  "data": {
    "status": 403
  }
}