> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List SMS messages

> List all SMS messages in the organization



## OpenAPI

````yaml /openapi.json get /v1/organization/sms/messages
openapi: 3.1.0
info:
  version: 1.0.0
  title: Chirp API
  description: Communication APIs for SMS, MMS, and WhatsApp messaging
servers:
  - url: https://api.buildwithchirp.com
security: []
paths:
  /v1/organization/sms/messages:
    get:
      tags:
        - Admin
        - SMS
      parameters:
        - schema:
            type: string
            example: '20'
            description: 'Maximum number of items to return (default: 20)'
          required: false
          description: 'Maximum number of items to return (default: 20)'
          name: limit
          in: query
        - schema:
            type: string
            minLength: 27
            example: msg_sms_2DbBs7GWhGvVNJGrDXr5RG0mBWI
            description: KSUID-based cursor for pagination
          required: false
          description: KSUID-based cursor for pagination
          name: cursor
          in: query
        - schema:
            type: string
            example: '40'
            description: Offset for pagination (fallback when cursor is not available)
          required: false
          description: Offset for pagination (fallback when cursor is not available)
          name: offset
          in: query
        - schema:
            type: string
            enum:
              - INBOUND
              - OUTBOUND
          required: false
          name: direction
          in: query
        - schema:
            type: string
            pattern: ^app_(?:test_)?[a-zA-Z0-9]{27}$
            example: app_2DbBs7GWhGvVNJGrDXr5RG0mBWI
            description: 'Unique identifier for a App. Format: app_[test_]{ksuid}'
          required: false
          description: 'Unique identifier for a App. Format: app_[test_]{ksuid}'
          name: appId
          in: query
      responses:
        '200':
          description: List all SMS messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMessagesResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - adminAuth: []
components:
  schemas:
    ListMessagesResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        nextCursor:
          $ref: '#/components/schemas/Cursor'
        totalCount:
          type: integer
          example: 100
          description: Total number of items matching the query
      required:
        - messages
        - nextCursor
        - totalCount
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - provider_error
                - api_error
              description: The type of error returned
              example: invalid_request_error
            code:
              type: string
              enum:
                - message_undeliverable
                - conversation_window_expired
                - recipient_not_on_whatsapp
                - phone_number_not_assigned
                - unsupported_message_type
                - media_too_large
                - invalid_phone_number
                - template_not_found
                - template_parameter_mismatch
                - groups_not_eligible
                - account_restricted
                - display_name_not_approved
                - whatsapp_not_configured
                - meta_api_error
                - meta_api_unavailable
                - telnyx_api_error
                - telnyx_api_unavailable
                - rate_limit_exceeded
                - whatsapp_rate_limited
                - resource_already_exists
                - test_app_required
                - call_not_found
                - call_already_ended
                - call_failed
                - call_rejected
                - call_timeout
                - call_busy
                - calling_not_configured
                - calling_disabled
                - max_concurrent_calls_reached
                - recording_not_found
                - recording_already_in_progress
                - recording_failed
                - voicemail_not_found
                - voicemail_disabled
                - invalid_call_command
                - command_not_applicable
                - whatsapp_calling_not_enabled
                - whatsapp_call_permission_required
                - whatsapp_call_permission_limit
                - whatsapp_pstn_bridge_forbidden
                - livekit_api_error
                - livekit_room_error
                - sip_trunk_error
              description: A machine-readable error code for programmatic handling
              example: invalid_phone_number
            message:
              type: string
              description: Human-readable error message
              example: The phone number "+1abc" is not in E.164 format.
            doc_url:
              type: string
              format: uri
              description: URL to documentation for this error code
              example: >-
                https://docs.buildwithchirp.com/api_reference/error-codes#invalid_phone_number
            param:
              type: string
              description: The parameter that caused the error
              example: from
            provider:
              $ref: '#/components/schemas/ProviderError'
            additional_info:
              type: array
              items:
                type: string
              description: Human-readable remediation hints (e.g. from Meta Health Status).
          required:
            - type
            - message
      required:
        - error
    Message:
      type: object
      properties:
        id:
          type: string
          pattern: ^msg_sms_(?:test_)?[a-zA-Z0-9]{27}$
          example: msg_sms_2DbBs7GWhGvVNJGrDXr5RG0mBWI
          description: 'Unique identifier for a Message. Format: msg_sms_[test_]{ksuid}'
        systemPhoneNumberId:
          type: string
          pattern: ^ph_(?:test_)?[a-zA-Z0-9]{27}$
          example: ph_2DbBs7GWhGvVNJGrDXr5RG0mBWI
          description: 'Unique identifier for a Phone Number. Format: ph_[test_]{ksuid}'
        systemPhoneNumber:
          type: string
        fromPhoneNumber:
          type: string
        text:
          type:
            - string
            - 'null'
        subject:
          type:
            - string
            - 'null'
        type:
          type: string
          enum:
            - SMS
            - MMS
        transport:
          type: string
          enum:
            - sms
            - mms
        direction:
          type: string
          enum:
            - INBOUND
            - OUTBOUND
        receivedAt:
          type:
            - string
            - 'null'
          format: date-time
        sentAt:
          type:
            - string
            - 'null'
          format: date-time
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/MessageRecipient'
      required:
        - id
        - systemPhoneNumberId
        - systemPhoneNumber
        - fromPhoneNumber
        - text
        - subject
        - type
        - transport
        - direction
        - receivedAt
        - sentAt
        - completedAt
        - createdAt
        - updatedAt
        - recipients
    Cursor:
      type:
        - string
        - 'null'
      minLength: 27
      example: msg_sms_2DbBs7GWhGvVNJGrDXr5RG0mBWI
      description: Cursor for the next page, or null if no more results
    ProviderError:
      type: object
      properties:
        source:
          type: string
          enum:
            - meta
            - telnyx
            - livekit
          description: Provider name
          example: meta
        code:
          anyOf:
            - type: number
            - type: string
          description: Provider's native error code
        message:
          type: string
          description: Provider's error message
        fbtrace_id:
          type: string
          description: Meta's trace ID for support tickets
        health_status:
          $ref: '#/components/schemas/HealthStatusPayload'
      required:
        - source
        - code
        - message
    MessageRecipient:
      type: object
      properties:
        id:
          type: string
          pattern: ^rcpt_(?:test_)?[a-zA-Z0-9]{27}$
          example: rcpt_2DbBs7GWhGvVNJGrDXr5RG0mBWI
          description: 'Unique identifier for a Recipient. Format: rcpt_[test_]{ksuid}'
        phoneNumber:
          type: string
        status:
          type: string
          enum:
            - QUEUED
            - SENDING
            - SENT
            - DELIVERED
            - FAILED
        carrier:
          type:
            - string
            - 'null'
        lineType:
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - phoneNumber
        - status
        - carrier
        - lineType
        - createdAt
        - updatedAt
    HealthStatusPayload:
      type: object
      properties:
        can_send_message:
          type: string
          enum:
            - AVAILABLE
            - LIMITED
            - BLOCKED
          description: Meta Health Status value
        entities:
          type: array
          items:
            $ref: '#/components/schemas/HealthStatusEntity'
      required:
        - can_send_message
        - entities
      description: >-
        Meta Health Status payload, present when the error was enriched via the
        Health Status API.
    HealthStatusEntity:
      oneOf:
        - type: object
          properties:
            entity_type:
              type: string
              enum:
                - PHONE_NUMBER
                - MESSAGE_TEMPLATE
                - WABA
                - BUSINESS
                - APP
            id:
              type: string
            can_send_message:
              type: string
              enum:
                - AVAILABLE
            can_receive_call_sip:
              type: string
              enum:
                - AVAILABLE
                - LIMITED
                - BLOCKED
              description: Meta Health Status value
            errors:
              type: array
              items:
                $ref: '#/components/schemas/HealthStatusError'
          required:
            - entity_type
            - id
            - can_send_message
        - type: object
          properties:
            entity_type:
              type: string
              enum:
                - PHONE_NUMBER
                - MESSAGE_TEMPLATE
                - WABA
                - BUSINESS
                - APP
            id:
              type: string
            can_send_message:
              type: string
              enum:
                - LIMITED
            can_receive_call_sip:
              type: string
              enum:
                - AVAILABLE
                - LIMITED
                - BLOCKED
              description: Meta Health Status value
            additional_info:
              type: array
              items:
                type: string
            errors:
              type: array
              items:
                $ref: '#/components/schemas/HealthStatusError'
          required:
            - entity_type
            - id
            - can_send_message
            - additional_info
        - type: object
          properties:
            entity_type:
              type: string
              enum:
                - PHONE_NUMBER
                - MESSAGE_TEMPLATE
                - WABA
                - BUSINESS
                - APP
            id:
              type: string
            can_send_message:
              type: string
              enum:
                - BLOCKED
            can_receive_call_sip:
              type: string
              enum:
                - AVAILABLE
                - LIMITED
                - BLOCKED
              description: Meta Health Status value
            errors:
              type: array
              items:
                $ref: '#/components/schemas/HealthStatusError'
          required:
            - entity_type
            - id
            - can_send_message
            - errors
    HealthStatusError:
      type: object
      properties:
        error_code:
          type: number
        error_description:
          type: string
        possible_solution:
          type: string
      required:
        - error_code
        - error_description
        - possible_solution
  securitySchemes:
    adminAuth:
      type: http
      scheme: bearer
      description: 'Admin API key (format: sk_admin_*) for organization-level operations'

````