add public documentation for WA outbound metrics api (#259)

* add public documentation for WA outbound metrics api

* fix documentation

* update doc

Author: akashbdj

descriptions/0/api.intercom.io.yaml

@@ -8960,6 +8960,134 @@ paths:
                     id: 6762f23b1bb69f9f2193bc1d
                   message_type: sms
                   body: heyy https://picsum.photos/200/300
+  "/messages/status":
+    get:
+      summary: Get statuses of all messages sent based on the specified ruleset_id
+      parameters:
+      - name: Intercom-Version
+        in: header
+        schema:
+          "$ref": "#/components/schemas/intercom_version"
+      - name: ruleset_id
+        in: query
+        required: true
+        description: The unique identifier for the set of messages to check status for
+        schema:
+          type: string
+      - name: per_page
+        in: query
+        required: false
+        description: Number of results per page (default 50, max 100)
+        schema:
+          type: integer
+          default: 50
+          maximum: 100
+      - name: starting_after
+        in: query
+        required: false
+        description: Cursor for pagination, used to fetch the next page of results
+        schema:
+          type: string
+      tags:
+      - Messages
+      - WhatsApp
+      operationId: getWhatsAppMessageStatus
+      description: |
+        Retrieves statuses of messages sent from the Outbound module. Currently, this API only supports WhatsApp messages.
+        
+        
+        This endpoint returns paginated status events for WhatsApp messages sent via the Outbound module, providing
+        information about delivery state and related message details.
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              examples:
+                Successful response:
+                  value:
+                    type: list
+                    ruleset_id: 12345
+                    pages:
+                      type: pages
+                      per_page: 50
+                      total_pages: 3
+                      next:
+                        starting_after: "abc123"
+                    total_count: 125
+                    events:
+                      - id: "event_1"
+                        conversation_id: "conv_123"
+                        user_id: "user_123"
+                        status: "delivered"
+                        type: "broadcast_outbound"
+                        created_at: 1734537980
+                        updated_at: 1734538000
+                        whatsapp_message_id: "wamid_123"
+                        template_name: "appointment_reminder"
+                      - id: "event_2"
+                        conversation_id: "conv_456"
+                        user_id: "user_456"
+                        status: "sent"
+                        type: "broadcast_outbound"
+                        created_at: 1734537970
+                        updated_at: 1734538010
+                        whatsapp_message_id: "wamid_456"
+                        template_name: "order_update"
+              schema:
+                "$ref": "#/components/schemas/whatsapp_message_status_list"
+        '400':
+          description: Bad request - missing required parameters
+          content:
+            application/json:
+              examples:
+                missing ruleset_id:
+                  value:
+                    type: error
+                    request_id: "req_123"
+                    message: "ruleset_id is required"
+              schema:
+                "$ref": "#/components/schemas/error"
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              examples:
+                Unauthorized:
+                  value:
+                    type: error.list
+                    request_id: d7997515-cd92-4fe4-966c-cb1f4bdda1d4
+                    errors:
+                    - code: unauthorized
+                      message: Access Token Invalid
+              schema:
+                "$ref": "#/components/schemas/error"
+        '403':
+          description: API plan restricted
+          content:
+            application/json:
+              examples:
+                API plan restricted:
+                  value:
+                    type: error.list
+                    request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b0
+                    errors:
+                    - code: api_plan_restricted
+                      message: Active subscription needed.
+              schema:
+                "$ref": "#/components/schemas/error"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              examples:
+                server error:
+                  value:
+                    type: error
+                    request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b2
+                    message: "Request failed due to an internal error. Please reach out to support"
+              schema:
+                "$ref": "#/components/schemas/error"
   "/news/news_items":
     get:
       summary: List all news items
@@ -18025,6 +18153,87 @@ components:
       - created_at
       - body
       - message_type
+    whatsapp_message_status_list:
+      type: object
+      required:
+        - type
+        - ruleset_id
+        - pages
+        - total_count
+        - events
+      properties:
+        type:
+          type: string
+          enum: ["list"]
+        ruleset_id:
+          type: string
+          description: The provided ruleset ID
+        pages:
+          type: object
+          required:
+            - type
+            - per_page
+            - total_pages
+          properties:
+            type:
+              type: string
+              enum: ["pages"]
+            per_page:
+              type: integer
+              description: Number of results per page
+            total_pages:
+              type: integer
+              description: Total number of pages
+            next:
+              type: object
+              nullable: true
+              description: Information for fetching next page (null if no more pages)
+              properties:
+                starting_after:
+                  type: string
+                  description: Cursor for the next page
+        total_count:
+          type: integer
+          description: Total number of events
+        events:
+          type: array
+          items:
+            type: object
+            required:
+              - id
+              - conversation_id
+              - status
+              - type
+              - created_at
+              - updated_at
+              - whatsapp_message_id
+            properties:
+              id:
+                type: string
+                description: Event ID
+              conversation_id:
+                type: string
+                description: ID of the conversation
+              status:
+                type: string
+                description: Current status of the message
+                enum: ["sent", "delivered", "read", "failed"]
+              type:
+                type: string
+                description: Event type
+                enum: ["broadcast_outbound"]
+              created_at:
+                type: integer
+                description: Creation timestamp
+              updated_at:
+                type: integer
+                description: Last update timestamp
+              whatsapp_message_id:
+                type: string
+                description: WhatsApp's message identifier
+              template_name:
+                type: string
+                description: Name of the WhatsApp template used
     multiple_filter_search_request:
       title: Multiple Filter Search Request
       description: Search using Intercoms Search APIs with more than one filter.