openapi: 3.2.0 info: title: RentalReady Conversations API version: 1.0.0 (api) description: 'This API enables you to access and update resources from RentalReady (GuestReady PMS) ### Throttling Our API supports up to 400 requests per minute ' servers: - url: https://pms.rentalready.io/api/v3/ description: Base URL declared by the provider in apis.yml (roadmap#122). tags: - name: Conversations paths: /api/v3/conversation_flags/: get: operationId: conversation_flags_list description: Retrieve the triage flags a conversation can carry. The name is the one this property manager uses; class_name is the underlying colour. summary: List conversation flags parameters: - name: limit required: false in: query description: Number of results to return per page. schema: type: integer - name: offset required: false in: query description: The initial index from which to return the results. schema: type: integer tags: - Conversations security: - oauth2: - conversations:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedConversationFlagList' description: '' /api/v3/conversation_flags/{id}/: get: operationId: conversation_flags_retrieve description: Retrieve a single conversation flag by ID. summary: Retrieve conversation flag parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this conversation flag. required: true tags: - Conversations security: - oauth2: - conversations:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConversationFlag' description: '' /api/v3/conversations/: get: operationId: conversations_list description: Retrieve a list of conversations accessible to the current user. summary: List conversations parameters: - in: query name: created_after schema: type: string format: date-time - in: query name: created_before schema: type: string format: date-time - in: query name: flag_id schema: type: integer - name: limit required: false in: query description: Number of results to return per page. schema: type: integer - name: offset required: false in: query description: The initial index from which to return the results. schema: type: integer - name: ordering required: false in: query description: Which field to use when ordering the results. schema: type: string - in: query name: rental_id schema: type: string title: Contract number description: "This field is not editable after creation.\n ALWAYS fill it with the correct value" - in: query name: reservation_id schema: type: number - in: query name: status schema: type: string tags: - Conversations security: - oauth2: - conversations:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedConversationList' description: '' post: operationId: conversations_create description: Create a new conversation. summary: Create conversation tags: - Conversations requestBody: content: application/json: schema: $ref: '#/components/schemas/ConversationCreate' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ConversationCreate' multipart/form-data: schema: $ref: '#/components/schemas/ConversationCreate' security: - oauth2: - conversations:write responses: '201': content: application/json: schema: $ref: '#/components/schemas/ConversationCreate' description: '' /api/v3/conversations/{id}/: get: operationId: conversations_retrieve description: Retrieve a specific conversation by ID. summary: Retrieve conversation parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this conversation. required: true tags: - Conversations security: - oauth2: - conversations:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/Conversation' description: '' /api/v3/conversations/{id}/set_flag/: patch: operationId: conversations_set_flag_partial_update description: 'Put a triage flag on a conversation, or remove it. Flags are the mailbox''s triage queues; list the ids with the conversation_flags endpoint. `flag_id` is required and nullable: null removes the flag, while omitting the field is a 400, never a silent no-op. The change is recorded on the conversation''s event trail and noted on every ticket raised from the conversation, exactly as the mailbox does it.' summary: Set conversation flag parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this conversation. required: true tags: - Conversations requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedSetConversationFlag' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedSetConversationFlag' multipart/form-data: schema: $ref: '#/components/schemas/PatchedSetConversationFlag' security: - oauth2: - conversations:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/Conversation' description: '' '400': content: application/json: schema: example: flag_id: - This field is required. description: '' '403': content: application/json: schema: example: detail: Guest messaging write not allowed, permission missing. description: '' components: schemas: PaginatedConversationFlagList: type: object required: - count - results properties: count: type: integer example: 123 next: type: - string - 'null' format: uri example: http://api.example.org/accounts/?offset=400&limit=100 previous: type: - string - 'null' format: uri example: http://api.example.org/accounts/?offset=200&limit=100 results: type: array items: $ref: '#/components/schemas/ConversationFlag' limit: type: integer example: 50 Conversation: type: object properties: id: type: integer readOnly: true status: allOf: - $ref: '#/components/schemas/StatusFa3Enum' readOnly: true guest_id: type: - integer - 'null' readOnly: true guest_name: type: - string - 'null' readOnly: true description: Guest's full name, or null when the conversation has no guest. guest_email: type: - string - 'null' format: email readOnly: true rental_ids: type: array items: type: integer readOnly: true description: Ids of the properties (rentals) linked to this conversation. reservation_ids: type: array items: type: integer readOnly: true description: Ids of the reservations linked to this conversation. inquiry_ids: type: array items: type: integer readOnly: true description: Ids of the inquiries linked to this conversation. default_channel: type: - string - 'null' readOnly: true flag_id: type: - integer - 'null' readOnly: true description: Id of the triage flag on this conversation, or null when it is not flagged. Flags are the mailbox's triage queues; list them with the conversation_flags resource to map a colour to an id. flag_name: type: - string - 'null' description: Name of the triage flag as the caller's property manager renamed it, or null when the conversation is not flagged. Match on flag_class_name instead for a value that survives renames. readOnly: true flag_class_name: type: - string - 'null' readOnly: true description: Colour of the triage flag (for example 'pink', 'green'), or null when the conversation is not flagged. Stable across renames, unlike flag_name. last_message_id: type: - integer - 'null' readOnly: true description: Id of the most recent message in this conversation, or null when it has none. Read it with the messages resource. snooze_until: type: string format: date-time readOnly: true description: 'UTC timestamp the conversation stays snoozed until. Never null: a conversation that was never snoozed carries a past timestamp, so ''currently snoozed'' means snooze_until is in the FUTURE, not that a value is present. Every inbound guest message resets it to the time that message arrived, which un-snoozes the conversation.' automatic_ai_enabled: type: - boolean - 'null' readOnly: true description: 'Whether the AI answers this conversation automatically. Three-state: true, false, or null when it was never set (inherit the office default) -- null is not the same as false.' created: type: string format: date-time readOnly: true modified: type: string format: date-time readOnly: true description: UTC timestamp of the last change to the conversation row (the default list ordering). required: - automatic_ai_enabled - created - default_channel - flag_class_name - flag_id - flag_name - guest_email - guest_id - guest_name - id - inquiry_ids - last_message_id - modified - rental_ids - reservation_ids - snooze_until - status StatusFa3Enum: enum: - merged - opened - closed type: string description: '* `merged` - Merged * `opened` - Opened * `closed` - Closed' PatchedSetConversationFlag: type: object description: 'Write serializer for the ``set_flag`` action: one field, no silent no-op. Bound to the conversation instance (like the incident status-change serializers): ``update`` delegates to ``SetConversationFlagService``, so this path produces exactly the mailbox''s side effects -- the conversation event and the note on every ticket raised from the conversation. ``flag_id`` is REQUIRED and nullable, and the two are not the same thing: ``null`` removes the flag, while omitting the field is a 400. A missing field must never read as "leave it alone" on a single-field write -- an agent that meant to clear a flag and dropped the key would otherwise get a 200 back for a call that changed nothing. The queryset is unscoped, like the ``flag_id`` filter and the ``conversation_flags`` resource: ``ConversationFlag`` is global reference data, so narrowing it per tenant would only 400 a valid id.' properties: flag_id: type: - integer - 'null' description: Id of the triage flag to put on the conversation, or null to remove the flag. List the ids with the conversation_flags resource. ConversationFlag: type: object description: 'A triage flag, named AS THE CALLER''S PROPERTY MANAGER SEES IT. The rows themselves are global reference data (every tenant flags against the same handful of flags), but the ``name`` is per-property-manager: ``PropertyManagerConversationFlag`` renames a flag for one tenant, and that rename is what the mailbox shows and what an operations lead says. So ``name`` is resolved the same way here as on ``ConversationSerializer.flag_name`` -- the two must agree, or "the Pink queue" resolves to a different id depending on which endpoint answered.' properties: id: type: integer readOnly: true name: type: string readOnly: true class_name: type: string readOnly: true description: Colour of the flag (for example 'pink', 'green'). Stable across renames, unlike name. required: - class_name - id - name ConversationCreate: type: object properties: id: type: integer readOnly: true status: $ref: '#/components/schemas/StatusFa3Enum' rental_ids: type: array items: type: integer writeOnly: true reservation_ids: type: array items: type: integer writeOnly: true default_channel: type: - string - 'null' maxLength: 250 required: - id PaginatedConversationList: type: object required: - count - results properties: count: type: integer example: 123 next: type: - string - 'null' format: uri example: http://api.example.org/accounts/?offset=400&limit=100 previous: type: - string - 'null' format: uri example: http://api.example.org/accounts/?offset=200&limit=100 results: type: array items: $ref: '#/components/schemas/Conversation' limit: type: integer example: 50 securitySchemes: basicAuth: type: http scheme: basic cookieAuth: type: apiKey in: cookie name: sessionid oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: /o/authorize/ tokenUrl: /o/token/ refreshUrl: /o/token/ scopes: read: Read scope write: Write scope amenities:read: Read amenities amenities:write: Create, update and delete amenities photos:write: Create, update and delete photos reservations:read: Read reservations reservations:write: Create, update and cancel reservations reservation_platform:read: Read reservation platform reviews:read: Read reviews reviews:write: Write reviews owners:read: Read owners owners:write: Write owners hosts:read: Read hosts (deprecated) hosts:write: Write hosts (deprecated) offices:read: Read offices property_managers:read: Read property managers onboarding_requests:read: Read onboarding requests listing_requests:read: Read listing requests pricing:read: Read pricing pricing:write: Create, update and delete pricing users:read: Read user data calendar:read: Read calendar calendar:write: Write calendar rentals:read: Read rentals rentals:write: Create, update and delete rentals issues:read: Read issues issues:write: Write issues incidents:read: Read incidents incidents:write: Write incidents missions:read: Read missions missions:write: Write missions agents:read: Read agents smart_schedulers:read: Read smart schedulers smart_schedulers:write: Write smart schedulers neighbourhoods:read: Read neighbourhoods payment_links:read: Read payment links swikly_deposits:read: Read swikly deposits payout_adjustments:read: Read payout adjustments payout_adjustments:write: Write payout adjustments payment_acceptance_transactions:read: Read payment acceptance transactions payment_acceptance_transactions:write: Write payment acceptance transactions accounting_invoice:read: Read accounting invoices accounting_invoice:write: Write accounting invoices guest_registration:read: Read guest registration data conversations:read: Read conversations conversations:write: Write conversations messages:read: Read messages messages:write: Write messages inquiries:read: Read inquiries city_tax_rules:read: Read city tax rules custom_fields:read: Read custom fields custom_fields:write: Write custom fields tokenAuth: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token"