API SMS Gigas
De GIGAS DOCS
Revisión del 22:44 2 dic 2021 de Pablo.desantiago (Discusión | contribuciones) (Página creada con « == GETTING STARTED == Welcome to API documentation. To integrate the API, you'll need some programming skills. If you’re ready to get started, read on. === JSON === F...»)
Contenido
GETTING STARTED
Welcome to API documentation. To integrate the API, you'll need some programming skills. If you’re ready to get started, read on.
JSON
For this version of our API we only support JSON. So instead of XML, HTTP POST parameters, or other serialization formats, all POST/PATCH requests require a valid JSON object for the body.
ENDPOINT
This is the URL you have to request where {app} is the application and {function} the function you want to call.
https://api.gateway360.com/api/3.0/{app}/{funcion}
AUTHENTICATION =
Most api requests will require authentication of the user account. This is always done through the API key associated with your account. You can find your API Key details in your account.
ENCODING
All the parameters must be encoded and they must be in UTF-8.
CONTENT TYPE
When you submit a request it's really important to set Content-Type: application/json
ERROR HANDLING
Plan to encounter errors of varying degrees. From an invalid request to the rare outage, you'll see the errors appear as an HTTP Response code. 400-series errors (code 400-499) indicate a bad request. Do not retry without fixing this error first. 500-series errors (500-599) indicate a problem on our servers.
SEND SMS
With this method you can send bulk SMS easily. This method has been extremely optimized to send more than 500.000 SMS in less than one hour.
ENDPOINT
https://api.gateway360.com/api/3.0/sms/send
REQUEST
Parameters
api_key |
Your API Key. | ||||||||||
messages |
Array of messages you want to send.
| ||||||||||
| report_url | URL where you want to receive the delivery report (DLR). | ||||||||||
| concat | Set to 1 if you want to allow concatenated messages (more than 160 characters). If concat is 0 (or it's not present) only first 160 chars will be sent. | ||||||||||
| encoding | Set to UCS2 if you want to send messages UCS2 (70 Unicode characters per SMS) with accents, emoticons and special characters. If encoding is GSM7 (or it's not present) the SMS will be treated as GSM7 (160 non Unicode characters per SMS). The Unicode encoding is only applicable to the text of message. | ||||||||||
| fake | Set to 1 if you want to simulate submitting messages, it's perfect for testing and debugging, it has no cost. | ||||||||||
JSON
{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}
cURL
curl - X POST \
- H 'Content-Type: application/json' \
- H 'Accept: application/json' \
-d '{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss
with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
SEND SMS 8
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a bo
ss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}' https: / /api.gateway360.com/api/3.0/sms/send
PHP
$request = '{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}';
$headers = array('Content-Type: application/json');
$ch = curl_init('https://api.gateway360.com/api/3.0/sms/send');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$result = curl_exec($ch);
if (curl_errno($ch) != 0 ){
die("curl error: ".curl_errno($ch));
}
Java
/** Imports */
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClientBuilder;
/** End imports */
HttpClient httpClient = HttpClientBuilder.create().build();
HttpPost request = new HttpPost("https://api.gateway360.com/api/3.0/sms/send");
StringEntity params = new StringEntity(
"{" +
" \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," +
" \"report_url\":\"http://yourserver.com/callback/script\"," +
" \"concat\":1," +
" \"messages\":[" +
" {" +
" \"from\":\"GOOD PIZZA\"," +
" \"to\":\"34666666111\"," +
" \"text\":\"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!\"," +
" \"send_at\":\"2018-02-18 17:30:00\""+
" }," +
" {" +
" \"from\":\"GOOD PIZZA\"," +
" \"to\":\"34666666112\"," +
" \"text\":\"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!\"," +
" \"send_at\":\"2018-02-18 17:30:00\""+
" }" +
" ]" +
"}");
request.addHeader("content-type", "application/json");
request.addHeader("Accept","application/json");
request.setEntity(params);
HttpResponse response = httpClient.execute(request);
Ruby
require 'uri'
require 'net/http'
url = URI("https://api.gateway360.com/api/3.0/sms/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request.body = '{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}'
response = http.request(request)
puts response.read_body
Python
conn = http.client.HTTPSConnection("api.gateway360.com")
payload = """{
"api_key":"399d2b438a53ebed3db8a7d52107f846",
"report_url":"http://yourserver.com/callback/script",
"concat":1,
"messages":[
{
"from":"GOOD PIZZA",
"to":"34666666111",
"text":"Hi John, today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"send_at":"2018-02-18 17:30:00"
},
{
"from":"GOOD PIZZA",
"to":"34666666112",
"text":"Hi Maria, , today 2x1 in pizzas, watch the game like a boss with our new pepperoni pizza!",
"custom":"MyMsgID-12345",
"send_at":"2018-02-18 17:30:00"
}
]
}"""
headers = {
'content-type': "application/json",
'accept': "application/json"
}
conn.request("POST", "/api/3.0/sms/send", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
RESPONSE
Parameters
| status | The sending status of request - either "ok", "error" | ||||||||||
| result | Array of results in the same order you submitted.
| ||||||||||
| error_id | In case the status values "error" we will indicate you here the error id. | ||||||||||
| error_msg | In case the status values "error" this param has additional information. This param should be use just for debugging. | ||||||||||
Example 1
200 OK
{
"status":"ok",
"result":[
{
"status":"ok",
"sms_id":"1a8940dc7471427db3021cde5b464444",
"custom":"test"
},
{
"status":"ok",
"sms_id":"1a8940dc7471427db3021cde5b464481",
"custom":""
}
]
}
- Two messages successfully processed
Example 2
200 OK
{
"status":"ok",
"result":[
{
"status":"ok",
"sms_id":"1a8940dc7471427db3021cde5b464444",
"custom":"test"
},
{
"status":"error",
"error_id":"INVALID_SENDER",
"error_msg":"Sender cannot exceed 11 alphanumeric or 15 numeric characters.",
"custom":""
},
{
"status":"error",
"error_id":"INVALID_DESTINATION",
"error_msg":"Destination number must be in international format.",
"custom":"12345"
},
{
"status":"error",
"error_id":"NOT_ENOUGH_BALANCE",
"error_msg":"Your account has no funds.",
"custom":""
},
{
"status":"error",
"error_id":"INVALID_DATETIME",
"error_msg":"Invalid datetime format.",
"custom":""
}
]
}
- One message successfully processed, and the rest with several errors.
Example 3
401 Unauthorized
{
"status":"error",
"error_id":"UNAUTHORIZED",
"error_msg":"Your API key may be invalid or your IP is blocked."
}
- We didn't continue processing your request because your API Key wasn't valid.
Example 4
400 Bad Request
{
"status":"error",
"error_id":"JSON_PARSE_ERROR",
"error_msg":"Your JSON was formatted incorrectly."
}
- We couldn't process your request
ERRORS
| Error ID | Explanation |
| INVALID_CONTENT_TYPE | The content type must be: Content-Type: application/json |
| JSON_PARSE_ERROR | Your JSON was formatted incorrectly or was considered otherwise improper or incomplete. Check it here. |
| MISSING_PARAMS | Your request is incomplete and missing some mandatory parameters. |
| BAD_PARAMS | One or more of your parameters has incorrect format or value. |
| UNAUTHORIZED | Your API key may be invalid, double-check that your API key was input correctly or see if the IP is blocked in your account API settings. |
| INVALID_SENDER | The sender address (from parameter) was not allowed for this message. |
| INVALID_DESTINATION | Our Gateway was unable to process your destination. The number must be in MSISDN format. Check format here. |
| INVALID_TEXT | The field was empty or is corrupt. |
| INVALID_DATETIME | The format we were expecting was: YYYY-MM-DD HH:MM:SS |
| NOT_ENOUGH_BALANCE | Your account has no funds to process this request, add credits to your account and try again. |
| LIMIT_EXCEEDED | Your request has exceeded the maximum of 1000 sms requests per batch. |
SPECIAL LONG CHARACTERS
There are 9 special characters that are counted as 2 individual characters when GSM encoded. This could result in a message becoming longer and therefore being concatenated.The following table identifies these characters.
| Symbol | Name | Symbol | Name |
| [ | Open square | | | Vertical bar |
| \ | Backslash | } | Right brace |
| ] | Close square | ~ | Tilde |
| ^ | Caret | € | Euro symbol |
| { | Left brace |
CONCATENATED GSM MESSAGES
Also referred to as a long message, multipart message or extended message, a concatenatedmessage is formed from several standard SMS containing a 7 byte concatenation header at the beginning of each one. Since this 7 byte header is within the message, it reduces the total size of each SMS to 153 characters each. The table below shows the maximum message length per number of SMS used for plain 7-bit messages. If you want to send a concatenated message, don’t forget you must set the parameter "concat" to value 1.
| Number of SMS | Maximum Message Length |
| 1 | 160 characters. |
| 2 | 306 characters. |
| 3 | 459 characters. |
| 4 | 612 characters. |
| 5 | 765 characters. |
| 6 | 918 characters. |
| 7 | 1071 characters. |
| 8 | 1224 characters. |
GSM ENCODING
According to GSM specification, a standard SMS message can contain up to 140 bytes of data (payload). Standard latin (ISO-8859-1) character encoding represents a single character using 1 byte, which is 8 bits. Therefore, the maximum number of latin 1 characters that could be included in an sms is 140. GSM encoding represents characters using 7 bits instead of 8. This therefore provides a maximum of 160 characters per SMS. (140 * 8 bits) / 7 bits = 160 This effectively halves the number of characters that the GSM character set can support, compared to ISO-8859-1. In order to include common characters that are usually represented using the 8th bit, these characters as well as other symbol characters must be re-mapped to a combination of lower bits. These re-mapped characters are often referred to as special characters. This re-mapping, in combination with packing 7-bit characters into 8- bit bytes is called GSM Encoding.
NOTE The below table lists the 7-bit default alphabet as specified by GSM 03.38
| Hex | Character name | Character | ISO-8859-1 Hex |
| 0x00 | COMMERCIAL AT | @ | 40 |
| 0x01 | POUND SIGN | £ | A3 |
| 0x02 | DOLLAR SIGN | $ | 24 |
| 0x03 | YEN SIGN | ¥ | A5 |
| 0x04 | LATIN SMALL LETTER E WITH GRAVE | è | E8 |
| 0x05 | LATIN SMALL LETTER E WITH ACUTE | é | E9 |
| 0x06 | LATIN SMALL LETTER U WITH GRAVE | ù | F9 |
| 0x07 | LATIN SMALL LETTER I WITH GRAVE | ì | EC |
| 0x08 | LATIN SMALL LETTER O WITH GRAVE | ò | F2 |
| 0x09 | LATIN SMALL LETTER C WITH CEDILLA (casechanged) | Ç | C7 |
| 0x0A | Line Feed | A | |
| 0x0B | LATIN CAPITAL LETTER O WITH STROKE | Ø | D8 |
| 0x0C | LATIN SMALL LETTER O WITH STROKE | ø | F8 |
| 0x0D | Carriage Return | D | |
| 0x0E | LATIN CAPITAL LETTER A WITH RING ABOVE | Å | C5 |
| 0x0F | LATIN SMALL LETTER A WITH RING ABOVE | å | E5 |
| 0x10 | GREEK CAPITAL LETTER | Δ | |
| 0x11 | LOW LINE | _ | 5F |
| 0x12 | GREEK CAPITAL LETTER | Φ | |
| 0x13 | GREEK CAPITAL LETTER | Γ | |
| 0x14 | GREEK CAPITAL LETTER | Λ | |
| 0x15 | GREEK CAPITAL LETTER | Ω | |
| 0x16 | GREEK CAPITAL LETTER | Π | |
| 0x17 | GREEK CAPITAL LETTER | Ψ | |
| 0x18 | GREEK CAPITAL LETTER | Σ | |
| 0x19 | GREEK CAPITAL LETTER | Θ | |
| 0x1A | GREEK CAPITAL LETTER | Ξ | |
| 0x1B | ESCAPE TO EXTENSION | ||
| 0x1B0A | FORM FEED | 12 | |
| 0x1B14 | CIRCUMFLEX ACCENT | ^ | 5E |
| 0x1B28 | LEFT CURLY BRACKET | { | 7B |
| 0x1B29 | RIGHT CURLY BRACKET | } | 7D |
| 0x1B2F | REVERSE SOLIDUS (BACKSLASH) | \ | 5C |
| 0x1B3C | LEFT SQUARE BRACKET | [ | 5B |
| 0x1B3D | TILDE | ~ | 7E |
| 0x1B3E | RIGHT SQUARE BRACKET | ] | 5D |
| 0x1B40 | VERTICAL BAR | | | 7C |
| 0x1B65 | EURO SIGN | € | A4 (ISO-8859-15) |
| 0x1C | LATIN CAPITAL LETTER AE | Æ | C6 |
| 0x1D | LATIN SMALL LETTER AE | æ | E6 |
| 0x1E | LATIN SMALL LETTER SHARP S (German) | ß | DF |
| 0x1F | LATIN CAPITAL LETTER E WITH ACUTE | É | C9 |
| 0x20 | SPACE | 20 | |
| 0x21 | EXCLAMATION MARK | ! | 21 |
| 0x22 | QUOTATION MARK | " | 22 |
| 0x23 | NUMBER SIGN | # | 23 |
| 0x25 | PERCENT SIGN | % | 25 |
| 0x26 | AMPERSAND | & | 26 |
| 0x27 | APOSTROPHE | 27 | |
| 0x28 | LEFT PARENTHESIS | ( | 28 |
| 0x29 | RIGHT PARENTHESIS | ) | 29 |
| 0x2A | ASTERISK | * | 2A |
| 0x2B | PLUS SIGN | + | 2B |
| 0x2C | COMMA | , | 2C |
| 0x2D | HYPHEN-MINUS | - | 2D |
| 0x2E | FULL STOP | . | 2E |
