openapi: 3.0.3 info: description: | This API provides the IoT Accelerator SMS Messaging API. The SMS Messaging API allows a web application to send and receive SMS messages over HTTPS and simplifies the communication between the enterprise and the IoT Accelerator SMSC. The service supports the sending and receiving of both binary and text SMS messages. The IoT Accelerator SMS Messaging API is based on the following OneAPI SMS interface: - OMA REST NetAPIs v1 # Scope This specification covers the following topics - An overview of all services offered by the SMS Messaging API interface - A detailed description of all the procedures and operations that a user of the interface can perform and all the possible results # Target Groups This specification is intended for enterprise users that want to know how to use the DCP SMS Messaging API interface. # Prerequisites It is assumed that the user is familiar with the following - Extensible Markup Language® (XML) - Java Script Object Notation (JSON) - Basic understanding of RESTful web services - Tools and programming languages for consuming RESTful web services version: v2 title: SMS Messaging API x-audience: external-public paths: "/outbound/{senderAddress}/requests": post: summary: Sends an SMS message to one or more devices tags: - sendSMS operationId: sendSMS parameters: - name: senderAddress description: "A string that represents the address of the enterprise that sends the SMS. For example tel:12345678" in: path required: true schema: type: string - name: Authorization description: "Should contain a base64 Basic auth string" in: header required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/OutboundSMSMessageRequestHolder" example: outboundSMSMessageRequest: address: - 'tel:13500000991' - 'tel:13500000992' senderAddress: 'tel:12345678' senderName: "Me" outboundSMSTextMessage: message: Hello World responses: '201': description: successful response content: application/json: schema: $ref: "#/components/schemas/OutboundSMSMessageRequestHolder" example: outboundSMSMessageRequest: address: - 'tel:13500000991' - 'tel:13500000992' deliveryInfoList: deliveryInfo: - address: "tel:13500000991" deliveryStatus: "DeliveredToTerminal" - address: "tel:13500000992" deliveryStatus: "DeliveredToNetwork" resourceURL: "https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1/outbound/tel:12345/requests/dcp1234567/deliveryInfos" senderAddress: "tel:12345" senderName: "Me" outboundSMSTextMessage: message: "Deep Purple" resourceURL: "https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1/outbound/tel:12345/requests/dcp1234567/" '400': description: "Bad Request" content: application/json: schema: $ref: "#/components/schemas/RequestError" example: requestError: serviceException: messageId: "SVC0004" text: "No valid addresses provided inmessage part %1" variables: "address, (each address must be prefixed with tel:)" '401': description: "Authentication Failure" content: application/json: schema: $ref: "#/components/schemas/RequestError" '403': description: "Forbidden" content: application/json: schema: $ref: "#/components/schemas/RequestError" example: requestError: policyException: messageId: "POL0010" text: "User has not been provisioned for %1" variables: "SMSMessaging" '404': description: "No Found" content: application/json: schema: $ref: "#/components/schemas/RequestError" '503': description: "Service Unavailable" content: application/json: schema: $ref: "#/components/schemas/RequestError" "/outbound/{senderAddress}/requests/{requestId}/deliveryInfos": get: summary: Queries the delivery status of an SMS. tags: - querySMS operationId: querySMS parameters: - name: senderAddress description: "A string that represents the address of the enterprise that raises the request.For example tel:12345678" in: path required: true schema: type: string - name: requestId description: "A string that must be entered as returned in the related sendSMS successful response." in: path required: true schema: type: string - name: Authorization description: "Should contain a base64 Basic auth string" in: header required: true schema: type: string responses: '200': description: successful response content: application/json: schema: $ref: "#/components/schemas/DeliveryInfoList" example: deliveryInfo: - address: "tel:13500000991" deliveryStatus: "DeliveredToTerminal" - address: "tel:13500000992" deliveryStatus: "DeliveredToNetwork" resourceURL: "https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1/outbound/tel:12345/requests/dcp1234567/deliveryInfos" '400': description: "Bad Request" content: application/json: schema: $ref: "#/components/schemas/RequestError" example: requestError: serviceException: messageId: "SVC0010" text: "Requested information unavailable as the retention time interval has expired." variables: "" '401': description: "Authentication Failure" content: application/json: schema: $ref: "#/components/schemas/RequestError" '403': description: "Forbidden" content: application/json: schema: $ref: "#/components/schemas/RequestError" example: requestError: policyException: messageId: "POL0010" text: "User has not been provisioned for %1" variables: "SMSMessaging" '404': description: "No Found" content: application/json: schema: $ref: "#/components/schemas/RequestError" '503': description: "Service Unavailable" content: application/json: schema: $ref: "#/components/schemas/RequestError" "/inbound/registrations/{registrationID}/messages": get: summary: Retrieves an SMS sent to a web application. tags: - retrieveSMS operationId: retrieveSMS parameters: - name: registrationID description: "Identity provided by DCP that grants with unique access to the received SMS messages." in: path required: true schema: type: string - name: maxBatchSize description: "The maximum number of messages to retrieve in the request." in: query required: false schema: type: string default: "2147483647" - name: Authorization description: "Should contain a base64 Basic auth string" in: header required: true schema: type: string responses: '200': description: successful response content: application/json: schema: $ref: "#/components/schemas/InboundSMSMessageRequest" example: inboundSMSMessageList: inboundSMSMessage: - dateTime: "2009-11-19T12:00:00" destinationAddress: "3456" messageId: "msg1" message: "Come on Barca!" resourceURL: "http://example.com/smsmessaging/v1/inbound/registrations/3456/messages/msg1" senderAddress: "+447825123456" - dateTime: "2009-11-19T12:00:00" destinationAddress: "3456" messageId: "msg2" message: "aDffiuek5fjj=" resourceURL: "http://example.com/smsmessaging/v1/inbound/registrations/3456/messages/msg2" senderAddress: "+447825789123" messageType: "binary" numberOfMessagesInThisBatch: "2" resourceURL: "http://example.com/smsmessaging/v1/inbound/registrations/3456/messages" totalNumberOfPendingMessages: "20" '400': description: "Bad Request" content: application/json: schema: $ref: "#/components/schemas/RequestError" example: requestError: serviceException: messageId: "SVC0003" text: "Invalid input value for message part , valid values are %2" variables: "maxBatchSize, (positive integer)" '401': description: "Authentication Failure" content: application/json: schema: $ref: "#/components/schemas/RequestError" '403': description: "Forbidden" content: application/json: schema: $ref: "#/components/schemas/RequestError" example: requestError: policyException: messageId: "POL0010" text: "User has not been provisioned for %1" variables: "SMSMessaging" '404': description: "No Found" content: application/json: schema: $ref: "#/components/schemas/RequestError" '503': description: "Service Unavailable" content: application/json: schema: $ref: "#/components/schemas/RequestError" servers: - url: https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1 description: SMS API server security: - BasicAuth: [] components: schemas: RequestError: type: object properties: requestError: type: object properties: serviceException: type: object properties: messageId: type: string description: "violation identifier, ref. User Guide" text: type: string description: "describes the violation" variables: type: string description: "points to the variable(s) in violation" policyException: type: object properties: messageId: type: string description: "violation identifier, ref. User Guide" text: type: string description: "describes the violation" variables: type: string description: "points to the variable(s) in violation" InboundSMSMessageRequest: type: object properties: inboundSMSMessageList: type: object properties: inboundSMSMessage: type: array items: $ref: "#/components/schemas/InboundSMSMessage" numberOfMessagesInThisBatch: type: string description: "The number of SMS messages retrieved in the successful response." resourceURL: type: string description: "Link to the successful response." totalNumberOfPendingMessages: type: string description: "Total number of SMS messages that are awaiting for retrieval from storage." InboundSMSMessage: type: object properties: dateTime: type: string description: "Date and time when the successful response is created." destinationAddress: type: string description: "The number associated with your service. It corresponds to the registrationID." messageId: type: string description: "Message identifier generated automatically by the server." message: type: string description: "For Text SMS: a string with maximum 160 characters. For Binary SMS: a Base64 (RFC4648) encoded string with up to 140 bytes of binary data. For example: AQIDBAUGBwgJCg==" resourceURL: type: string description: "Link to the SMS message." senderAddress: type: string description: "The name of the enterprise that sent the SMS." messageType: type: string description: "The type of SMS message. For Binary SMS: use 'binary'. When field is not present, the message is a text message" DeliveryInfo: type: object required: - address - deliveryStatus properties: address: type: string description: "The recipients MSISDN including the tel: protocol identifier. For example: tel:16309700001" deliveryStatus: type: string description: "Delivery status for the recipient identified by address. " enum: - DeliveredToTerminal - DeliveryUncertain - DeliveryImpossible - MessageWaiting - DeliveredToNetwork DeliveryInfoList: type: object required: - deliveryInfo - resourceURL properties: deliveryInfo: type: array description: "List of deliveryInfos" items: $ref: "#/components/schemas/DeliveryInfo" resourceURL: type: string description: "Link to the successful response." DeliveryInfoObject: type: object properties: deliveryInfoList: items: $ref: "#/components/schemas/DeliveryInfoList" OutboundSMSBinaryMessage: type: object required: - message properties: message: type: string description: "Base64 coded string" OutboundSMSMessageRequest: type: object required: - address - senderAddress properties: address: type: array description: "The recipients MSISDN including the ‘tel:' protocol identifier and the country code. For example: tel:16309700001" items: type: string deliveryInfoList: $ref: "#/components/schemas/DeliveryInfoList" senderAddress: type: string description: "A string that represents the address of the enterprise that sends the SMS. For example: tel:12345678" outboundSMSTextMessage: $ref: "#/components/schemas/OutboundSMSTextMessage" outboundSMSBinaryMessage: $ref: "#/components/schemas/OutboundSMSBinaryMessage" senderName: type: string description: "The name of the sender" validityPeriod: type: integer format: int32 description: "The SMSC expiration time, after which the message is discarded if still not delivered to the destination." resourceURL: type: string subAddress: type: string description: "A string that represents the sub-address of the device to send the message to. Supports only SIM card. For example: subAddress:sim" OutboundSMSMessageRequestHolder: type: object required: - outboundSMSMessageRequest properties: outboundSMSMessageRequest: $ref: "#/components/schemas/OutboundSMSMessageRequest" OutboundSMSTextMessage: type: object required: - message properties: message: type: string description: "Regular text string of up to 160 characters." securitySchemes: BasicAuth: type: http scheme: basic