swagger: "2.0"
info:
  version: "1.0"
  title: "Medallia SMS Experience API"
  description: "Provides a RESTful API to expose SMS capability."
host: api.mtn.com
basePath: /v2m/
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: "https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials"
    scopes:
      SEND-SMS: Grants ability to send SMS messages to subscribers.
security:
  - OAuth2: []
paths:
  /messages/sms/outbound:
    post:
      tags:
          - "Sending SMS"
      summary: "This operation is used to create outgoing SMS request"
      description: "This interface is used to send an SMS to the specified address(s)."
      parameters:
      - in: "body"
        name: "body"
        description: "Request body"
        required: true
        schema:
          $ref: "#/definitions/outboundSMSMessageRequest"
      responses:
        201:
          description: "Outbound SMS created"
          schema:
            $ref: "#/definitions/resourceReference"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error"
          description: "Internal Server Error"
  
          
  
definitions:
  
  outboundSMSMessageRequest:
    type: object
    required: 
      - message
      - receiverAddress
    properties:
      recipient:
        description: "This is subscriber MSISDN that the SMS is being sent to. The value is represented as International  ITU-T E.164. If more than one address is used the values will be comma separated. Current supported length is one. This means a client may not send an SMS to more than one receiver at a time."
        type: object
        properties:
          id: 
            type: string
            example: "27123456789"
      message:
        type: object
        properties:
          text:
            type: string
            description: "The message being sent. The standard limit of the size of the message is 160 characters."
            maxLength: 160
      notification_type:
        type: string
      
  resourceReference:
    type: object
    properties:
      recipient_id:
        type: string
        description: "Recepient number/id sent in request"
        example: "sub123456"
      message_id:
        type: string
        description: "Unique identification id generated by MADapi which will be used by Medallia to correlate the delivery notification"
        example: "sub123456"


  Error:
    type: object
    required:
      - "statusCode"
      - "statusMessage"
      - "transactionId"
    properties:
      statusCode:
        type: string
        description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
        example: '1000'
      statusMessage:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client
      supportMessage:
        type: string
        description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
      transactionId:
        type: string
        description: MADAPI generated Id to include for tracing requests
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2020-08-01T12:34'
      path:
        type: string
        description: The path that caused the error
        example: 'https://api.mtn.com/v1/'
      method:
        type: string
        description: The HTTP method type that was used
        example: 'POST'