gatewaysms.openapi.json

{"openapi":"3.0.0","info":{"description":"This web service exposes REST calls to send text messages directly from our gateway","version":"1.0.0","title":"Gateway SMS","termsOfService":"https://openapi.it/en/terms-and-conditions","contact":{"url":"https://openapi.it/en/support","name":"Support"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"}},"servers":[{"url":"https://ws.messaggisms.com","description":"Production"},{"url":"https://test.ws.messaggisms.com","description":"Sandbox"}],"tags":[{"name":"Messages","description":"Calls to send, view and edit SMS messages"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"PostBodyMessage":{"type":"object","properties":{"test":{"type":"boolean","description":"By default it is false, if set to true it simulates a send"},"sender":{"type":"string","description":"The sender must be between 3 and 11 characters if alphanumeric and between 3 and 14 if numeric"},"body":{"type":"string","description":"Text of the sms; we can insert in the text the values of the 'placeholder' parameters contained in 'fields' in this way: “body”: “Test invio {{name}}”"},"recipients":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"number":{"type":"string"},"fields":{"type":"object","properties":{"name":{"type":"string"},"surname":{"type":"string"}}}}}],"description":"Phone number of the recipient and wanting the 'fields' object in which to insert the parameters that we want to enter in the 'body' like this: {'number':'+39-34xxxxx987', 'fields':{'name':'simone', 'surname':'rossi'}}. Mandatory is the international prefix which must be separated from the rest by '-' like this: '+39-number'. Any other format will be considered bad recipients and placed among the invalid"},"priority":{"type":"number","format":"double","description":"Sending priority; default is 1.00 which is the minimum; increasing the priority increases the total cost of the message but assuming that in the queue there are 1000 messages with priority 1.00, by sending a message with priority 1.01 you skip the queue"},"options":{"$ref":"#/components/schemas/Options"},"transaction":{"type":"boolean","description":"By default, FALSE is set. Set to TRUE, it starts a transaction by storing the data sent but not putting the request in the queue. Subsequent PUT calls can be made on the end point '/messages/{id}/' to integrate the initial POST call (for example adding recipients) until a PUT is sent with 'transaction' : FALSE. The ID field is returned from the first POST call. At that point the transaction (if valid) is closed and the message queues normally"}},"required":["sender","body","recipients"]},"Options":{"type":"object","properties":{"flash":{"type":"boolean","description":"By default it is set to FALSE, if instead it is assigned to it TRUE considers the SMS as a flash message, which will appear on the recipient's device as a pop-up"},"timestamp_send":{"type":"string","description":"Indicates the date on which you want to send the message; the correct format wants this type of separator between the digits '-', the number of the month always in between, while year and day can interchange at will between first or third place in this way: '2018-05-20' or '20-05-2018'; if not set, the sending will be scheduled for that precise moment"},"custom":{"type":"string","description":"A field to be valued according to our own structure"},"callback_url":{"type":"string","description":"Address to which a message summary json is sent each time it changes state. If nothing is specified in 'callback_field' the json is sent to the payload of the call"},"callback_field":{"type":"string","description":"Linked to the 'callback_url'; if this parameter is specified, the json will be sent in POST in the ‘parameter value’ variable"},"realtime":{"type":"boolean","description":"By default it is set to FALSE, if instead it is assigned to it TRUE considers the SMS as an OTP or 2FA message and will be sent immediately skipping all the queues, it is possible to send only one realtime message per minute"}}},"PutBodyMessage":{"type":"object","properties":{"recipients":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"number":{"type":"string"},"fields":{"type":"object","properties":{"name":{"type":"string"},"surname":{"type":"string"}}}}}],"description":"Phone number of the recipient and wanting the 'fields' object in which to insert the parameters that we want to enter in the 'body' like this: {'number':'+39-34xxxxx987', 'fields':{'name':'simone', 'surname':'rossi'}}. Mandatory is the international prefix which must be separated from the rest by '-' like this: '+39-number'. Any other format will be considered bad recipients and placed among the invalid"},"transaction":{"type":"boolean","description":"Until it is set to false the transaction is not closed and the message will not go into the sending queue"},"options":{"type":"object","properties":{"timestamp_send":{"type":"string","description":"Indicates the date on which you want to send the message; the correct format wants this type of separator between the digits '-', the number of the month always in between, while year and day can interchange at will between first or third place in this way: '2018-05-20' or '20-05-2018'; if not set, the sending will be scheduled for that precise moment"}}}},"required":["recipients"]},"Message_Object":{"type":"object","properties":{"test":{"type":"boolean"},"sender":{"type":"string"},"body":{"type":"string"},"recipients":{"$ref":"#/components/schemas/Recipients"},"priority":{"type":"number","format":"double"},"options":{"$ref":"#/components/schemas/Options"},"transaction":{"type":"boolean"},"statistics":{"$ref":"#/components/schemas/Statistics"},"base_price":{"type":"number","format":"double"},"timestamp":{"type":"string"},"last_update":{"type":"string"},"price":{"type":"number","format":"double"},"state":{"type":"integer"},"id":{"type":"string"}}},"Recipients":{"type":"object","properties":{"valid":{"type":"object","properties":{"count":{"type":"integer"}}},"invalid":{"type":"object","properties":{"total":{"type":"integer"},"list":{"type":"array","items":{"type":"string"}}}}}},"Statistics":{"type":"object","properties":{"error":{"type":"integer"},"sent":{"type":"integer"},"delivered":{"type":"integer"},"total":{"type":"integer"},"sms_total":{"type":"integer"}}},"Messages":{"type":"object","properties":{"sender":{"type":"string"},"timestamp":{"type":"string"},"id":{"type":"string"}}},"Recipient_Object":{"type":"object","properties":{"number":{"type":"string"},"prefix":{"type":"string"},"send_id":{"type":"string"},"body":{"type":"string"},"sms":{"type":"integer"},"remaining_chr":{"type":"integer"},"state":{"type":"string"},"state_description":{"type":"string"},"price":{"type":"number","format":"double"},"fields":{"type":"array","items":{"type":"object"}},"message_id":{"type":"string"},"i":{"type":"integer"},"state_detail":{"type":"string"},"timestamp_sent":{"type":"string"},"real_cost":{"type":"number","format":"double"},"report":{"$ref":"#/components/schemas/Report"},"timestamp_delivery":{"type":"string"},"id":{"type":"string"}}},"Report":{"type":"object","properties":{"price":{"type":"object","properties":{"pricePerMessage":{"type":"number","format":"double"},"currency":{"type":"string"}}},"status":{"type":"object","properties":{"id":{"type":"integer"},"groupId":{"type":"integer"},"groupName":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}},"error":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"groupId":{"type":"integer"},"groupName":{"type":"string"},"permanent":{"type":"boolean"}}},"messageId":{"type":"string"},"doneAt":{"type":"string"},"smsCount":{"type":"integer"},"sentAt":{"type":"string"},"to":{"type":"string"}}}}},"paths":{"/messages/":{"get":{"tags":["Messages"],"summary":"List of your messages","description":"This method allows you to view the list of sent messages from your account","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Messages"}},"success":{"type":"boolean"},"message":{"type":"string"},"credit":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"sender":"alberto","timestamp":"1564411330117","id":"5d3f05c29f2725610c2b4e60"},{"sender":"3939989741","timestamp":"1563554978976","id":"5d31f4a29f27257de166d960"},{"sender":"3939989741","timestamp":"1562686328690","id":"5d24b3789f27257de1645bda"},{"sender":"Nome del mittente","timestamp":"1562142688118","id":"5d1c67e09f27255e2f4079a3"},{"sender":"Nome del mittente","timestamp":"1562142398400","id":"5d1c66be9f272563102e8045"}],"success":true,"message":"5 Results","credit":"91.00299999999986","error":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"No message found","error":203,"data":null}}}}}},"post":{"tags":["Messages"],"summary":"Send a sms message","description":"This method allows you to send an sms message directly from our gateway.\n\n*Short messages can be encoded using a variety of alphabets: the default GSM 7-bit alphabet,\nthe 8-bit data alphabet, and the 16-bit UCS-2 or UTF-16 alphabets.\nDepending on which alphabet the subscriber has configured in the handset,\nthis leads to the maximum individual short message sizes of 160 7-bit characters,\n140 8-bit characters, or 70 16-bit characters.\nGSM 7-bit alphabet support is mandatory for GSM handsets and network elements,\nbut characters in languages such as Hindi, Arabic, Chinese, Korean, Japanese,\nor Cyrillic alphabet languages (e.g., Russian, Ukrainian, Serbian, Bulgarian, etc.)\nmust be encoded using the 16-bit UCS-2 character encoding.\nRouting data and other metadata is additional to the payload size.\nLarger content (concatenated SMS, multipart or segmented SMS, or \"long SMS\")\ncan be sent using multiple messages, in which case each message will start with a User Data Header (UDH)\ncontaining segmentation information. Since UDH is part of the payload,\nthe number of available characters per segment is lower: 153 for 7-bit encoding,\n134 for 8-bit encoding and 67 for 16-bit encoding. The receiving handset\nis then responsible for reassembling the message and presenting it to the user\nas one long message. While the standard theoretically permits up to 255 segments,\n10 segments is the practical maximum with some carriers, and long messages are\noften billed as equivalent to multiple SMS messages.*\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostBodyMessage"},"example":{"test":false,"sender":"alberto","body":"test invio","recipients":"+39-349xxxxx18"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message_Object"}},"success":{"type":"boolean"},"message":{"type":"string"},"credit":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"test":false,"sender":"alberto","body":"test invio","recipients":{"valid":{"count":1},"invalid":{"total":0,"list":[]}},"transaction":false,"options":{"flash":false,"realtime":false,"timestamp_send":"1564752494920"},"statistics":{"error":0,"sent":0,"delivered":0,"total":1,"sms_total":1},"base_price":0.0315,"timestamp":"1564752494920","last_update":"1564752494920","priority":1,"price":0.0315,"state":0,"id":"5d443a6e9f2725660f3db347"}],"message":"Message Queued","credit":"90.90849999999988","success":true,"error":null}}}},"402":{"description":"Payment Required","content":{"application/json":{"example":{"success":false,"message":"Current User credit is not enough. 0.3 needed 0.1 € available","error":201,"data":null}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"example":{"success":false,"message":"missing 'body' parameter","error":302,"data":null}}}}}}},"/messages/{id}":{"get":{"tags":["Messages"],"summary":"Get a single message","description":"This method allows you to see the single message related to the parameter passed in the path","parameters":[{"name":"id","in":"path","description":"Message Id","required":true,"schema":{"type":"string","example":"5cf7cc139f272546624d3795"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message_Object"}},"success":{"type":"boolean"},"message":{"type":"string"},"credit":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"test":false,"sender":"Simone","body":"Production test 4 ","recipients":{"valid":{"count":1},"invalid":{"total":0,"list":[]}},"priority":1,"options":{"flash":true,"realtime":true,"timestamp_send":"326152800000","custom":{"test":123,"best":321,"trest":[12,3,12,3]},"callback_url":"https://test.ws.messaggisms.com/callbackTest.php"},"transaction":false,"statistics":{"error":0,"sent":1,"delivered":1,"total":1,"sms_total":1},"base_price":0.03,"timestamp":"1559743507600","last_update":"1559743510156","price":0.036,"state":2,"id":"5cf7cc139f272546624d3795"}],"message":"1 Result","credit":"90.97149999999986","success":true,"error":null}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"example":{"success":false,"message":"Invalid Message ID","error":202,"data":null}}}}}},"put":{"tags":["Messages"],"summary":"Message integration","description":"If a message exists with 'transaction = true', this method allows integrating the initial POST call (adding recipients for example) until a PUT with 'transaction = false' is passed. At that point the message is closed and put in the sending queue. With this method you can also change the sending date of the message ('timestamp_send') (if it hasn't already been sent or scheduled for sending).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutBodyMessage"},"example":{"recipients":["+39-3xxxxxx115"],"options":{"timestamp_send":"2023-12-25"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message_Object"},"success":{"type":"boolean"},"message":{"type":"string"},"credit":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":{"test":false,"sender":"alberto","body":"test invio","recipients":{"valid":{"count":4},"invalid":{"total":0,"list":[]}},"transaction":true,"options":{"flash":false,"realtime":false,"timestamp_send":"1564751430282"},"statistics":{"error":0,"sent":0,"delivered":0,"total":4,"sms_total":4},"base_price":0.126,"timestamp":"1564751430282","last_update":"1564751430282","priority":1,"price":0.126,"state":0,"id":"5d4436469f272566771c6671"},"message":"Updated","credit":"90.97149999999986","success":true,"error":null}}}},"402":{"description":"Payment Required","content":{"application/json":{"example":{"success":false,"message":"Insufficient Credit in Wallet: 182.03","error":201,"data":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"No message found","error":211,"data":null}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"example":{"success":false,"message":"Invalid Message ID","error":210,"data":null}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"example":{"success":false,"message":"Transaction already closed","error":212,"data":null}}}}}},"delete":{"tags":["Messages"],"summary":"Delete a single message","description":"This method allows you to cancel and therefore not send a message (not allowed on messages already sent or scheduled for sending). With the cancellation there is no refund on the spent credits.","parameters":[{"name":"id","in":"path","description":"Message Id","required":true,"schema":{"type":"string","example":"5cf7cc139f272546624d3795"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[],"message":"5cf7cc139f272546624d3795 Deleted","success":true,"error":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"success":false,"message":"Message Id required","error":217,"data":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"No message found","error":219,"data":null}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"example":{"success":false,"message":"Invalid Message ID","error":218,"data":null}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"example":{"success":false,"message":"message already scheduled for sending","error":221,"data":null}}}}}}},"/messages/{id}/recipients/":{"get":{"tags":["Messages"],"summary":"Get the recipients from a message","description":"This method allows you to see the recipients of a particular message","parameters":[{"name":"id","in":"path","description":"Message Id","required":true,"schema":{"type":"string","example":"5e5e65429f272510fb6adcc0"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recipient_Object"}},"success":{"type":"boolean"},"message":{"type":"string"},"credit":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"number":"+39-3xxxxx5018","prefix":"+39","send_id":"5e5e65429f272510fb6adcc0_0","body":"test summary2","sms":1,"remaining_chr":147,"state":"DELIVERED","state_description":"DELIVERED_TO_HANDSET","price":0.03,"fields":[],"message_id":"5e5e65429f272510fb6adcc0","i":0,"state_detail":"Message delivered to handset","timestamp_sent":{"$date":{"$numberLong":"1583244661371"}},"real_cost":0.03,"report":{"price":{"pricePerMessage":0.03,"currency":"EUR"},"status":{"id":5,"groupId":3,"groupName":"DELIVERED","name":"DELIVERED_TO_HANDSET","description":"Message delivered to handset"},"error":{"id":0,"name":"NO_ERROR","description":"No Error","groupId":0,"groupName":"OK","permanent":false},"messageId":"5e5e65429f272510fb6adcc1","doneAt":"2020-03-03T15:11:03.168+0100","smsCount":1,"sentAt":"2020-03-03T15:11:01.467+0100","to":"393495155018"},"timestamp_delivery":{"$date":{"$numberLong":"1583244663000"}},"id":"5e5e65429f272510fb6adcc1"}],"message":"1 Result","credit":90.20949999999985,"success":true,"error":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"No message found","error":203,"data":null}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"example":{"success":false,"message":"Invalid Message ID","error":202,"data":null}}}}}}},"/messages/{id}/recipients/{number}":{"get":{"tags":["Messages"],"summary":"Get the recipient from a message","description":"This method allows you to see the specific recipient of a particular message","parameters":[{"name":"id","in":"path","description":"Message Id","required":true,"schema":{"type":"string","example":"5e5e65429f272510fb6adcc0"}},{"name":"number","in":"path","description":"Recipient number","required":true,"schema":{"type":"string","example":"+39-34xxxxx018"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recipient_Object"}},"success":{"type":"boolean"},"message":{"type":"string"},"credit":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"number":"+39-3xxxxx5018","prefix":"+39","send_id":"5e5e65429f272510fb6adcc0_0","body":"test summary2","sms":1,"remaining_chr":147,"state":"DELIVERED","state_description":"DELIVERED_TO_HANDSET","price":0.03,"fields":[],"message_id":"5e5e65429f272510fb6adcc0","i":0,"state_detail":"Message delivered to handset","timestamp_sent":{"$date":{"$numberLong":"1583244661371"}},"real_cost":0.03,"report":{"price":{"pricePerMessage":0.03,"currency":"EUR"},"status":{"id":5,"groupId":3,"groupName":"DELIVERED","name":"DELIVERED_TO_HANDSET","description":"Message delivered to handset"},"error":{"id":0,"name":"NO_ERROR","description":"No Error","groupId":0,"groupName":"OK","permanent":false},"messageId":"5e5e65429f272510fb6adcc1","doneAt":"2020-03-03T15:11:03.168+0100","smsCount":1,"sentAt":"2020-03-03T15:11:01.467+0100","to":"393495155018"},"timestamp_delivery":{"$date":{"$numberLong":"1583244663000"}},"id":"5e5e65429f272510fb6adcc1"}],"message":"1 Result","credit":90.20949999999985,"success":true,"error":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"No message found","error":203,"data":null}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"example":{"success":false,"message":"Invalid Message ID","error":202,"data":null}}}}}}}},"externalDocs":{"description":"First time here? Generate a new access token","url":"https://console.openapi.com/oauth"},"security":[{"bearerAuth":[]}]}