GuestReady Conversations API

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"