Documentation
Documentation
https://developers.mtn.com/products/mtn-sms-interface
APIReference
https://developers.mtn.com/products/mtn-sms-interface
OpenAPI Specification
swagger: "2.0"
info:
version: "1.0"
title: "Short Message Service (SMS) API"
description: "Provides a RESTful API to expose SMS capability."
host: api.mtn.com
basePath: /v2/
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:
200:
description: "Outbound SMS created. This applies only to the countries that have partially migrated to SMS v3.
Applicable country list: **Nigeria , Zambia , Cote d'Ivore , Eswatini , Cameroon**"
schema:
$ref: "#/definitions/resourceReferencev3"
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"
/messages/sms/outbound/{senderAddress}/{requestId}/deliveryStatus:
get:
tags:
- "Sending SMS"
summary: "Query delivery status of outgoing SMS"
description: "This interface is used to query the delivery status of an SMS or list of SMSes that were sent in one resquest."
parameters:
- in: "path"
name: senderAddress
type: string
required: true
description: "It is the address to which a responding SMS is sent."
x-example: "10111"
- in: "path"
name: requestId
type: string
required: true
description: "This is the requestId returned after when sending an SMS."
x-example: "10c0d78cd4bf77ee@138a3d02644"
responses:
200:
description: "Query sucessful"
schema:
$ref: "#/definitions/deliveryStatusResponse"
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"
/messages/sms/outbound/{senderAddress}/subscription:
post:
tags:
- "Sending SMS"
summary: "Create subscription to receive SMS delivery notifications."
description: "This interface will start the server to send notifications to third party apps when SMS delivery notifications are received."
parameters:
- in: "path"
name: senderAddress
type: string
required: true
description: "It is the address to which a responding SMS is sent."
x-example: "278945464"
- in: "body"
name: "body"
description: "Request body"
required: true
schema:
$ref: "#/definitions/deliveryReceiptSubscription"
responses:
201:
description: "Outbound SMS created"
schema:
$ref: "#/definitions/subscriptionResponse"
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"
/messages/sms/outbound/{senderAddress}/subscription/{subscriptionId}:
delete:
tags:
- "Sending SMS"
summary: "Delete subscription to receive SMS delivery notifications."
description: "This interface will stop the server from sending SMS delivery notifications to third party apps when SMS messages are received by subscribers"
parameters:
- in: "path"
name: senderAddress
type: string
required: true
description: "It is the address to which a responding SMS is sent."
x-example: "278945464"
- in: "path"
name: subscriptionId
type: string
required: true
description: "It is the address to which a responding SMS is sent."
x-example: "2783123455@138e1821414"
responses:
200:
description: "SMS notification stopped"
schema:
$ref: "#/definitions/outboundSubscriptionDeleteResponse"
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"
/messages/sms/inbound/registrations/{requestId}/messages:
get:
tags:
- "Receiving SMS"
summary: "Query for received SMS messages."
description: "This interface is used to query for received SMS messages on the given requestId"
parameters:
- in: "path"
name: requestId
type: string
required: true
description: "It is typically a short-code or virtual MSISDN that is agreed with the mobile operator for receipt of SMS messages"
x-example: "10111"
- in: "query"
name: maxBatchSize
type: string
description: "It is the maximum number of messages to be retrieved in the request. The actual maximum batch size is also limited by SLA MaxReturnedSMS. System chooses the smaller value from the value of maxBatchSize and MaxReturnedSMS."
x-example: "10"
responses:
200:
description: "Query sucessful"
schema:
$ref: "#/definitions/inboundSMSMessageResponse"
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
- senderAddress
- receiverAddress
properties:
senderAddress:
type: string
description: "It is the MSISDN or virtual MSIDN of the sender."
example: "278945464"
receiverAddress:
description: "This an array of the subscriber MSISDN(s) 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: array
items:
type: string
example: ["27123456789"]
message:
type: string
description: "The message being sent. The standard limit of the size of the message is 160 characters."
maxLength: 160
clientCorrelator:
type: string
description: "It uniquely identifies the request."
maxLength: 36
resourceReference:
type: object
required:
- data
- statusCode
- statusMessage
- transactionId
- _link
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: '0000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client.
example: 'Sucessful'
transactionId:
type: string
description: MADAPI generated Id to include for tracing requests
example: "1365478abcz-fdhsdfh54351"
data:
type: object
required:
- requestId
properties:
requestId:
type: string
description: "Unique identifier for the request"
example: "sub123456"
clientCorrelator:
type: string
description: "field used by client to track"
example: "25145dsfd5"
_link:
type: "object"
required:
- "self"
properties:
self:
type: "object"
required:
- "href"
description: ""
properties:
href:
type: "string"
description: ""
example: "https://api.mtn.com/v1/messages/sms/outbound"
resourceReferencev3:
type: object
required:
- data
- 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: '0000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client.
example: 'Sucessful'
transactionId:
type: string
description: This is the client generated clientCorrelator that is echoed back. Incase the clientCorrelator was not set, then the madapi generated ID will be returned
example: "1365478abcz"
data:
type: object
properties:
status:
type: string
description: "Status of the submitted outbound message(s)"
example: "PENDING"
deliveryInfoNotification:
type: object
required:
- resourceURL
- transactionId
properties:
deliveryInfo:
# type: array
# items:
$ref: "#/definitions/deliveryInfo"
deliveryInfo:
type: object
required:
- receiverAddress
- deliveryStatus
- requestId
properties:
requestId:
type: string
description: "Identifier used to link the delivery notification to the message sent"
example: "req445454"
clientCorrelator:
type: string
description: "Identifier passed by client when sending the message"
deliveryStatus:
type: array
items:
type: object
required:
- receiverAddress
- status
properties:
receiverAddress:
type: string
description: "Subscriber MSISDN"
example: "27568942200"
status:
$ref: "#/definitions/status"
status:
type: "string"
title: "Delivery status"
description: "SMS delivery status.\nSuccessful delivery to Terminal value is \"DeliveredToTerminal\"\nDelivery status unknown: e.g. because it was handed off to another network value is \"DeliveryUncertain\"\nUnsuccessful delivery; the message could not be delivered before it expired value is \"DeliveryImpossible\"\nThe message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states value is \"MessageWaiting\"\nSuccessful delivery to the network entity responsible for distributing the short message further in the network value is \"DeliveredToNetwork\"\nUnable to provide delivery receipt notification. NotifyMessageDeliveryReceipt function will provide DeliveryNotificationNotSupported to indicate that delivery receipt for the specified address in a send message request is not supported value is \"DeliveryNotificationNotSupported\""
example: "DeliveredToTerminal"
enum:
- "DeliveredToTerminal"
- "DeliveryUncertain"
- "DeliveryImpossible"
- "MessageWaiting"
- "DeliveredToNetwork"
- "DeliveryNotificationNotSupported"
deliveryStatusResponse:
type: object
required:
- data
- statusCode
- statusMessage
- transactionId
- _link
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: '0000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client.
example: 'Sucessful'
transactionId:
type: string
description: MADAPI generated Id to include for tracing requests
example: "1365478abcz-fdhsdfh54351"
data:
$ref: "#/definitions/deliveryInfo"
_link:
$ref: "#/definitions/Links"
inboundSMSMessageResponse:
type: object
required:
- data
- statusCode
- statusMessage
- transactionId
- _link
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: '0000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client.
example: 'Sucessful'
transactionId:
type: string
description: MADAPI generated Id to include for tracing requests
example: "1365478abcz-fdhsdfh54351"
data:
$ref: "#/definitions/inboundSMSMessageList"
_link:
type: "object"
required:
- "self"
properties:
self:
type: "object"
required:
- "href"
description: ""
properties:
href:
type: "string"
description: ""
example: "https://api.mtn.com/v1/messages/sms/inbound/registrations/10111/messages"
inboundSMSMessageList:
type: object
properties:
numberOfMessagesInThisBatch:
type: string
description: "The number of messages in the batch."
example: "10"
totalNumberOfPendingMessages:
type: string
description: "Total number of messages in the gateway storage waiting for retrieval at the time of the request"
example: "10"
inboundSMSMessage:
type: array
items:
$ref: "#/definitions/inboundSMSMessage"
inboundSMSMessage:
type: object
required:
- registrationId
- senderAddress
- message
properties:
dateTime:
type: string
description: "The time when the message is received."
example: "2012-08-01T09:25:55.815+0000"
registrationId:
type: string
description: "The number associated with service (for example, an agreed short code)"
example: "10111"
message:
type: string
description: "The SMS message itself"
example: "Hello MADAPI SMS receiver!!!"
senderAddress:
type: string
description: "The MSISDN or Anonymous Customer Reference of the sender"
example: "27830000001"
messageID:
type: string
description: "Server-generated message identifier"
example: "4444aaz-ddsds-45"
format: URL
deliveryReceiptSubscription:
type: object
required:
- notifyUrl
- targetSystem
properties:
notifyUrl:
type: string
example: "https://example.com/12acb41"
targetSystem:
type: string
example: "MADAPI"
subscriptionResponse:
type: object
required:
- data
- statusCode
- statusMessage
- transactionId
- _link
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: '0000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client.
example: 'Sucessful'
transactionId:
type: string
description: MADAPI generated Id to include for tracing requests
example: "1365478abcz-fdhsdfh54351"
data:
type: object
properties:
subscriptionId:
type: string
description: "Unique identifier for the subscription"
example: "sub123456"
_link:
type: "object"
required:
- "self"
properties:
self:
type: "object"
required:
- "href"
description: ""
properties:
href:
type: "string"
description: ""
example: "https://api.mtn.com/v1/messages/sms/outbound/10111/subscription"
outboundSubscriptionDeleteResponse:
type: object
required:
- data
- statusCode
- statusMessage
- transactionId
- _link
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: '0000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client.
example: 'Sucessful'
transactionId:
type: string
description: MADAPI generated Id to include for tracing requests
example: "1365478abcz-fdhsdfh54351"
data:
type: object
_link:
type: "object"
required:
- "self"
properties:
self:
type: "object"
required:
- "href"
description: ""
properties:
href:
type: "string"
description: ""
example: "https://api.mtn.com/v1/messages/sms/outbound/10111/subscription/10c0d78cd4bf77e"
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'
Links:
type: "object"
required:
- "self"
properties:
self:
type: "object"
required:
- "href"
description: ""
properties:
href:
type: "string"
description: ""
example: "https://api.mtn.com/v1/messages/sms/outbound/10111/10c0d78cd4bf77ee%40138a3d02644/deliveryStatus"