• Webservices Gateway Sms
  • POST Messages

Send Sms

This method allows you to send sms directly via the gateway.


Production environment:

  • https://ws.messaggisms.com/messages/

Testing environment

  • https://test.ws.messaggisms.com/messages/


Property name Type Required Description
test boolean no By default it is false, if set to true it simulates a send.
sender string yes The sender must be between 3 and 11 characters if alphanumeric and between 3 and 14 if numeric.
body string yes 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 string, object, array yes 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-3478569987", "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 double no 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 OptionsDetails no Object in which it is possible to value additional parameters.
transaction boolean no 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.

Options Details

Property name Type Required Description
flash boolean no 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 string no 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 string no A field to be valued according to our own structure.
callback_url string no 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 string no Linked to the "callback_url"; if this parameter is specified, the json will be sent in POST in the ‘parameter value’ variable.
realtime boolean no 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.
bulk boolean no By default it is set to FALSE, if instead it is assigned to it TRUE considers the SMS as a bulk message, the sender is ignored and a low priority message is sent which takes up to 8 hours to be delivered. Consult your list to check if this type of message is enabled.

Request examples


Response Format

If successful, the response header HTTP status code will be 201 Created and the request will be answered.

If you try to get a request without authorization, you will receive an error 401 Unauthorized.

Additionally you should also handle the 400 Bad request status. For more info on HTTP status handling see dedicated section in Integration best practices page.

Request Response

Parameter Type Description
data DataResponseDetails Present only if the API call goes to good end, it will contain the answer data.
message string It contains a message that can be shown by the user.
credit string Remaining credit of the user.
success boolean True or false.
error int Present only if the API call fails, it contains an error code.

Data Response Details

Parameter Type Description
test boolean Identifies if it is a simulation or not.
sender string Sending sender.
body string Text of the sms.
recipients RecipientsResponseDetails Returns the number of "recipients" divided between valid and invalid.
transaction boolean Status of the transaction.
options object Report of the sending options used. Returns the same object with the values ​​passed by you or by default.
statistics StatisticsResponseDetails Report of the resulting sending statistics.
base_price double Starting cost of the text messages sent.
timestamp string Message storage timestamp.
last_update string Timestamp of the last modification of the message.
priority double Priority value set.
price double Total cost resulting from the base_price for the priority.
state int Sending status.
id string Unique identifier of the message.

Recipients Response Details

Parameter Type Description
valid object Contains the count of valid recipients.
count int Number of valid recipients.
invalid object Contains the list of invalid recipients.
total int Number of invalid recipients.
list array List of numbers considered invalid.

Statistics Response Details

Parameter Type Description
error int Number of errors; increases when sending is not completed.
sent int Number of text messages actually sent.
delivered int Number of text messages actually delivered.
total int Number of valid recipients.
sms_total int Number of sms formally correct and ready to be sent