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/index.yml

@@ -82,10 +82,16 @@ audit_log:
 ## public resources
 public_contact:
   $ref: ./resource/public/contact.yml
+public_contact_record:
+  $ref: ./resource/public/contact_record.yml
 public_conversation:
   $ref: ./resource/public/conversation.yml
 public_message:
   $ref: ./resource/public/message.yml
+public_message_attachment:
+  $ref: ./resource/public/message_attachment.yml
+public_message_sender:
+  $ref: ./resource/public/message_sender.yml
 public_inbox:
   $ref: ./resource/public/inbox.yml
 

swagger/definitions/resource/public/contact.yml

@@ -7,11 +7,20 @@ properties:
     type: string
     description: The session identifier of the contact
   name:
-    type: string
+    type:
-    description: Name of the contact
+      - 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
+    $ref: '#/components/schemas/public_contact_record'
-    description: The contact information associated to the conversation

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
+    type:
-    description: Text content of the message
+      - string
+      - 'null'
+    description: Text content of the message. Can be null for attachment-only messages.
   message_type:
-    type: string
+    type: integer
-    description: Denotes the message type
+    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
+    type: integer
-    description: Created at time stamp of the message
+    description: Created at Unix timestamp of the message
   conversation_id:
-    type: string
+    type: integer
-    description: Conversation Id of the message
+    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
+    $ref: '#/components/schemas/public_message_sender'
-    description: Details of the 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

swagger/paths/public/inboxes/contacts/update.yml

@@ -16,7 +16,7 @@ responses:
     content:
       application/json:
         schema:
-          $ref: '#/components/schemas/public_contact'
+          $ref: '#/components/schemas/public_contact_record'
   '401':
     description: Unauthorized
     content:

swagger/swagger.json

@@ -971,7 +971,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/public_contact"
+                  "$ref": "#/components/schemas/public_contact_record"
                 }
               }
             }
@@ -10750,19 +10750,163 @@
             "description": "The session identifier of the contact"
           },
           "name": {
-            "type": "string",
+            "type": [
-            "description": "Name of the contact"
+              "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"
           }
         }
       },
+      "public_contact_record": {
+        "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"
+            }
+          }
+        }
+      },
       "public_conversation": {
         "type": "object",
         "properties": {
@@ -10770,20 +10914,41 @@
             "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",
+            "$ref": "#/components/schemas/public_contact_record"
-            "description": "The contact information associated to the conversation"
           }
         }
       },
@@ -10791,43 +10956,245 @@
         "type": "object",
         "properties": {
           "id": {
-            "type": "string",
+            "type": "integer",
             "description": "Id of the message"
           },
           "content": {
-            "type": "string",
+            "type": [
-            "description": "Text content of the message"
+              "string",
+              "null"
+            ],
+            "description": "Text content of the message. Can be null for attachment-only messages."
           },
           "message_type": {
-            "type": "string",
+            "type": "integer",
-            "description": "Denotes the message type"
+            "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",
+            "type": "integer",
-            "description": "Created at time stamp of the message"
+            "description": "Created at Unix timestamp of the message"
           },
           "conversation_id": {
-            "type": "string",
+            "type": "integer",
-            "description": "Conversation Id of the message"
+            "description": "Display Id of the conversation the message belongs to"
           },
           "attachments": {
             "type": "array",
+            "description": "Attachments if any",
             "items": {
-              "type": "object"
+              "$ref": "#/components/schemas/public_message_attachment"
-            },
+            }
-            "description": "Attachments if any"
           },
           "sender": {
+            "$ref": "#/components/schemas/public_message_sender"
+          }
+        }
+      },
+      "public_message_attachment": {
+        "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": "Details of the sender"
+            "description": "Metadata for contact attachments"
+          },
+          "transcribed_text": {
+            "type": "string",
+            "description": "Transcribed text for audio attachments"
+          }
+        }
+      },
+      "public_message_sender": {
+        "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"
           }
         }
       },

swagger/tag_groups/application_swagger.json

@@ -9257,19 +9257,163 @@
             "description": "The session identifier of the contact"
           },
           "name": {
-            "type": "string",
+            "type": [
-            "description": "Name of the contact"
+              "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"
           }
         }
       },
+      "public_contact_record": {
+        "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"
+            }
+          }
+        }
+      },
       "public_conversation": {
         "type": "object",
         "properties": {
@@ -9277,20 +9421,41 @@
             "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",
+            "$ref": "#/components/schemas/public_contact_record"
-            "description": "The contact information associated to the conversation"
           }
         }
       },
@@ -9298,43 +9463,245 @@
         "type": "object",
         "properties": {
           "id": {
-            "type": "string",
+            "type": "integer",
             "description": "Id of the message"
           },
           "content": {
-            "type": "string",
+            "type": [
-            "description": "Text content of the message"
+              "string",
+              "null"
+            ],
+            "description": "Text content of the message. Can be null for attachment-only messages."
           },
           "message_type": {
-            "type": "string",
+            "type": "integer",
-            "description": "Denotes the message type"
+            "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",
+            "type": "integer",
-            "description": "Created at time stamp of the message"
+            "description": "Created at Unix timestamp of the message"
           },
           "conversation_id": {
-            "type": "string",
+            "type": "integer",
-            "description": "Conversation Id of the message"
+            "description": "Display Id of the conversation the message belongs to"
           },
           "attachments": {
             "type": "array",
+            "description": "Attachments if any",
             "items": {
-              "type": "object"
+              "$ref": "#/components/schemas/public_message_attachment"
-            },
+            }
-            "description": "Attachments if any"
           },
           "sender": {
+            "$ref": "#/components/schemas/public_message_sender"
+          }
+        }
+      },
+      "public_message_attachment": {
+        "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": "Details of the sender"
+            "description": "Metadata for contact attachments"
+          },
+          "transcribed_text": {
+            "type": "string",
+            "description": "Transcribed text for audio attachments"
+          }
+        }
+      },
+      "public_message_sender": {
+        "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"
           }
         }
       },

swagger/tag_groups/client_swagger.json

@@ -141,7 +141,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/public_contact"
+                  "$ref": "#/components/schemas/public_contact_record"
                 }
               }
             }
@@ -2522,19 +2522,163 @@
             "description": "The session identifier of the contact"
           },
           "name": {
-            "type": "string",
+            "type": [
-            "description": "Name of the contact"
+              "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"
           }
         }
       },
+      "public_contact_record": {
+        "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"
+            }
+          }
+        }
+      },
       "public_conversation": {
         "type": "object",
         "properties": {
@@ -2542,20 +2686,41 @@
             "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",
+            "$ref": "#/components/schemas/public_contact_record"
-            "description": "The contact information associated to the conversation"
           }
         }
       },
@@ -2563,43 +2728,245 @@
         "type": "object",
         "properties": {
           "id": {
-            "type": "string",
+            "type": "integer",
             "description": "Id of the message"
           },
           "content": {
-            "type": "string",
+            "type": [
-            "description": "Text content of the message"
+              "string",
+              "null"
+            ],
+            "description": "Text content of the message. Can be null for attachment-only messages."
           },
           "message_type": {
-            "type": "string",
+            "type": "integer",
-            "description": "Denotes the message type"
+            "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",
+            "type": "integer",
-            "description": "Created at time stamp of the message"
+            "description": "Created at Unix timestamp of the message"
           },
           "conversation_id": {
-            "type": "string",
+            "type": "integer",
-            "description": "Conversation Id of the message"
+            "description": "Display Id of the conversation the message belongs to"
           },
           "attachments": {
             "type": "array",
+            "description": "Attachments if any",
             "items": {
-              "type": "object"
+              "$ref": "#/components/schemas/public_message_attachment"
-            },
+            }
-            "description": "Attachments if any"
           },
           "sender": {
+            "$ref": "#/components/schemas/public_message_sender"
+          }
+        }
+      },
+      "public_message_attachment": {
+        "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": "Details of the sender"
+            "description": "Metadata for contact attachments"
+          },
+          "transcribed_text": {
+            "type": "string",
+            "description": "Transcribed text for audio attachments"
+          }
+        }
+      },
+      "public_message_sender": {
+        "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"
           }
         }
       },

swagger/tag_groups/other_swagger.json

@@ -1937,19 +1937,163 @@
             "description": "The session identifier of the contact"
           },
           "name": {
-            "type": "string",
+            "type": [
-            "description": "Name of the contact"
+              "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"
           }
         }
       },
+      "public_contact_record": {
+        "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"
+            }
+          }
+        }
+      },
       "public_conversation": {
         "type": "object",
         "properties": {
@@ -1957,20 +2101,41 @@
             "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",
+            "$ref": "#/components/schemas/public_contact_record"
-            "description": "The contact information associated to the conversation"
           }
         }
       },
@@ -1978,43 +2143,245 @@
         "type": "object",
         "properties": {
           "id": {
-            "type": "string",
+            "type": "integer",
             "description": "Id of the message"
           },
           "content": {
-            "type": "string",
+            "type": [
-            "description": "Text content of the message"
+              "string",
+              "null"
+            ],
+            "description": "Text content of the message. Can be null for attachment-only messages."
           },
           "message_type": {
-            "type": "string",
+            "type": "integer",
-            "description": "Denotes the message type"
+            "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",
+            "type": "integer",
-            "description": "Created at time stamp of the message"
+            "description": "Created at Unix timestamp of the message"
           },
           "conversation_id": {
-            "type": "string",
+            "type": "integer",
-            "description": "Conversation Id of the message"
+            "description": "Display Id of the conversation the message belongs to"
           },
           "attachments": {
             "type": "array",
+            "description": "Attachments if any",
             "items": {
-              "type": "object"
+              "$ref": "#/components/schemas/public_message_attachment"
-            },
+            }
-            "description": "Attachments if any"
           },
           "sender": {
+            "$ref": "#/components/schemas/public_message_sender"
+          }
+        }
+      },
+      "public_message_attachment": {
+        "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": "Details of the sender"
+            "description": "Metadata for contact attachments"
+          },
+          "transcribed_text": {
+            "type": "string",
+            "description": "Transcribed text for audio attachments"
+          }
+        }
+      },
+      "public_message_sender": {
+        "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"
           }
         }
       },

swagger/tag_groups/platform_swagger.json

@@ -2698,19 +2698,163 @@
             "description": "The session identifier of the contact"
           },
           "name": {
-            "type": "string",
+            "type": [
-            "description": "Name of the contact"
+              "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"
           }
         }
       },
+      "public_contact_record": {
+        "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"
+            }
+          }
+        }
+      },
       "public_conversation": {
         "type": "object",
         "properties": {
@@ -2718,20 +2862,41 @@
             "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",
+            "$ref": "#/components/schemas/public_contact_record"
-            "description": "The contact information associated to the conversation"
           }
         }
       },
@@ -2739,43 +2904,245 @@
         "type": "object",
         "properties": {
           "id": {
-            "type": "string",
+            "type": "integer",
             "description": "Id of the message"
           },
           "content": {
-            "type": "string",
+            "type": [
-            "description": "Text content of the message"
+              "string",
+              "null"
+            ],
+            "description": "Text content of the message. Can be null for attachment-only messages."
           },
           "message_type": {
-            "type": "string",
+            "type": "integer",
-            "description": "Denotes the message type"
+            "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",
+            "type": "integer",
-            "description": "Created at time stamp of the message"
+            "description": "Created at Unix timestamp of the message"
           },
           "conversation_id": {
-            "type": "string",
+            "type": "integer",
-            "description": "Conversation Id of the message"
+            "description": "Display Id of the conversation the message belongs to"
           },
           "attachments": {
             "type": "array",
+            "description": "Attachments if any",
             "items": {
-              "type": "object"
+              "$ref": "#/components/schemas/public_message_attachment"
-            },
+            }
-            "description": "Attachments if any"
           },
           "sender": {
+            "$ref": "#/components/schemas/public_message_sender"
+          }
+        }
+      },
+      "public_message_attachment": {
+        "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": "Details of the sender"
+            "description": "Metadata for contact attachments"
+          },
+          "transcribed_text": {
+            "type": "string",
+            "description": "Transcribed text for audio attachments"
+          }
+        }
+      },
+      "public_message_sender": {
+        "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"
           }
         }
       },