docs(swagger): fix public API schema definitions to match jbuilder responses (#13693)

## Description

This PR updates the OpenAPI schema definitions for Public API resources
(`public_conversation`, `public_message`, `public_contact`) so they
match the actual API responses produced by the jbuilder views.

These definitions were introduced in #2417 (2021-06) with a minimal set
of fields. The jbuilder views have since been updated (e.g. `uuid` in
#7255, `agent_last_seen_at` in #4377), but the Swagger definitions were
never updated. As a result, generated API clients get incorrect or
missing types. This change fixes that by aligning the schemas with the
implementation.

**Fixes #13692**

## Type of change

Please delete options that are not relevant.

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality not to work as expected)
- [x] This change requires a documentation update

## How Has This Been Tested?

- Compared each jbuilder view
(`app/views/public/api/v1/models/_conversation.json.jbuilder`,
`_message.json.jbuilder`, `_contact.json.jbuilder`) field-by-field
against the Swagger YAML definitions.
- Cross-referenced Ruby model enums (`Conversation.status`,
`Attachment.file_type`, `Message.message_type`) for enum values.
- Ran the swagger build (via the project’s `rake swagger:build` logic /
`json_refs` resolution) to regenerate `swagger.json` and tag group
files; confirmed the generated schemas contain the correct fields and
types.
- No runtime tests were run; this is a documentation/schema-only change.

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas *(N/A: schema definitions)*
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works *(N/A: documentation/schema only)*
- [ ] New and existing unit tests pass locally with my changes *(N/A: no
code under test)*
- [x] Any dependent changes have been merged and published in downstream
modules *(N/A: none)*

---

## Change summary (for reference)

### `public_conversation`
- Added missing fields: `uuid`, `status`, `contact_last_seen_at`,
`agent_last_seen_at`
- Fixed `inbox_id` type from `string` to `integer`
- Fixed `messages` items `$ref` from `message` to `public_message`
- Added property details for embedded `contact` object (`id`, `name`,
`email`, `phone_number`)
- Added `status` enum: `open`, `resolved`, `pending`, `snoozed`

### `public_message`
- Fixed `id`, `message_type`, `created_at`, `conversation_id` types
(string → integer where applicable)
- Fixed `content_attributes` type from `string` to `object`
- Added property details for `attachments` items and `sender` object
- Added `file_type` and `sender.type` enums

### `public_contact`
- Added missing `phone_number` field

---------

Co-authored-by: Sojan Jose <sojan@pepalo.com>

swagger/definitions/resource/public/contact.yml

@@ -7,11 +7,20 @@ properties:
     type: string
     description: The session identifier of the contact
   name:
-    type: string
-    description: Name of the contact
+    type:
+      - string
+      - 'null'
+    description: Name of the contact when available
   email:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Email of the contact
+  phone_number:
+    type:
+      - string
+      - 'null'
+    description: Phone number of the contact
   pubsub_token:
     type: string
     description: The token to be used to connect to chatwoot websocket

swagger/definitions/resource/public/contact_record.yml

@@ -0,0 +1,93 @@
+type: object
+additionalProperties: true
+description: Full serialized contact record returned when the public API renders a Contact model directly.
+properties:
+  id:
+    type: integer
+    description: Id of the contact
+  name:
+    type:
+      - string
+      - 'null'
+    description: Name of the contact when available
+  email:
+    type:
+      - string
+      - 'null'
+    description: Email of the contact
+  phone_number:
+    type:
+      - string
+      - 'null'
+    description: Phone number of the contact
+  identifier:
+    type:
+      - string
+      - 'null'
+    description: Identifier of the contact
+  blocked:
+    type: boolean
+    description: Whether the contact is blocked
+  additional_attributes:
+    type:
+      - object
+      - 'null'
+    description: Additional attributes of the contact when present
+  custom_attributes:
+    type:
+      - object
+      - 'null'
+    description: Custom attributes of the contact when present
+  contact_type:
+    type:
+      - string
+      - 'null'
+    description: Contact type of the contact when available
+  country_code:
+    type:
+      - string
+      - 'null'
+    description: Country code of the contact
+  last_activity_at:
+    type:
+      - string
+      - 'null'
+    description: Last activity timestamp of the contact in ISO 8601 format
+  created_at:
+    type:
+      - string
+      - 'null'
+    description: Created timestamp of the contact in ISO 8601 format
+  updated_at:
+    type:
+      - string
+      - 'null'
+    description: Updated timestamp of the contact in ISO 8601 format
+  last_name:
+    type:
+      - string
+      - 'null'
+    description: Last name of the contact
+  middle_name:
+    type:
+      - string
+      - 'null'
+    description: Middle name of the contact
+  location:
+    type:
+      - string
+      - 'null'
+    description: Location of the contact
+  account_id:
+    type: integer
+    description: Account id of the contact
+  company_id:
+    type:
+      - integer
+      - 'null'
+    description: Company id of the contact
+  label_list:
+    type: array
+    description: Labels applied to the contact
+    items:
+      type: string

swagger/definitions/resource/public/conversation.yml

@@ -3,14 +3,26 @@ properties:
   id:
     type: integer
     description: Id of the conversation
-  inbox_id:
+  uuid:
     type: string
+    description: UUID of the conversation
+  inbox_id:
+    type: integer
     description: The inbox id of the conversation
+  contact_last_seen_at:
+    type: integer
+    description: Timestamp of when the contact last seen the conversation (Unix timestamp)
+  status:
+    type: string
+    enum: ['open', 'resolved', 'pending', 'snoozed']
+    description: The status of the conversation
+  agent_last_seen_at:
+    type: integer
+    description: Timestamp of when the agent last seen the conversation (Unix timestamp)
   messages:
     type: array
     items:
-      $ref: '#/components/schemas/message'
+      $ref: '#/components/schemas/public_message'
     description: Messages in the conversation
   contact:
-    type: object
-    description: The contact information associated to the conversation
+    $ref: '#/components/schemas/public_contact_record'

swagger/definitions/resource/public/message.yml

@@ -1,38 +1,32 @@
 type: object
 properties:
   id:
-    type: string
+    type: integer
     description: Id of the message
   content:
-    type: string
-    description: Text content of the message
+    type:
+      - string
+      - 'null'
+    description: Text content of the message. Can be null for attachment-only messages.
   message_type:
-    type: string
-    description: Denotes the message type
+    type: integer
+    description: "Denotes the message type. Possible values: 0 (incoming), 1 (outgoing), 2 (activity), 3 (template)"
   content_type:
     type: string
     description: Content type of the message
   content_attributes:
-    type: string
+    type: object
     description: Additional content attributes of the message
   created_at:
-    type: string
-    description: Created at time stamp of the message
+    type: integer
+    description: Created at Unix timestamp of the message
   conversation_id:
-    type: string
-    description: Conversation Id of the message
+    type: integer
+    description: Display Id of the conversation the message belongs to
   attachments:
     type: array
-    items:
-      type: object
     description: Attachments if any
+    items:
+      $ref: '#/components/schemas/public_message_attachment'
   sender:
-    type: object
-    description: Details of the sender
-
-
-
-
-
-
-
+    $ref: '#/components/schemas/public_message_sender'

swagger/definitions/resource/public/message_attachment.yml

@@ -0,0 +1,60 @@
+type: object
+additionalProperties: true
+description: Attachment payload. Available fields vary by attachment file_type.
+properties:
+  id:
+    type: integer
+    description: Id of the attachment
+  message_id:
+    type: integer
+    description: Id of the parent message
+  file_type:
+    type: string
+    enum: ['image', 'audio', 'video', 'file', 'location', 'fallback', 'share', 'story_mention', 'contact', 'ig_reel', 'ig_post', 'ig_story', 'embed']
+    description: Type of the attached file
+  account_id:
+    type: integer
+    description: Id of the account
+  extension:
+    type:
+      - string
+      - 'null'
+    description: File extension
+  data_url:
+    type:
+      - string
+      - 'null'
+    description: URL of the file. Can be null when an attachment variant has no external URL.
+  thumb_url:
+    type: string
+    description: URL of the file thumbnail
+  file_size:
+    type: integer
+    description: File size in bytes
+  width:
+    type:
+      - integer
+      - 'null'
+    description: Width of the attachment when available
+  height:
+    type:
+      - integer
+      - 'null'
+    description: Height of the attachment when available
+  coordinates_lat:
+    type: number
+    description: Latitude for location attachments
+  coordinates_long:
+    type: number
+    description: Longitude for location attachments
+  fallback_title:
+    type:
+      - string
+      - 'null'
+    description: Fallback title for location, fallback, and contact attachments when available
+  meta:
+    type: object
+    description: Metadata for contact attachments
+  transcribed_text:
+    type: string
+    description: Transcribed text for audio attachments

swagger/definitions/resource/public/message_sender.yml

@@ -0,0 +1,70 @@
+type: object
+additionalProperties: true
+description: Polymorphic sender payload returned by push_event_data. Available fields vary by sender type.
+properties:
+  id:
+    type: integer
+    description: Id of the sender
+  name:
+    type:
+      - string
+      - 'null'
+    description: Name of the sender when available
+  avatar_url:
+    type: string
+    description: Avatar URL of the sender. Present for senders of type user, agent_bot, and captain_assistant. Not present for contact senders (use thumbnail instead).
+  thumbnail:
+    type: string
+    description: Avatar/thumbnail URL of the sender. Contact senders use this field; user senders may also include it.
+  type:
+    type: string
+    enum: ['contact', 'user', 'agent_bot', 'captain_assistant']
+    description: Type of the sender
+  available_name:
+    type:
+      - string
+      - 'null'
+    description: Display name for user senders
+  availability_status:
+    type:
+      - string
+      - 'null'
+    description: Availability status for user senders
+  email:
+    type:
+      - string
+      - 'null'
+    description: Email of the sender when the sender is a contact
+  phone_number:
+    type:
+      - string
+      - 'null'
+    description: Phone number of the sender when the sender is a contact
+  identifier:
+    type:
+      - string
+      - 'null'
+    description: Identifier of the sender when the sender is a contact
+  blocked:
+    type: boolean
+    description: Whether the sender is blocked when the sender is a contact
+  additional_attributes:
+    type:
+      - object
+      - 'null'
+    description: Additional attributes when the sender is a contact and available
+  custom_attributes:
+    type:
+      - object
+      - 'null'
+    description: Custom attributes when the sender is a contact and available
+  description:
+    type:
+      - string
+      - 'null'
+    description: Description when the sender is a captain assistant
+  created_at:
+    type:
+      - string
+      - 'null'
+    description: Created timestamp in ISO 8601 format when the sender is a captain assistant