openapi: 3.2.0
info:
  title: MTN Messaging USSD Accessible to USSD Gateway API
  version: 1.0.0
  description: Provides a RESTful API to expose USSD capability.
servers:
- url: https://api.mtn.com/v1/
tags:
- name: Accessible to USSD Gateway
  description: Used by USSDGW - using ApiKeyAuth, to send MO generated messages to 3PP through MADAPI.
  externalDocs:
    url: https://#
paths:
  /messages/ussd/inbound:
    post:
      description: This function sends USSD MO-generated message to a 3PP with subscription on MADAPI.
      summary: The USSDGW sends USSD MO-generated message to 3PP through MADAPI
      tags:
      - Accessible to USSD Gateway
      operationId: inbound
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid access token. Please try with a valid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Authorization credentials passed and accepted but account does forbidden to send USSD

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: API does not support the requested content type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: 'The HTTP method being used has not yet been implemented for

            the requested resource

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The service requested is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundRequest'
        description: request body
        required: true
components:
  schemas:
    InboundResponse:
      type: object
      required:
      - statusCode
      - statusMessage
      - transactionId
      - data
      - _link
      properties:
        statusCode:
          type: string
          example: '0000'
        statusMessage:
          type: string
          example: ''
        transactionId:
          type: string
          example: ''
        data:
          type: object
          required:
          - outboundResponse
          properties:
            inboundResponse:
              type: string
              description: Response value.
              example: null
            userInputRequired:
              type: boolean
              description: Is user input required.
              example: true
            messageType:
              type: integer
              description: The messageType to send
              example: 1
            serviceCode:
              type: string
              description: 'The service code or short code of the service. '
              example: '9000'
            msisdn:
              type: string
              description: The msisdn to send the response to.
        _link:
          $ref: '#/components/schemas/Links'
    Links:
      type: object
      required:
      - self
      properties:
        self:
          type: object
          required:
          - href
          description: ''
          properties:
            href:
              type: string
              description: ''
              example: https://api.mtn.com/v1/messages/ussd/send
    Error:
      type: object
      required:
      - statusCode
      - statusMessage
      - transactionId
      properties:
        statusCode:
          type: string
          description: This is the MADAPI Canonical Response 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 Response Codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
          example: '3001'
        statusMessage:
          type: string
          description: More details on the returned status code which can be shown to a client
          example: A system error has occured
        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)
          example: 400 Bad Request
        transactionId:
          type: string
          description: MADAPI generated Id to include for tracing requests
          example: xyz-t960-tuy
        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/<path>
        method:
          type: string
          description: The HTTP method type that was used
          example: POST
    InboundRequest:
      type: object
      required:
      - sessionId
      - messageType
      - msisdn
      - serviceCode
      - ussdString
      properties:
        sessionId:
          type: string
          description: Unique identifier of the session.
          example: '01235'
        messageType:
          type: string
          description: Message type. 0-Begin|1-Continue|2-End|3-Notification|4-Cancel|5-Timeout.
          example: '0'
        msisdn:
          type: string
          description: Mobile number of the message recipient.
          example: '2252312345'
        serviceCode:
          type: string
          example: '321123'
        ussdString:
          type: string
          description: USSD message content. If messageType is of type 4-Abort, this attribute will contain the abort reason or message.
          example: Please vote for xxx.
        cellId:
          type: string
          description: Cell Id of the subscriber. A GSM Cell ID (CID) is a unique number used to identify each base transceiver station (BTS) or sector of a BTS within a location area code (LAC) if not within a GSM network.
        language:
          type: string
          description: Language of preference of the subscriber
        imsi:
          type: string
          description: IMSI of the subscriber. An international mobile subscriber identity (IMSI) is a unique number, usually fifteen digits, associated with Global System for Mobile Communications (GSM) and Universal Mobile Telecommunications System (UMTS) network mobile phone users. The IMSI is a unique number identifying a GSM subscriber.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key