Diferencia entre revisiones de «API SMS Gigas»
(→ERRORS) |
|||
Línea 5781: | Línea 5781: | ||
| Service temporarily unavailable, try again later. | | Service temporarily unavailable, try again later. | ||
|} | |} | ||
− | |||
− |
Revisión del 05:10 4 dic 2021
Contenido
- 1 GETTING STARTED
- 2 SEND SMS
- 3 GET REPORTS
- 4 SEND SMS LANDING
- 5 GET REPORTS (SMS LANDING)
- 6 SEND SMS SURVEY
- 7 GET REPORTS (SMS SURVEY)
- 8 SEND SMS LINK
- 9 GET REPORTS (SMS LINK)
- 10 RECEIVE SMS
- 11 HLR SERVICE (LOOKUP)
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", "link":"https://www.ebay.es", "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John! See our new offers only available for you: {LINK}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria! See our new offers only available for you: {LINK}", "custom":"MyMsgID-12345", "send_at":"2018-02-18 17:30:00" } ] }
PHP
$request = '{ "api_key":"399d2b438a53ebed3db8a7d52107f846", "report_url":"http://yourserver.com/callback/script", "link":"https://www.ebay.es", "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John! See our new offers only available for you: {LINK}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria! See our new offers only available for you: {LINK}", "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-link'); 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-link"); StringEntity params = new StringEntity( "{" + " \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," + " \"report_url\":\"http://yourserver.com/callback/script\"," + " \"link\":\"https://ebay.es\"," + " \"concat\":1," + " \"messages\":[" + " {" + " \"from\":\"GOOD PIZZA\"," + " \"to\":\"34666666111\"," + " \"text\":\"Hi John! See our new offers only available for you: {LINK}\"," + " \"send_at\":\"2018-02-18 17:30:00\""+ " }," + " {" + " \"from\":\"GOOD PIZZA\"," + " \"to\":\"34666666112\"," + " \"text\":\"Hi Maria! See our new offers only available for you: {LINK}\"," + " \"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);
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 | 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 |
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 |
0x2F | SOLIDUS (SLASH) | / | 2F |
0x30 | DIGIT ZERO | 0 | 30 |
0x31 | DIGIT ONE | 1 | 31 |
0x32 | DIGIT TWO | 2 | 32 |
0x33 | DIGIT THREE | 3 | 33 |
0x34 | DIGIT FOUR | 4 | 34 |
0x35 | DIGIT FIVE | 5 | 35 |
0x36 | DIGIT SIX | 6 | 36 |
0x37 | DIGIT SEVEN | 7 | 37 |
0x38 | DIGIT EIGHT | 8 | 38 |
0x39 | DIGIT NINE | 9 | 39 |
0x3A | COLON | : | 3A |
0x3B | SEMICOLON | ; | 3B |
0x3C | LESS-THAN SIGN | < | 3C |
0x3D | EQUALS SIGN | = | 3D |
0x3E | GREATER-THAN SIGN | > | 3E |
0x3F | QUESTION MARK | ? | 3F |
0x40 | INVERTED EXCLAMATION MARK | ¡ | A1 |
0x41 | LATIN CAPITAL LETTER A | A | 41 |
0x42 | LATIN CAPITAL LETTER B | B | 42 |
0x43 | LATIN CAPITAL LETTER C | C | 43 |
0x44 | LATIN CAPITAL LETTER D | D | 44 |
0x45 | LATIN CAPITAL LETTER E | E | 45 |
0x46 | LATIN CAPITAL LETTER F | F | 46 |
0x47 | LATIN CAPITAL LETTER G | G | 47 |
0x48 | LATIN CAPITAL LETTER H | H | 48 |
0x49 | LATIN CAPITAL LETTER I | I | 49 |
0x4A | LATIN CAPITAL LETTER J | J | 4A |
0x4B | LATIN CAPITAL LETTER K | K | 4B |
0x4C | LATIN CAPITAL LETTER L | L | 4C |
0x4D | LATIN CAPITAL LETTER M | M | 4D |
0x4E | LATIN CAPITAL LETTER N | N | 4E |
0x4F | LATIN CAPITAL LETTER O | O | 4F |
0x50 | LATIN CAPITAL LETTER P | P | 50 |
0x51 | LATIN CAPITAL LETTER Q | Q | 51 |
0x52 | LATIN CAPITAL LETTER R | R | 52 |
0x53 | LATIN CAPITAL LETTER S | S | 53 |
0x54 | LATIN CAPITAL LETTER T | T | 54 |
0x55 | LATIN CAPITAL LETTER U | U | 55 |
0x56 | LATIN CAPITAL LETTER V | V | 56 |
0x57 | LATIN CAPITAL LETTER W | W | 57 |
0x58 | LATIN CAPITAL LETTER X | X | 58 |
0x59 | LATIN CAPITAL LETTER Y | Y | 59 |
0x5A | LATIN CAPITAL LETTER Z | Z | 5A |
0x5B | LATIN CAPITAL LETTER A WITH DIAERESIS | Ä | C4 |
0x5C | LATIN CAPITAL LETTER O WITH DIAERESIS | Ö | D6 |
0x5D | LATIN CAPITAL LETTER N WITH TILDE | Ñ | D1 |
0x5E | LATIN CAPITAL LETTER U WITH DIAERESIS | Ü | DC |
0x5F | SECTION SIGN | § | A7 |
0x60 | INVERTED QUESTION MARK | ¿ | BF |
0x61 | LATIN SMALL LETTER A | a | 61 |
0x62 | LATIN SMALL LETTER B | b | 62 |
0x63 | LATIN SMALL LETTER C | c | 63 |
0x64 | LATIN SMALL LETTER D | d | 64 |
0x65 | LATIN SMALL LETTER E | e | 65 |
0x66 | LATIN SMALL LETTER F | f | 66 |
0x67 | LATIN SMALL LETTER G | g | 67 |
0x68 | LATIN SMALL LETTER H | h | 68 |
0x69 | LATIN SMALL LETTER I | i | 69 |
0x6A L | ATIN SMALL LETTER J | j | 6A |
0x6B | LATIN SMALL LETTER K | k | 6B |
0x6C | LATIN SMALL LETTER L | l | 6C |
0x6D | LATIN SMALL LETTER M | m | 6D |
0x6E | LATIN SMALL LETTER N | n | 6E |
0x6F | LATIN SMALL LETTER O | o | 6F |
0x70 | LATIN SMALL LETTER P | p | 70 |
0x71 | LATIN SMALL LETTER Q | q | 71 |
0x72 | LATIN SMALL LETTER R | r | 72 |
0x73 | LATIN SMALL LETTER S | s | 73 |
0x74 | LATIN SMALL LETTER T | t | 74 |
0x75 | LATIN SMALL LETTER U | u | 75 |
0x76 | LATIN SMALL LETTER V | v | 76 |
0x77 | LATIN SMALL LETTER W | w | 77 |
0x78 | LATIN SMALL LETTER X | x | 78 |
0x79 | LATIN SMALL LETTER Y | y | 79 |
0x7A | LATIN SMALL LETTER Z | z | 7A |
0x7B | LATIN SMALL LETTER A WITH DIAERESIS | ä | E4 |
0x7C | LATIN SMALL LETTER O WITH DIAERESIS | ö | F6 |
0x7D | LATIN SMALL LETTER N WITH TILDE | ñ | F1 |
0x7E | LATIN SMALL LETTER U WITH DIAERESIS | ü | FC |
0x7F | LATIN SMALL LETTER A WITH GRAVE | à | E0 |
UCS2 ENCODING
UCS2 is the Unicode format required for SMS, as opposed to the later format UTF-16. Since each UCS2 character requires 2 bytes, the SMS message length is reduced to 70 characters: 140 bytes / 2 bytes = 70 characters. You must also set the correct Data Coding Scheme value, 0 x 08 or 8 in the case of UCS2. UCS2 encoding allows the use of emoticons in SMS and these are treated as characters so you can write it in your SMS as any other character. Unicode messages can be concatenated. The concatenation headers reduce the characters available for content as follows:
Number of SMS | Maximum Message Length |
1 | 70 characters. |
2 | 134 characters. |
3 | 201 characters. |
4 | 268 characters. |
5 | 335 characters. |
6 | 402 characters. |
7 | 469 characters. |
8 | 536 characters. |
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 |
0x2F | SOLIDUS (SLASH) | / | 2F |
0x30 | DIGIT ZERO | 0 | 30 |
0x31 | DIGIT ONE | 1 | 31 |
0x32 | DIGIT TWO | 2 | 32 |
0x33 | DIGIT THREE | 3 | 33 |
0x34 | DIGIT FOUR | 4 | 34 |
0x35 | DIGIT FIVE | 5 | 35 |
0x36 | DIGIT SIX | 6 | 36 |
0x37 | DIGIT SEVEN | 7 | 37 |
0x38 | DIGIT EIGHT | 8 | 38 |
0x39 | DIGIT NINE | 9 | 39 |
0x3A | COLON | : | 3A |
0x3B | SEMICOLON | ; | 3B |
0x3C | LESS-THAN SIGN | < | 3C |
0x3D | EQUALS SIGN | = | 3D |
0x3E | GREATER-THAN SIGN | > | 3E |
0x3F | QUESTION MARK | ? | 3F |
0x40 | INVERTED EXCLAMATION MARK | ¡ | A1 |
0x41 | LATIN CAPITAL LETTER A | A | 41 |
0x42 | LATIN CAPITAL LETTER B | B | 42 |
0x43 | LATIN CAPITAL LETTER C | C | 43 |
0x44 | LATIN CAPITAL LETTER D | D | 44 |
0x45 | LATIN CAPITAL LETTER E | E | 45 |
0x46 | LATIN CAPITAL LETTER F | F | 46 |
0x47 | LATIN CAPITAL LETTER G | G | 47 |
0x48 | LATIN CAPITAL LETTER H | H | 48 |
0x49 | LATIN CAPITAL LETTER I | I | 49 |
0x4A | LATIN CAPITAL LETTER J | J | 4A |
0x4B | LATIN CAPITAL LETTER K | K | 4B |
0x4C | LATIN CAPITAL LETTER L | L | 4C |
0x4D | LATIN CAPITAL LETTER M | M | 4D |
0x4E | LATIN CAPITAL LETTER N | N | 4E |
0x4F | LATIN CAPITAL LETTER O | O | 4F |
0x50 | LATIN CAPITAL LETTER P | P | 50 |
0x51 | LATIN CAPITAL LETTER Q | Q | 51 |
0x52 | LATIN CAPITAL LETTER R | R | 52 |
0x53 | LATIN CAPITAL LETTER S | S | 53 |
0x54 | LATIN CAPITAL LETTER T | T | 54 |
0x55 | LATIN CAPITAL LETTER U | U | 55 |
0x56 | LATIN CAPITAL LETTER V | V | 56 |
0x57 | LATIN CAPITAL LETTER W | W | 57 |
0x58 | LATIN CAPITAL LETTER X | X | 58 |
0x59 | LATIN CAPITAL LETTER Y | Y | 59 |
0x5A | LATIN CAPITAL LETTER Z | Z | 5A |
0x5B | LATIN CAPITAL LETTER A WITH DIAERESIS | Ä | C4 |
0x5C | LATIN CAPITAL LETTER O WITH DIAERESIS | Ö | D6 |
0x5D | LATIN CAPITAL LETTER N WITH TILDE | Ñ | D1 |
0x5E | LATIN CAPITAL LETTER U WITH DIAERESIS | Ü | DC |
0x5F | SECTION SIGN | § | A7 |
0x60 | INVERTED QUESTION MARK | ¿ | BF |
0x61 | LATIN SMALL LETTER A | a | 61 |
0x62 | LATIN SMALL LETTER B | b | 62 |
0x63 | LATIN SMALL LETTER C | c | 63 |
0x64 | LATIN SMALL LETTER D | d | 64 |
0x65 | LATIN SMALL LETTER E | e | 65 |
0x66 | LATIN SMALL LETTER F | f | 66 |
0x67 | LATIN SMALL LETTER G | g | 67 |
0x68 | LATIN SMALL LETTER H | h | 68 |
0x69 | LATIN SMALL LETTER I | i | 69 |
0x6A L | ATIN SMALL LETTER J | j | 6A |
0x6B | LATIN SMALL LETTER K | k | 6B |
0x6C | LATIN SMALL LETTER L | l | 6C |
0x6D | LATIN SMALL LETTER M | m | 6D |
0x6E | LATIN SMALL LETTER N | n | 6E |
0x6F | LATIN SMALL LETTER O | o | 6F |
0x70 | LATIN SMALL LETTER P | p | 70 |
0x71 | LATIN SMALL LETTER Q | q | 71 |
0x72 | LATIN SMALL LETTER R | r | 72 |
0x73 | LATIN SMALL LETTER S | s | 73 |
0x74 | LATIN SMALL LETTER T | t | 74 |
0x75 | LATIN SMALL LETTER U | u | 75 |
0x76 | LATIN SMALL LETTER V | v | 76 |
0x77 | LATIN SMALL LETTER W | w | 77 |
0x78 | LATIN SMALL LETTER X | x | 78 |
0x79 | LATIN SMALL LETTER Y | y | 79 |
0x7A | LATIN SMALL LETTER Z | z | 7A |
0x7B | LATIN SMALL LETTER A WITH DIAERESIS | ä | E4 |
0x7C | LATIN SMALL LETTER O WITH DIAERESIS | ö | F6 |
0x7D | LATIN SMALL LETTER N WITH TILDE | ñ | F1 |
0x7E | LATIN SMALL LETTER U WITH DIAERESIS | ü | FC |
0x7F | LATIN SMALL LETTER A WITH GRAVE | à | E0 |
UCS2 ENCODING
UCS2 is the Unicode format required for SMS, as opposed to the later format UTF-16. Since each UCS2 character requires 2 bytes, the SMS message length is reduced to 70 characters: 140 bytes / 2 bytes = 70 characters. You must also set the correct Data Coding Scheme value, 0 x 08 or 8 in the case of UCS2. UCS2 encoding allows the use of emoticons in SMS and these are treated as characters so you can write it in your SMS as any other character. Unicode messages can be concatenated. The concatenation headers reduce the characters available for content as follows:
Number of SMS | Maximum Message Length |
1 | 70 characters. |
2 | 134 characters. |
3 | 201 characters. |
4 | 268 characters. |
5 | 335 characters. |
6 | 402 characters. |
7 | 469 characters. |
8 | 536 characters. |
GET REPORTS
Once you have submitted a message and the message has been delivered to the handset, the operator responds with a delivery report. It could take seconds or 48 hours to receive the delivery report from the operator, depending on the network.
NOTE To use this method you need to specify the url callback in the param "report_url" when you send the message.
REQUEST TO YOUR SERVER
When we receive delivery reports we will send to your server instantly in batches, so each request can contain up to 1,000 delivery reports in a JSON format.
Parameters
Array of delivery reports founds.
|
JSON
[ { "sms_id":"034d2acec0eb44af842de6a00bf4d934", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774843", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:50" }, { "sms_id":"034d2acec0eb44af842de6a00bf4d892", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774849", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:49" } ]
- Two delivery reports sent
STATUS VALUES
DELIVRD | Message delivered to destination. |
ACCEPTD | Message is in accepted state, this state is temporary. |
EXPIRED | Message validity period has expired, the expiration of a message is 48 hours if not specified. |
DELETED | Message has been deleted due to the operator's reasons. |
UNDELIV | Message wasn't delivered by SMSC, expiration, not reachable, operator problems, portability... |
UNKNOWN | Message is in unknown state, the operator is trying, maybe the cellphone is turned off. |
REJECTD | Message is in rejected state, the destination or the operator rejected the message. |
YOUR SERVER RESPONSE
In order to accept the delivery reports, your server must respond with HTTP status code 200 OK. If you cannot process the data at this time, for example, due to a database problem, you can return any other error such as status code 500. If a status code other than 200 is received, the request will be retried every 30 minutes for a period of 6 hours.
SEND SMS LANDING
With this method you can send bulk SMS Landing easily. This method has been extremely optimized to send more than 500.000 SMS in less than one hour. To send SMS Landing via API, you must first have it created in your account in your user panel, since you will need `landing_id` to send it.
ENDPOINT
https://api.gateway360.com/api/3.0/sms/send-landing
REQUEST
Parameters
api_key | Your API Key. | ||||||||||
messages | Array of messages you want to send.
| ||||||||||
landing_id | ID of the landing template created in your account. | ||||||||||
campaign_name | Name of the campaign in case your want to group more than one SMS in a unique campaign to see it in your panel (otherway no one campaign will be created). | ||||||||||
report_url | URL where you want to receive the delivery report (DLR) and the events of the landing as your client open it or click in some link or action. | ||||||||||
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", "landing_id":2749, "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John! See our new offers only available for you: {LANDING}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria! See our new offers only available for you: {LANDING}", "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", "landing_id":2749, "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John! See our new offers only available for you: {LANDING}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria! See our new offers only available for you: {LANDING}", "custom":"MyMsgID-12345", "send_at":"2018-02-18 17:30:00" } ] }' https://api.gateway360.com/api/3.0/sms/send-landing
PHP
$request = '{ "api_key":"399d2b438a53ebed3db8a7d52107f846", "report_url":"http://yourserver.com/callback/script", "landing_id":2749, "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John! See our new offers only available for you: {LANDING}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria! See our new offers only available for you: {LANDING}", "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-landing'); 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-landing"); StringEntity params = new StringEntity( "{" + " \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," + " \"report_url\":\"http://yourserver.com/callback/script\"," + " \"landing_id\":2749," + " \"concat\":1," + " \"messages\":[" + " {" + " \"from\":\"GOOD PIZZA\"," + " \"to\":\"34666666111\"," + " \"text\":\"Hi John! See our new offers only available for you: {LANDING}\"," + " \"send_at\":\"2018-02-18 17:30:00\""+ " }," + " {" + " \"from\":\"GOOD PIZZA\"," + " \"to\":\"34666666112\"," + " \"text\":\"Hi Maria! See our new offers only available for you: {LANDING}\"," + " \"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);
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
GET REPORTS (SMS LANDING)
Once you have submitted a message and the message has been delivered to the handset, the operator responds with a delivery report. It could take seconds or 48 hours to receive the delivery report from the operator, depending on the network. In addition, SMS Landing can send you reports whenever your client will open the landing page and when he click in any link, map or action button of the landing page.
NOTE To use this method you need to specify the url callback in the param "report_url" when you send the message.
REQUEST TO YOUR SERVER
When we receive delivery reports we will send to your server instantly in batches, so each request can contain up to 1,000 delivery reports in a JSON format.
DLR REQUEST
Parameters
Array of delivery reports founds.
|
JSON
[ { "sms_id":"034d2acec0eb44af842de6a00bf4d934", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774843", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:50" }, { "sms_id":"034d2acec0eb44af842de6a00bf4d892", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774849", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:49" } ]
- Two delivery reports sent
STATUS VALUES
DELIVRD | Message delivered to destination. |
ACCEPTD | Message is in accepted state, this state is temporary. |
EXPIRED | Message validity period has expired, the expiration of a message is 48 hours if not specified. |
DELETED | Message has been deleted due to the operator's reasons. |
UNDELIV | Message wasn't delivered by SMSC, expiration, not reachable, operator problems, portability... |
UNKNOWN | Message is in unknown state, the operator is trying, maybe the cellphone is turned off. |
REJECTD | Message is in rejected state, the destination or the operator rejected the message. |
LANDING OPEN REQUEST
Parameters
sms_id | The message id. |
msisdn | The destination number of the message you sent and who has opened the landing page. |
timestamp | The datetime when your client has opened the landing in the format: YYYY-MM-DD HH:MM:SS. |
ip | The ip from the landing page has been opened. |
city | The city from the landing page has been opened. |
device | The device OS (Operative System) from the landing page has been opened. |
user_agent | The user_agent of the device from the landing page has been opened. |
brand | The brand of the device from the landing page has been opened. |
model | The model of the device from the landing page has been opened. |
full_name | The model full name of the device from the landing page has been opened. |
marketing_name | The marketing name of the device from the landing page has been opened. |
JSON
{ "034d2acec0eb44af842de6a00bf4d934": { "msisdn":"34666666666", "timestamp":"2017-08-07 17:05:35", "ip":"8.8.8.8", "city":"Madrid", "device":"Android", "user_agent":"Mozilla/5.0 (Linux; Android 7.0; SAMSUNG SM-G950F Build/NRD90M) AppleWebKit/537.36", "brand":"Samsung", "model":"Galaxy S8", "full_name":"Samsung Galaxy S8", "marketing_name":"SAMSUNG SM-G950F" } }
YOUR SERVER RESPONSE
In order to accept the delivery reports, your server must respond with HTTP status code 200 OK. If you cannot process the data at this time, for example, due to a database problem, you can return any other error such as status code 500. If a status code other than 200 is received, the request will be retried every 30 minutes for a period of 6 hours.
LANDING CLICK REQUEST
Parameters
sms_id | The message id. |
msisdn | The destination number of the message you sent and who has opened the landing page. |
timestamp | The datetime when your client has clicked the link in the format: YYYY-MM-DD HH:MM:SS. |
click | The link (button, map, image...) which your client have clicked. |
JSON
{ "034d2acec0eb44af842de6a00bf4d934": { "msisdn":"34666666666", "timestamp":"2017-08-07 17:06:15", "click":"https://yourpage.com/more-information", } }
YOUR SERVER RESPONSE
In order to accept the delivery reports, your server must respond with HTTP status code 200 OK. If you cannot process the data at this time, for example, due to a database problem, you can return any other error such as status code 500. If a status code other than 200 is received, the request will be retried every 30 minutes for a period of 6 hours.
SEND SMS SURVEY
With this method you can send bulk SMS Survey easily. This method has been extremely optimized to send more than 500.000 SMS in less than one hour. To send SMS Survey via API, you must first have it created in your account in your user panel, since you will need `survey_id` to send it.
ENDPOINT
https://api.gateway360.com/api/3.0/sms/send-survey
REQUEST
Parameters
api_key |
Your API Key. | ||||||||||
messages |
Array of messages you want to send.
| ||||||||||
survey_id |
ID of the survey template created in your account. | ||||||||||
campaign_name | Name of the campaign in case your want to group more than one SMS in a unique campaign to see it in your panel (otherway no one campaign will be created). | ||||||||||
report_url | URL where you want to receive the delivery report (DLR) and the events of the survey as your client open it or complete it. | ||||||||||
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", "survey_id":573, "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John, thanks for your order! Please, complete this survey to improve our service: {SURVEY}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria, thanks for your order! Please, complete this survey to improve our service: {SURVEY}", "custom":"MyMsgID-12345", "send_at":"2018-02-18 17:30:00" } ] }
PHP
$request = '{ "api_key":"399d2b438a53ebed3db8a7d52107f846", "report_url":"http://yourserver.com/callback/script", "survey_id":573, "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John, thanks for your order! Please, complete this survey to improve our service: {SURVEY}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria, thanks for your order! Please, complete this survey to improve our service: {SURVEY}", "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-survey'); 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-survey"); StringEntity params = new StringEntity( "{" + " \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," + " \"report_url\":\"http://yourserver.com/callback/script\"," + " \"survey_id\":573," + " \"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);
RESPONSE
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 | 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 |
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 |
0x2F | SOLIDUS (SLASH) | / | 2F |
0x30 | DIGIT ZERO | 0 | 30 |
0x31 | DIGIT ONE | 1 | 31 |
0x32 | DIGIT TWO | 2 | 32 |
0x33 | DIGIT THREE | 3 | 33 |
0x34 | DIGIT FOUR | 4 | 34 |
0x35 | DIGIT FIVE | 5 | 35 |
0x36 | DIGIT SIX | 6 | 36 |
0x37 | DIGIT SEVEN | 7 | 37 |
0x38 | DIGIT EIGHT | 8 | 38 |
0x39 | DIGIT NINE | 9 | 39 |
0x3A | COLON | : | 3A |
0x3B | SEMICOLON | ; | 3B |
0x3C | LESS-THAN SIGN | < | 3C |
0x3D | EQUALS SIGN | = | 3D |
0x3E | GREATER-THAN SIGN | > | 3E |
0x3F | QUESTION MARK | ? | 3F |
0x40 | INVERTED EXCLAMATION MARK | ¡ | A1 |
0x41 | LATIN CAPITAL LETTER A | A | 41 |
0x42 | LATIN CAPITAL LETTER B | B | 42 |
0x43 | LATIN CAPITAL LETTER C | C | 43 |
0x44 | LATIN CAPITAL LETTER D | D | 44 |
0x45 | LATIN CAPITAL LETTER E | E | 45 |
0x46 | LATIN CAPITAL LETTER F | F | 46 |
0x47 | LATIN CAPITAL LETTER G | G | 47 |
0x48 | LATIN CAPITAL LETTER H | H | 48 |
0x49 | LATIN CAPITAL LETTER I | I | 49 |
0x4A | LATIN CAPITAL LETTER J | J | 4A |
0x4B | LATIN CAPITAL LETTER K | K | 4B |
0x4C | LATIN CAPITAL LETTER L | L | 4C |
0x4D | LATIN CAPITAL LETTER M | M | 4D |
0x4E | LATIN CAPITAL LETTER N | N | 4E |
0x4F | LATIN CAPITAL LETTER O | O | 4F |
0x50 | LATIN CAPITAL LETTER P | P | 50 |
0x51 | LATIN CAPITAL LETTER Q | Q | 51 |
0x52 | LATIN CAPITAL LETTER R | R | 52 |
0x53 | LATIN CAPITAL LETTER S | S | 53 |
0x54 | LATIN CAPITAL LETTER T | T | 54 |
0x55 | LATIN CAPITAL LETTER U | U | 55 |
0x56 | LATIN CAPITAL LETTER V | V | 56 |
0x57 | LATIN CAPITAL LETTER W | W | 57 |
0x58 | LATIN CAPITAL LETTER X | X | 58 |
0x59 | LATIN CAPITAL LETTER Y | Y | 59 |
0x5A | LATIN CAPITAL LETTER Z | Z | 5A |
0x5B | LATIN CAPITAL LETTER A WITH DIAERESIS | Ä | C4 |
0x5C | LATIN CAPITAL LETTER O WITH DIAERESIS | Ö | D6 |
0x5D | LATIN CAPITAL LETTER N WITH TILDE | Ñ | D1 |
0x5E | LATIN CAPITAL LETTER U WITH DIAERESIS | Ü | DC |
0x5F | SECTION SIGN | § | A7 |
0x60 | INVERTED QUESTION MARK | ¿ | BF |
0x61 | LATIN SMALL LETTER A | a | 61 |
0x62 | LATIN SMALL LETTER B | b | 62 |
0x63 | LATIN SMALL LETTER C | c | 63 |
0x64 | LATIN SMALL LETTER D | d | 64 |
0x65 | LATIN SMALL LETTER E | e | 65 |
0x66 | LATIN SMALL LETTER F | f | 66 |
0x67 | LATIN SMALL LETTER G | g | 67 |
0x68 | LATIN SMALL LETTER H | h | 68 |
0x69 | LATIN SMALL LETTER I | i | 69 |
0x6A L | ATIN SMALL LETTER J | j | 6A |
0x6B | LATIN SMALL LETTER K | k | 6B |
0x6C | LATIN SMALL LETTER L | l | 6C |
0x6D | LATIN SMALL LETTER M | m | 6D |
0x6E | LATIN SMALL LETTER N | n | 6E |
0x6F | LATIN SMALL LETTER O | o | 6F |
0x70 | LATIN SMALL LETTER P | p | 70 |
0x71 | LATIN SMALL LETTER Q | q | 71 |
0x72 | LATIN SMALL LETTER R | r | 72 |
0x73 | LATIN SMALL LETTER S | s | 73 |
0x74 | LATIN SMALL LETTER T | t | 74 |
0x75 | LATIN SMALL LETTER U | u | 75 |
0x76 | LATIN SMALL LETTER V | v | 76 |
0x77 | LATIN SMALL LETTER W | w | 77 |
0x78 | LATIN SMALL LETTER X | x | 78 |
0x79 | LATIN SMALL LETTER Y | y | 79 |
0x7A | LATIN SMALL LETTER Z | z | 7A |
0x7B | LATIN SMALL LETTER A WITH DIAERESIS | ä | E4 |
0x7C | LATIN SMALL LETTER O WITH DIAERESIS | ö | F6 |
0x7D | LATIN SMALL LETTER N WITH TILDE | ñ | F1 |
0x7E | LATIN SMALL LETTER U WITH DIAERESIS | ü | FC |
0x7F | LATIN SMALL LETTER A WITH GRAVE | à | E0 |
UCS2 ENCODING
UCS2 is the Unicode format required for SMS, as opposed to the later format UTF-16. Since each UCS2 character requires 2 bytes, the SMS message length is reduced to 70 characters: 140 bytes / 2 bytes = 70 characters. You must also set the correct Data Coding Scheme value, 0 x 08 or 8 in the case of UCS2. UCS2 encoding allows the use of emoticons in SMS and these are treated as characters so you can write it in your SMS as any other character. Unicode messages can be concatenated. The concatenation headers reduce the characters available for content as follows:
Number of SMS | Maximum Message Length |
1 | 70 characters. |
2 | 134 characters. |
3 | 201 characters. |
4 | 268 characters. |
5 | 335 characters. |
6 | 402 characters. |
7 | 469 characters. |
8 | 536 characters. |
GET REPORTS (SMS SURVEY)
Once you have submitted a message and the message has been delivered to the handset, the operator responds with a delivery report. It could take seconds or 48 hours to receive the delivery report from the operator, depending on the network. In addition, SMS Landing can send you reports whenever your client will open the landing page and when he click in any link, map or action button of the landing page.
NOTE To use this method you need to specify the url callback in the param "report_url" when you send the message.
REQUEST TO YOUR SERVER
When we receive delivery reports we will send to your server instantly in batches, so each request can contain up to 1,000 delivery reports in a JSON format.
DLR REQUEST
Parameters
Array of delivery reports founds.
|
JSON
[ { "sms_id":"034d2acec0eb44af842de6a00bf4d934", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774843", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:50" }, { "sms_id":"034d2acec0eb44af842de6a00bf4d892", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774849", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:49" } ]
- Two delivery reports sent
STATUS VALUES
DELIVRD | Message delivered to destination. |
ACCEPTD | Message is in accepted state, this state is temporary. |
EXPIRED | Message validity period has expired, the expiration of a message is 48 hours if not specified. |
DELETED | Message has been deleted due to the operator's reasons. |
UNDELIV | Message wasn't delivered by SMSC, expiration, not reachable, operator problems, portability... |
UNKNOWN | Message is in unknown state, the operator is trying, maybe the cellphone is turned off. |
REJECTD | Message is in rejected state, the destination or the operator rejected the message. |
SURVEY OPEN REQUEST
Parameters
sms_id | The message id. |
msisdn | The destination number of the message you sent and who has opened the survey page. |
timestamp | The datetime when your client has opened the survey in the format: YYYY-MM-DD HH:MM:SS. |
ip | The ip from the survey page has been opened. |
city | The city from the survey page has been opened. |
device | The device OS (Operative System) from the survey page has been opened. |
user_agent | The user_agent of the device from the survey page has been opened. |
brand | The brand of the device from the survey page has been opened. |
model | The model of the device from the survey page has been opened. |
full_name | The model full name of the device from the survey page has been opened. |
marketing_name | The marketing name of the device from the survey page has been opened. |
JSON
{ "034d2acec0eb44af842de6a00bf4d934": { "msisdn":"34666666666", "timestamp":"2017-08-07 17:05:35", "ip":"8.8.8.8", "city":"Madrid", "device":"Android", "user_agent":"Mozilla/5.0 (Linux; Android 7.0; SAMSUNG SM-G950F Build/NRD90M) AppleWebKit/537.36", "brand":"Samsung", "model":"Galaxy S8", "full_name":"Samsung Galaxy S8", "marketing_name":"SAMSUNG SM-G950F" } }
SURVEY COMPLETED REQUEST
The response obtained in this request will depends of the structure of the survey created in your account and the sequence of those fields will be the same, being this the list of possible fields:
- checkbox-X
- radio-X
- textarea-X
- select-X
- date-X
- time-X
X value corresponds to an identifier of the number of elements of that type, starting at 1
Parameters
sms_id | The message id. |
msisdn | The destination number of the message you sent and who has opened the landing page. |
timestamp | The datetime when your client has completed the survey in the format: YYYY-MM-DD HH:MM:SS. |
response | The objects returned in this parameter will depend on the survey as well as its fields. |
JSON
{ "034d2acec0eb44af842de6a00bf4d934": { "msisdn":"34666666666", "timestamp":"2017-08-07 16:54:53", "response":{ "radio-1": { "type": "radio", "question": "Have you bought in our shop before?", "answers": { "predefined": [ "No" ] } }, "textarea-1": { "type": "textarea", "question": "How did you find the purchase process?", "answers": { "predefined": [ "Really good and simple" ] } }, "radio-2": { "type": "radio", "question": "On a scale from 1 to 10, what score would you give us?", "answers": { "predefined": [ "9" ] } }, "checkbox-1": { "type": "checkbox", "question": "What did you like most about our brand?", "answers": { "predefined": [ "Simplicity", "Price" ], "other": [ "You're awesome!" ] } } } } }
YOUR SERVER RESPONSE
In order to accept the delivery reports, your server must respond with HTTP status code 200 OK. If you cannot process the data at this time, for example, due to a database problem, you can return any other error such as status code 500. If a status code other than 200 is received, the request will be retried every 30 minutes for a period of 6 hours.
SEND SMS LINK
With this method you can send bulk SMS Link 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-link
REQUEST
api_key | Your API Key. | |
messages | Array of messages you want to send. | |
from | Originator address (sender). Up to 15 numeric or 11 alphanumeric characters. All characters non-ASCII will be replaced with its equivalent if exist any (á => a), empty in another case. | |
to | Destination mobile number in international format. Country code must be included.Ex: to=447525812121 when sending to UK. | |
text | Body of the text message including the tag {LINK} (with a maximum length of 459 characters). Ex: "Déjà vu, you can find it and more in our shop: {LINK}" | |
custom | Include any reference string for your reference. Useful for your internal reports. Maximum 32 alphanumeric characters. | |
send_at | When this message should be sent as timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately. | |
link | URL you want to track when your client has click on it to access. | |
campaign_name | Name of the campaign in case your want to group more than one SMS in a unique campaign to see it in your panel (otherway no one campaign will be created). | |
report_url | URL where you want to receive the delivery report (DLR) and the event of the link as your client open it. | |
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. | |
Mandatory | ||
Optional |
{ " api_key ": "399d2b438a53ebed3db8a7d52107f846" , " report_url ": "http://yourserver.com/callback/script" , " link ": "https://www.ebay.es" , " concat ": 1 , " messages ": [ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John! See our new offers only available for you: {LINK }", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria! See our new offers only available for you: {LIN K}", "custom":"MyMsgID-12345", "send_at":"2018-02-18 17:30:00" } ] }
$request = '{ "api_key":"399d2b438a53ebed3db8a7d52107f846", "report_url":"http://yourserver.com/callback/script", "link":"https://www.ebay.es", "concat":1, "messages":[ { "from":"GOOD PIZZA", "to":"34666666111", "text":"Hi John! See our new offers only available for you: {LINK}", "send_at":"2018-02-18 17:30:00" }, { "from":"GOOD PIZZA", "to":"34666666112", "text":"Hi Maria! See our new offers only available for you: {LINK}", "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-link'); 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)); }
/** 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-link"); StringEntity params = new StringEntity( "{" + " \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," + " \"report_url\":\"http://yourserver.com/callback/script\"," + " \"link\":\"https://ebay.es\"," + " \"concat\":1," + " \"messages\":[" + " {" + " \"from\":\"GOOD PIZZA\"," + " \"to\":\"34666666111\"," + " \"text\":\"Hi John! See our new offers only available for you: {LINK}\"," + " \"send_at\":\"2018-02-18 17:30:00\""+ " }," + " {" + " \"from\":\"GOOD PIZZA\"," + " \"to\":\"34666666112\"," + " \"text\":\"Hi Maria! See our new offers only available for you: {LINK}\"," + " \"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);
RESPONSE
status | The sending status of request - either "ok", "error" | |
result | Array of results in the same order you submitted. | |
status | The status of the message - either "ok", "error" | |
sms_id | Operator message id (with a maximum length of 32 characters). This is helpful for delivery reports. | |
custom | Custom field sent in request. | |
error_id | In case the status values "error" this param gives you the error id. | |
error_msg | In case the status values "error" this param has additional information. This param should be use just for debugging. | |
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. |
200 OK
{ "status":"ok", "result":[ { "status":"ok", "sms_id":"1a8940dc7471427db3021cde5b464444", "custom":"test" }, { "status":"ok", "sms_id":"1a8940dc7471427db3021cde5b464481", "custom":"" } ] }
Two messages successfully processed
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 c haracters.", "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.
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
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 | https://jsonlint.com/ |
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 | https://en.wikipedia.org/wiki/MSISDN |
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 concatenated message 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 [https://en.wikipedia.org/wiki/GSM_03.38 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 |
0x2F | SOLIDUS (SLASH) | / | 2F |
0x30 | DIGIT ZERO | 0 | 30 |
0x31 | DIGIT ONE | 1 | 31 |
0x32 | DIGIT TWO | 2 | 32 |
0x33 | DIGIT THREE | 3 | 33 |
0x34 | DIGIT FOUR | 4 | 34 |
0x35 | DIGIT FIVE | 5 | 35 |
0x36 | DIGIT SIX | 6 | 36 |
0x37 | DIGIT SEVEN | 7 | 37 |
0x38 | DIGIT EIGHT | 8 | 38 |
0x39 | DIGIT NINE | 9 | 39 |
0x3A | COLON | : | 3A |
0x3B | SEMICOLON | ; | 3B |
0x3C | LESS-THAN SIGN | < | 3C |
0x3D | EQUALS SIGN | = | 3D |
0x3E | GREATER-THAN SIGN | > | 3E |
0x3F | QUESTION MARK | ? | 3F |
0x40 | INVERTED EXCLAMATION MARK | ¡ | A1 |
0x41 | LATIN CAPITAL LETTER A | A | 41 |
0x42 | LATIN CAPITAL LETTER B | B | 42 |
0x43 | LATIN CAPITAL LETTER C | C | 43 |
0x44 | LATIN CAPITAL LETTER D | D | 44 |
0x45 | LATIN CAPITAL LETTER E | E | 45 |
0x46 | LATIN CAPITAL LETTER F | F | 46 |
0x47 | LATIN CAPITAL LETTER G | G | 47 |
0x48 | LATIN CAPITAL LETTER H | H | 48 |
0x49 | LATIN CAPITAL LETTER I | I | 49 |
0x4A | LATIN CAPITAL LETTER J | J | 4A |
0x4B | LATIN CAPITAL LETTER K | K | 4B |
0x4C | LATIN CAPITAL LETTER L | L | 4C |
0x4D | LATIN CAPITAL LETTER M | M | 4D |
0x4E | LATIN CAPITAL LETTER N | N | 4E |
0x4F | LATIN CAPITAL LETTER O | O | 4F |
0x50 | LATIN CAPITAL LETTER P | P | 50 |
0x51 | LATIN CAPITAL LETTER Q | Q | 51 |
0x52 | LATIN CAPITAL LETTER R | R | 52 |
0x53 | LATIN CAPITAL LETTER S | S | 53 |
0x54 | LATIN CAPITAL LETTER T | T | 54 |
0x55 | LATIN CAPITAL LETTER U | U | 55 |
0x56 | LATIN CAPITAL LETTER V | V | 56 |
0x57 | LATIN CAPITAL LETTER W | W | 57 |
0x58 | LATIN CAPITAL LETTER X | X | 58 |
0x59 | LATIN CAPITAL LETTER Y | Y | 59 |
0x5A | LATIN CAPITAL LETTER Z | Z | 5A |
0x5B | LATIN CAPITAL LETTER A WITH DIAERESIS | Ä | C4 |
0x5C | LATIN CAPITAL LETTER O WITH DIAERESIS | Ö | D6 |
0x5D | LATIN CAPITAL LETTER N WITH TILDE | Ñ | D1 |
0x5E | LATIN CAPITAL LETTER U WITH DIAERESIS | Ü | DC |
0x5F | SECTION SIGN | § | A7 |
0x60 | INVERTED QUESTION MARK | ¿ | BF |
0x61 | LATIN SMALL LETTER A | a | 61 |
0x62 | LATIN SMALL LETTER B | b | 62 |
0x63 | LATIN SMALL LETTER C | c | 63 |
0x64 | LATIN SMALL LETTER D | d | 64 |
0x65 | LATIN SMALL LETTER E | e | 65 |
0x66 | LATIN SMALL LETTER F | f | 66 |
0x67 | LATIN SMALL LETTER G | g | 67 |
0x68 | LATIN SMALL LETTER H | h | 68 |
0x69 | LATIN SMALL LETTER I | i | 69 |
0x6A L | ATIN SMALL LETTER J | j | 6A |
0x6B | LATIN SMALL LETTER K | k | 6B |
0x6C | LATIN SMALL LETTER L | l | 6C |
0x6D | LATIN SMALL LETTER M | m | 6D |
0x6E | LATIN SMALL LETTER N | n | 6E |
0x6F | LATIN SMALL LETTER O | o | 6F |
0x70 | LATIN SMALL LETTER P | p | 70 |
0x71 | LATIN SMALL LETTER Q | q | 71 |
0x72 | LATIN SMALL LETTER R | r | 72 |
0x73 | LATIN SMALL LETTER S | s | 73 |
0x74 | LATIN SMALL LETTER T | t | 74 |
0x75 | LATIN SMALL LETTER U | u | 75 |
0x76 | LATIN SMALL LETTER V | v | 76 |
0x77 | LATIN SMALL LETTER W | w | 77 |
0x78 | LATIN SMALL LETTER X | x | 78 |
0x79 | LATIN SMALL LETTER Y | y | 79 |
0x7A | LATIN SMALL LETTER Z | z | 7A |
0x7B | LATIN SMALL LETTER A WITH DIAERESIS | ä | E4 |
0x7C | LATIN SMALL LETTER O WITH DIAERESIS | ö | F6 |
0x7D | LATIN SMALL LETTER N WITH TILDE | ñ | F1 |
0x7E | LATIN SMALL LETTER U WITH DIAERESIS | ü | FC |
0x7F | LATIN SMALL LETTER A WITH GRAVE | à | E0 |
UCS2 ENCODING
UCS2 is the Unicode format required for SMS, as opposed to the later format UTF-16. Since each UCS2 character requires 2 bytes, the SMS message length is reduced to 70 characters: 140 bytes / 2 bytes = 70 characters. You must also set the correct Data Coding Scheme value, 0 x 08 or 8 in the case of UCS2. UCS2 encoding allows the use of emoticons in SMS and these are treated as characters so you can write it in your SMS as any other character. Unicode messages can be concatenated. The concatenation headers reduce the characters available for content as follows:
Number of SMS | Maximum Message Length |
---|---|
1 | 70 characters. |
2 | 134 characters. |
3 | 201 characters. |
4 | 268 characters. |
5 | 335 characters. |
6 | 402 characters. |
7 | 469 characters. |
8 | 536 characters. |
GET REPORTS (SMS LINK)
Once you have submitted a message and the message has been delivered to the handset, the operator responds with a delivery report. It could take seconds or 48 hours to receive the delivery report from the operator, depending on the network. In addition, SMS Link can send you reports whenever your client will open the URL in your message.
NOTE To use this method you need to specify the url callback in the param "report_url" when you send the message.
REQUEST TO YOUR SERVER
When we receive delivery reports we will send to your server instantly in batches, so each request can contain up to 1,000 delivery reports in a JSON format
DLR REQUEST
sms_id | The message id. |
from | The sender of the message you sent. |
to | The destination number of the message you sent. |
custom | The custom value of the message you sent. |
sms_date | The date & time of the message you sent in the format: YYYY-MM-DD HH:MM:SS |
status | The status of the message, check the following table to see possible values. |
dlr_date | The date & time of the status. |
[ { "sms_id":"034d2acec0eb44af842de6a00bf4d934", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774843", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:50" }, { "sms_id":"034d2acec0eb44af842de6a00bf4d892", "from":"SUPERGOL", "to":"34666666666", "custom":"YourReferenceID-774849", "sms_date":"2015-06-02 01:43:47", "status":"DELIVRD", "dlr_date":"2015-06-02 01:43:49" } ]
Two delivery reports sent
STATUS VALUES
DELIVRD | Message delivered to destination. |
ACCEPTD | Message is in accepted state, this state is temporary. |
EXPIRED | Message validity period has expired, the expiration of a message is 48 hours if not specified. |
DELETED | Message has been deleted due to the operator's reasons. |
UNDELIV | Message wasn't delivered by SMSC, expiration, not reachable, operator problems, portability... |
UNKNOWN | Message is in unknown state, the operator is trying, maybe the cellphone is turned off. |
LINK OPEN REQUEST
sms_id | The message id. |
msisdn | The destination number of the message you sent and who has opened the landing page. |
timestamp | The datetime when your client has clicked the link in the format: YYYY-MM-DD HH:MM:SS. |
ip | The city from the landing page has been opened. |
{ "034d2acec0eb44af842de6a00bf4d934": { "msisdn":"34666666666", "timestamp":"2017-08-07 16:41:57", "ip":"8.8.8.8", } }
YOUR SERVER RESPONSE
In order to accept the delivery reports, your server must respond with HTTP status code 200 OK. If you cannot process the data at this time, for example, due to a database problem, you can return any other error such as status code 500. If a status code other than 200 is received, the request will be retried every 30 minutes for a period of 6 hours.
RECEIVE SMS
To get started the first thing you need to do is buying a virtual number. This you can do in the panel.
NOTE To use this method you need to specify the url callback in your account.
REQUEST TO YOUR SERVER
When we receive sms from the operator we will send it to your server instantly in batches, so each request can contain up to 1,000 messages in a JSON format.
sms_id | The message id. |
from | The sender of the originator. |
to | The destination number, this is your virtual number. |
text | The content of the message. |
sms_date | Date & time when we received the message from the operator, in the format YYYY-MM-DD HH:MM:SS. |
[ { "sms_id":"034d2acec0eb44af842de6a00bf4d934", "from":"34666666666", "to":"34666666667", "text":"Hello 1!", "sms_date":"2015-06-02 01:43:47" }, { "sms_id":"034d2acec0eb44af842de6a00bf4d892", "from":"34666666666", "to":"34666666667", "text":"Hello 2!", "sms_date":"2015-06-02 01:45:03" } ]
Two messages sent to your server
YOUR SERVER RESPONSE
In order to accept the incoming messages, your server must respond with HTTP status code 200 OK. If you cannot process the data at this time, for example, due to a database problem, you can return any other error such as status code 500. If a status code other than 200 is received, the request will be retried every 30 minutes for a period of 6 hours
HLR SERVICE (LOOKUP)
With this method you can verify a mobile number in international format (msisdn). It will return the status of the desired number, including its validity, network and succint portability information. The HLR validation has a cost of 0.005€ per number.
ENDPOINT
https://api.gateway360.com/api/hlr/request
REQUEST
api_key | Your API Key. |
msisdn | A mobile number in msisdn format. |
Mandatory |
{ " api_key ": "399d2b438a53ebed3db8a7d52107f846" , " msisdn ": "34666666667" }
$request = '{ "api_key":"399d2b438a53ebed3db8a7d52107f846", "msisdn":"34666666667" }' ; $headers = array( 'Content-Type: application/json' ); $ch = curl_init( 'https://api.gateway360.com/api/hlr/request' ); 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 )); }
/** 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/hlr/request" ); StringEntity params = new StringEntity( "{" + " \"api_key\":\"399d2b438a53ebed3db8a7d52107f846\"," + " \"msisdn\":\"34666666667\"" + "}" ); request.addHeader( "content-type" , "application/json" ); request.addHeader( "Accept" , "application/json" ); request.setEntity(params); HttpResponse response = httpClient.execute(request);
RESPONSE
status | Status of request - either "ok" or "error" |
msisdn | Requested number. |
success | If the number lookup was successful. True or false. |
mccmnc | Mobile Country Code (first 3 characters) and Mobile Network Code. |
original_network | Mobile network the number belongs to. |
error_id | In case of status being "error", this param will contain the error id. |
error_msg | In case of status being "error", this param will contain additional information. Should only be used for debugging. |
200 OK
{ " status ": "ok" , " result ": { "msisdn":"34666666666", "success":true, "mccmnc":"21403", "original_network":"MNO - Vodafone Espana", "ported":false } }
One number lookup without portability
200 OK
{ " status ": "ok" , " result ": { "msisdn":"34666666666", "success":true, "mccmnc":"21403", "original_network":"MNO - Movistar (Telefonica Moviles Espana)", "ported":true, "ported_network":"MNO - Orange Espana" } }
One number lookup with portability
200 OK
{ " status ": "ok" , " result ": { "msisdn":"34666666665", "success":false } }
One number lookup about a number that is incorrect
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 | https://jsonlint.com/ |
MISSING_PARAMS | Your request is incomplete and missing some mandatory parameters. |
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. |
NOT_ENOUGH_BALANCE | Your account has no funds to process this request, add credits to your account and try again. |
SERVICE_UNAVAILABLE | Service temporarily unavailable, try again later. |