openapi: 3.0.4
info:
  title: Messaging API
  description: |-
    Welcome to the Voxtelesys Messaging REST API. If at any point you have questions or would like more information please reach out to support.
  version: v2
servers:
  - url: https://smsapi.voxtelesys.net/api/v2
paths:
  /sms/{id}:
    get:
      tags:
        - SMS
      security:
        - OAuth2: ['messagingapi:sms: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/Sms"
  /sms:
    get:
      tags:
        - SMS
      security:
        - OAuth2: ['messagingapi:sms: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
          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/ListSms"
    post:
      tags:
        - SMS
      security:
        - OAuth2: ['messagingapi:sms:manage']
      summary: Send a message
      description: Endpoint for sending a message.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Single"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/Single"
  /sms/batch:
    post:
      tags:
        - Batch
      security:
        - OAuth2: ['messagingapi:sms:manage']
      summary: Send a batch
      description: |
        Endpoint for sending a batch of messages.

        When creating an SMS/MMS batch, it can be convenient to customize part(s) of the message on a per recipient basis. Parameterization allows you to do just that!

        When defining the message body, just insert as many parameter keys as is required. A key is defined by entering _${key}_ in the message body, where "key" is the name of the parameter. For each specified parameter key, a recipient and parameter value must also be provided.

        For example, the message body "Your appointment is scheduled for ${time}." contains the parameter key "time". When sending the batch, this key would be replaced with the defined value.

        Parameter values are then provided per recipient, or default values are provided. When providing parameter values, there are three component:

        **definition:** Specifies the order in which parameter values will be provided in the default and {recipient} arrays.

        **default:** Specifies the default values. The default value is used if an associated recipient array is not provided. Array size must be the same as definition, where an integer of 0 represents NULL or not provided.

        **recipient:** Specifies the parameter values to use for the specified recipient. Again, array size must be the same as definition, where an integer of 0 represents NULL or not provided.

        To send media like pictures, videos, and documents you will need to provide the `media` parameter with one or more URL.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Batch"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/Batch"
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://authapi.voxtelesys.net/api/v1/oauth/token
          scopes:
            messagingapi:sms:manage: Ability to send SMS/MMS messages
            messagingapi:sms:view: Ability to view SMS/MMS messages
  schemas:
    Sms:
      type: object
      properties:
          id:
            type: string
            example: 6708f96b76b15fde200deaca
            readOnly: true
          account_id:
            type: integer
            example: 190000
            readOnly: true
          trunk_group_id:
            type: integer
            example: 70000
            readOnly: true
          time:
            type: string
            format: date-time
            example: "2018-03-10T10:30:00.000Z"
          direction:
            type: string
            enum: [inbound, outbound]
            example: outbound
            readOnly: true
          to:
            type: string
            description: recipient phone number
            example: "13003003001"
          from:
            type: string
            description: sender phone number
            example: "13003003000"
          status:
            type: string
            example: "received"
            readOnly: true
          tag:
            type: string
            description: custom string which is included in callback events
            example: "261f6924-6982-11ea-bc55-0242ac130003"
          bulk_tag:
            type: string
            description: custom string which is included in callback events
            example: "4de1d075-2a7e-404e-abac-3f80560db42f"
          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
          registered:
            type: boolean
            readOnly: true
            description: whether the message is 10DLC registered with the TCR
            example: true
          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"
    Single:
      type: object
      required:
        - to
        - from
        - body
      properties:
        to:
          type: string
          description: recipient phone number
          example: "+13003003001"
        from:
          type: string
          description: sender phone number
          example: "+13003003000"
        body:
          type: string
          example: Hello world, this is a test message!
          description: message body
        media:
          type: array
          items:
            type: string
            format: uri
          example: ["http://path.to.image"]
          description: list of URLs to include as media attachments
        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
        status_callback:
          type: object
          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`.
          required:
            - url
    Batch:
      type: object
      required:
        - to
        - from
        - body
      properties:
        to:
          type: array
          items:
            type: string
          example: ["+13003003001","+13003003002"]
          description: list of recipients
        from:
          type: string
          example: "+13003003000"
          description: sender phone number
        body:
          type: string
          example: Hello ${name}, this is a test message!
          description: message body template
        media:
          type: array
          items:
            type: string
            format: uri
          example: ["http://path.to.image"]
          description: list of URLs to include as media attachments
        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 identifier for the messages
        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 identifier for a batch of messages
        status_callback:
          type: object
          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`.
          required:
            - url
        parameters:
          type: object
          description: Within the parameters object, you may specify multiple phone number properties
          properties:
            definition:
              type: array
              items:
                type: string
              example: ["name", "address", "time"]
              description: order of params
            default:
              type: array
              items:
                type: string
              example: 	["Customer", 0, 0]
              description: default params
            "<recipient>":
              type: array
              items:
                type: string
              example: ["John", "1111 Westroads Street", "12:30 PM"]
              description: parameters for specified recipient. Property name is the phone number of the recipient
        expire_at:
          type: string
          format: date-time
          example: "2018-03-10T10:30:00.000Z"
          description: time to expire batch if not already sent. Must be in ISO8601 format
  responseSchemas:
    ListSms:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Sms"
        page_size:
          type: integer
          example: 50
        next_page:
          type: string
          example: "K0NFRUBbQV00YjkxYmRkMWU0ZjlhY2Q4ZDUiXQ=="
    Single:
      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: sender phone number
          example: "13003003000"
        body:
          type: string
          example: Hello world, this is a test message!
          description: message body
        media:
          type: array
          items:
            type: string
            format: uri
          example: ["http://path.to.image"]
          description: list of URLs to include as media attachments
        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
    Batch:
      type: object
      properties:
        id:
          type: string
          example: 6708f96b76b15fde200deaca
        to:
          type: array
          items:
            type: string
          example: ["13003003001","13003003002"]
          description: list of recipients
        from:
          type: string
          description: sender phone number
          example: "13003003000"
        body:
          type: string
          example: Hello ${name}, this is a test message!
          description: message body template
        parameters:
          type: object
          description: Within the parameters object, you may specify multiple phone number properties
          properties:
            definition:
              type: array
              items:
                type: string
              example: ["name", "address", "time"]
              description: order of params
            default:
              type: array
              items:
                type: string
              example: 	["Customer", 0, 0]
              description: default params
            "<recipient>":
              type: array
              items:
                type: string
              example: ["John", "1111 Westroads Street", "12:30 PM"]
              description: parameters for specified recipient. Property name is the phone number of the recipient
        media:
          type: array
          items:
            type: string
            format: uri
          example: ["http://path.to.image"]
          description: list of URLs to include as media attachments
        tag:
          type: string
          example: 	261f6924-6982-11ea-bc55-0242ac130003
          description: string which will be included in callback events (max 256 chars)
        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
