openapi: 3.0.4
info:
  title: RCS API
  description: |-
    Welcome to the Voxtelesys RCS REST API. If at any point you have questions or would like more information please reach out to support.
  version: v2
servers:
  - url: https://rcsapi.voxtelesys.net/api/v2
paths:
  /rcs/{id}:
    get:
      tags:
        - RCS
      security:
        - OAuth2: ['rcsapi:rcs:view']
      summary: Retrieve a message
      description: Endpoint for retrieving a message.
      parameters:
        - name: id
          in: path
          description: ID of message.
          example: 6708f96b76b15fde200deaca
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Rcs"
  /rcs:
    get:
      tags:
        - RCS
      security:
        - OAuth2: ['rcsapi:rcs:view']
      summary: List messages
      description: Endpoint for retrieving a list of messages. To fetch all available messages, the `next_page` parameter is available as a cursor to iterate over. The iteration process works by taking the `next_page` field in the response from the `GET /sms` route and then providing the `next_page` parameter in the subsequent request to `GET /sms`.
      parameters:
        - name: page_size
          in: query
          description: Number of messages to retrieve per page.
          example: 50
          default: 50
          schema:
            type: integer
        - name: next_page
          in: query
          description: Unique identifier to fetch the next page. Required for pagination.
          example: 7d10a422-bd7d-4034-83de-c70caac600ba
          schema:
            type: string
            default: null
        - name: start_date
          in: query
          description: Retrieve messages at or after this time. Dates must be in ISO 8601 format.
          example: 2018-03-01
          schema:
            type: string
            format: date
            default: yesterday's date
        - name: end_date
          in: query
          description: Retrieve messages at or before this time. Dates must be in ISO 8601 format.
          example: 2018-03-28
          schema:
            type: string
            format: date
            default: today's date
        - name: trunk_group_id
          in: query
          description: 	Filter messages by service trunk group.
          example: 70000
          schema:
            type: integer
            default: null
        - name: tag
          in: query
          description: tag to filter messages by
          example: 261f6924-6982-11ea-bc55-0242ac130003
          schema:
            type: string
            default: null
        - name: bulk_tag
          in: query
          description: bulk tag to filter messages by
          example: 4de1d075-2a7e-404e-abac-3f80560db42f
          schema:
            type: string
            default: null
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/ListRcs"
    post:
      tags:
        - RCS
      security:
        - OAuth2: ['rcsapi:message:manage']
      summary: Send an RCS message
      description: Endpoint for sending a message.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RcsMessage"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/RcsMessage"
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://authapi.voxtelesys.net/api/v1/oauth/token
          scopes:
            rcsapi:rcs:manage: Ability to send RCS messages
            rcsapi:rcs:view: Ability to view RCS messages
  schemas:
    Rcs:
      type: object
      properties:
          id:
            type: string
            example: 6708f96b76b15fde200deaca
            readOnly: true
          sent_at:
            type: string
            format: date-time
            example: "2018-03-10T10:30:00.000Z"
          account_id:
            type: integer
            example: 190000
            readOnly: true
          service_trunk_group_id:
            type: integer
            example: 70000
            readOnly: true
          to:
            type: string
            description: Recipient phone number.
            example: "+13003003001"
          from:
            type: string
            description: Registered sender.
            example: "Brand"
          direction:
            type: string
            enum: [inbound, outbound]
            example: outbound
            readOnly: true
          status:
            type: string
            enum: [queued, delivering, delivered, failed, unknown, expired, received]
            example: "received"
            readOnly: true
          service:
            type: string
            enum: [RBM]
            example: "RBM"
            readOnly: true
          class:
            type: string
            enum: [basic, single]
            example: "single"
            readOnly: true
          segments:
            type: integer
            description: Number of segments in the message.
            example: 1
            readOnly: true
          rate:
            type: number
            readOnly: true
            description: Billable rate per segment.
            format: float
            example: 0.010
          surcharge:
            type: number
            readOnly: true
            description: Billable surcharge per segment.
            format: float
            example: 0.001
          cost:
            type: number
            readOnly: true
            description: Total cost of the message.
            format: float
            example: 0.011
          message_type:
            type: string
            enum: ["TEXT"]
          tag:
            description: String which will be included in callback events (max 256 chars), typically used to store an external identifier for the message.
            example: 261f6924-6982-11ea-bc55-0242ac130003
            type: string
            default: null
          bulk_tag:
            description: String which will be included in callback events (max 256 chars), typically used to store an external identifier for a batch of messages.
            example: 4de1d075-2a7e-404e-abac-3f80560db42f
            type: string
            default: null
          error:
            type: object
            readOnly: true
            properties:
              code:
                type: integer
                description: The error code.
                example: 5312
              description:
                type: string
                description: The error description.
                example: "internal error"
    RcsMessage:
      type: object
      required:
        - to
        - from
        - content
      properties:
        to:
          type: string
          description: Recipient phone number.
          example: "+13003003001"
        from:
          type: string
          description: Registered sender.
          example: "Brand"
        expire_at:
          type: string
          format: date-time
          example: "2024-12-31T23:59:59Z"
          description: Expire message at this time if not already sent. Must be in ISO8601 format.
        content:
          type: object
          description: Message body.
          required:
            - body
          properties:
            body:
              type: string
              example: Hello world, this is a test message!
              description: Message body.
            suggestions:
              type: array
              description: A list of suggestions, each with a different structure based on type.
              maxLength: 11
              items:
                oneOf:
                  - $ref: '#/components/schemas/ReplySuggestion'
                  - $ref: '#/components/schemas/OpenUrlSuggestion'
                  - $ref: '#/components/schemas/DialPhoneSuggestion'
                  - $ref: '#/components/schemas/ShowLocationSuggestion'
                  - $ref: '#/components/schemas/RequestLocationSuggestion'
                  - $ref: '#/components/schemas/CreateCalendarEventSuggestion'
              discriminator:
                propertyName: type
                mapping:
                  REPLY: '#/components/schemas/ReplySuggestion'
                  OPEN_URL: '#/components/schemas/OpenUrlSuggestion'
                  DIAL_PHONE: '#/components/schemas/DialPhoneSuggestion'
                  SHOW_LOCATION: '#/components/schemas/ShowLocationSuggestion'
                  REQUEST_LOCATION: '#/components/schemas/RequestLocationSuggestion'
                  CREATE_CALENDAR_EVENT: '#/components/schemas/CreateCalendarEventSuggestion'
        tag:
          type: string
          example: 	261f6924-6982-11ea-bc55-0242ac130003
          description: String which will be included in callback events (max 256 chars), typically used to store an external identifier for the message.
        bulk_tag:
          type: string
          example: 	4de1d075-2a7e-404e-abac-3f80560db42f
          description: String which will be included in callback events (max 256 chars), typically used to store an external identifier for a batch of messages.
        failover:
          type: object
          required:
            - enabled
            - from
            - to
            - body
          description: Information for failover to SMS if RCS message cannot be delivered.
          properties:
            enabled:
              type: boolean
              example: true
              description: Whether failover is enabled.
            from:
              type: string
              description: Sender phone number to use for SMS failover.
              example: "+13003003000"
            to:
              type: string
              example: "+15555555555"
              description: Recipient phone number to use for SMS failover.
            body:
              type: string
              example: Hello, this is a fallback SMS message.
              description: message body to use for SMS failover
            media:
              type: array
              items:
                type: string
                format: uri
              example: ["http://path.to.image"]
              description: List of URLs to include as media attachments for SMS failover.
        status_callback:
          type: object
          required:
            - url
          description: Information for receiving HTTP callbacks when the status of the message changes.
          properties:
            url:
              type: string
              format: uri
              example: http://example.com
              description: The absolute URL to send callbacks to when the status of the message is updated.
            method:
              type: string
              enum: ["GET", "POST"]
              example: POST
              description: The HTTP method to use for status callbacks. Defaults to `POST`.
    ReplySuggestion:
      type: object
      required:
        - type
        - text
        - callback_data
      properties:
        type:
          type: string
          enum: ["REPLY"]
        text:
          type: string
          description: Text to display in the suggestion chip.
          example: "Reply"
          maxLength: 25
        callback_data:
          type: string
          description: Data sent back to the server when clicked.
          example: "REPLY"
          maxLength: 2048
    OpenUrlSuggestion:
      type: object
      required:
        - type
        - text
        - callback_data
        - url
      properties:
        type:
          type: string
          enum: ["OPEN_URL"]
        text:
          type: string
          description: Text to display in the suggestion chip.
          example: "Visit our Website"
          maxLength: 25
        callback_data:
          type: string
          description: Data sent back to the server when clicked.
          example: "OPEN_URL"
          maxLength: 2048
        url:
          type: string
          format: uri
          description: The URL to open.
          example: "https://example.com"
        application:
          type: string
          enum: ["BROWSER", "WEBVIEW"]
          default: "BROWSER"
          description: Determines how the URL will be opened on the phone. `BROWSER` will open the URL in a web browser. `WEBVIEW` will open a webview window within the phone's messaging app.
        view_mode:
          type: string
          enum: ["FULL", "HALF", "TALL"]
          description: Determines the view mode of a webview. This field is required when the application type is `WEBVIEW`. `FULL` makes the webview take up the full screen. `HALF` makes the webview take up half of the screen. `TALL` makes the screen take up three quarters of the screen.
    DialPhoneSuggestion:
      type: object
      required:
        - type
        - text
        - callback_data
        - phone_number
      properties:
        type:
          type: string
          enum: ["DIAL_PHONE"]
        text:
          type: string
          description: Text to display in the suggestion chip.
          example: "Contact Support"
          maxLength: 25
        callback_data:
          type: string
          description: Data sent back to the server when clicked.
          example: "DIAL_PHONE"
          maxLength: 2048
        phone_number:
          type: string
          description: The E164-formatted phone number to dial.
          example: "15555555555"
    ShowLocationSuggestion:
      type: object
      required:
        - type
        - text
        - callback_data
        - location
      properties:
        type:
          type: string
          enum: ["SHOW_LOCATION"]
        text:
          type: string
          description: Text to display in the suggestion chip.
          example: "Visit our office"
          maxLength: 25
        callback_data:
          type: string
          description: Data sent back to the server when clicked.
          example: "SHOW_LOCATION"
          maxLength: 2048
        location:
          type: object
          description: Location information to show.
          required:
            - latitude
            - longitude
          properties:
            latitude:
              type: number
              format: double
              maximum: 90
              minimum: -90
            longitude:
              type: number
              format: double
              maximum: 180
              minimum: -180
        label:
          type: string
          description: Label of the location.
          minLength: 1
          maxLength: 100
    RequestLocationSuggestion:
      type: object
      required:
        - type
        - text
        - callback_data
      properties:
        type:
          type: string
          enum: ["REQUEST_LOCATION"]
        text:
          type: string
          description: Text to display in the suggestion chip.
          example: "Share location"
          maxLength: 25
        callback_data:
          type: string
          description: Data sent back to the server when clicked.
          example: "REQUEST_LOCATION"
          maxLength: 2048
    CreateCalendarEventSuggestion:
      type: object
      required:
        - type
        - text
        - callback_data
        - start_time
        - end_time
        - title
      properties:
        type:
          type: string
          enum: ["CREATE_CALENDAR_EVENT"]
        text:
          type: string
          description: Text to display in the suggestion chip.
          example: "Create event"
          maxLength: 25
        callback_data:
          type: string
          description: Data sent back to the server when clicked.
          example: "CREATE_CALENDAR_EVENT"
          maxLength: 2048
        start_time:
          type: string
          description: Start time of the event in ISO 8601 format.
          example: "2025-01-01T01:00:00Z"
        end_time:
          type: string
          description: End time of the event in ISO 8601 format.
          example: "2025-01-01T02:00:00Z"
        title:
          type: string
          description: Title of the event.
          example: "Planning Meeting"
          maxLength: 100
          minLength: 1
        description:
          type: string
          description: Description of the event.
          maxLength: 500
          minLength: 1
          example: "Weekly meeting to discuss plan"


  responseSchemas:
    ListRcs:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Rcs"
        page_size:
          type: integer
          example: 50
        next_page:
          type: string
          example: "K0NFRUBbQV00YjkxYmRkMWU0ZjlhY2Q4ZDUiXQ=="
    RcsMessage:
      type: object
      properties:
        id:
          type: string
          example: 6708f96b76b15fde200deaca
        direction:
          type: string
          example: outbound
        to:
          type: string
          description: Recipient phone number.
          example: "+13003003001"
        from:
          type: string
          description: Registered sender.
          example: "Brand"
        tag:
          type: string
          example: 	261f6924-6982-11ea-bc55-0242ac130003
          description: String which will be included in callback events (max 256 chars).
        bulk_tag:
          type: string
          example: 	261f6924-6982-11ea-bc55-0242ac130003
          description: String which will be included in callback events (max 256 chars).
        status:
          type: string
          example: "queued"
        expire_at:
          type: string
          format: date-time
          example: "2018-03-10T10:30:00.000Z"
          description: Expire message at this time if not already sent. Must be in ISO8601 format.
