Parameters for sending SMS via HTTP API

Use this flexible endpoint to send SMS to one or more recipients at the same time.

Please direct your request to the following URL: https://gateway.sms77.io/api/sms

Required parameters

The following parameters are required in addition to authentication:

Parameter	Description	Examples
`to`	Recipient number – possible are numbers and address book entries (groups and contacts). Multiple recipients can be specified separated by commas	`0049171999999999` `0171999999999` `49171999999999` `+49171999999999` `Group1,Contact1`
`text`	The text message. May not exceed 1520 characters. If more than 160 characters are used, the text is distributed over several messages, each SMS is calculated individually.	`Dear customer, we have not heard from you in a while. Use the coupon code WEMISSU to save 10% on the next order. Sincerely, your pet store.`

Optional parameters

0 = The parameter is deactivated – this is the default setting if not specified otherwise.
1 = The parameter is activated.

Parameter	Description	Examples
`from`	The sender number. It may contain a maximum of 11 alphanumeric or 16 numeric characters.	`Sender` `01761234567890` `CompanyABC`
`debug`	If activated no SMS will be sent or calculated. Useful to see if the connection to the API actually works without spending money.	`0` `1`
`delay`	Specify a custom point of time for time-delayed SMS. Accepts a Unix timestamp or a date/time string formatted as yyyy-mm-dd hh:ii.	`1141511104` `2016-03-04 23:25:04`
`no_reload`	Switch off reload lock. This lock prevents the sending of the same SMS (text, type and recipient alike) within 180 seconds. You can deactivate this lock permanently in your login under Settings > SMS.	`0` `1`
`unicode`	Transmission as Unicode SMS (Cyrillic, Arabic etc characters). The SMS length is thereby reduced to 70 characters. Please note that our Gateway recognizes the coding automatically. This parameter is therefore not necessary. You can, however, force a certain transmission method hereby. Only Direct SMS support unicode messages.	`0` `1`
`flash`	Send as Flash SMS. These are displayed directly in the receiver’s display. Flash SMS do not show sender names, except on some older phone models. See more.	`0` `1`
`udh`	Only for Direct SMS. Individual User Data Header (UDH) of the SMS. If specified and variable `text` contains hexcode, the message will be sent as 8-bit binary SMS.	`050003CC0201` (Concatenated message: reference number 204, part 1 of 2 parts)
`utf8`	Forces the detection as a UTF-8 character set and overrides automatic recognition of the API.	`0` `1`
`ttl`	Specifies the validity period of the SMS in minutes. This is also known as time to live.	`2880` 48h (default) `60` 1h
`details`	Shows numerous details for the sent SMS. Handy for debugging.	`0` `1`
`return_msg_id`	If this parameter is set, the ID of the SMS is output in the second line after the status code.	`0` = Only status code (default) `1` = return ID
`label`	You can optionally set a separate label for each SMS so that you can assign it to your statistics. Max. 100 chars, allowed characters: `a-z, A-Z, 0-9, .-_@`.	`Customer_1` `Marketing_22.02.2018` `Splittest17`
`json`	The output is more detailed in JSON format.	`0` – out as text `1` – output as JSON
`performance_tracking`	Enable Performance Tracking for URLs found in the message text.	`0` `1`
`foreign_id`	Provide your own data for this message. You will get the `foreign_id` returned in DLR callbacks etc. Max. 64 chars, allowed characters: `a-z, A-Z, 0-9, .-_@`.	`id12345`

File attachments

You can send file attachments directly via API. To do this, you need to pass in the files parameter as an associative array the respective files.

Parameter	Description	Examples
`name`	The Filename. It must be inserted exactly like this in the SMS text as a placeholder. Here it would be [[document.pdf]].	`document.pdf`
`contents`	Contents of the file encoded as base64.	`iVBORw0KGgoAAAANSUhEUgAAAdoAAACWCAYAAAB5CUk.......`
`validity` (optional)	You can set a validity period in days.	`3`
`password` (optional)	You can set an access password to protect the file.	`password123`

For example, here would be files[0][name]=document.pdf, files[0][contents]=iVBORw0KGgoAAAANSUhEUgAAAdoAAACWCAYAAAB5CUk......., files[0][validity]=3 and files[0][password]=password123.

In the SMS text, please enter the respective placeholder at the desired position: Here is the file: [[document.pdf]]

Return

In response to your request, you will receive a numeric return value and the message ID of the message sent. You can later use the ID to assign e.g status reports.
If you specify the parameter details you will receive a lot of additional information – amongst other things the credit balance and the booked credit.
The return is done as a simple text with each value separated by \n in a line.

The following return status codes are possible:

100: The SMS was accepted by the gateway.
101: The transmission to at least one recipient failed.
201: The sender is invalid. A maximum of 11 alphanumeric or 16 numeric characters is allowed.
202: The recipient number is invalid.
301: The variable to is not set.
305: The variable text is not set.
401: The variable text is too long.
402: The Reload Lock prevents sending this SMS as it has already been sent within the last 180 seconds.
403: The maximum limit for this number per day has been reached.
500: The account has too little credit available.
600: The carrier delivery failed.
900: The authentication failed. Please check your API key.
901: The verification of the signing hash failed.
902: The API key has no access rights to this endpoint.
903: The server IP is wrong.

Character set

SMS support a very own 7-bit character set (GSM 0338), which contains some UTF-8 characters such as e.g. German umlauts, but not e.g. ó or Chinese, Arabic, Cyrillic characters, etc. For this, a unicode SMS would have to be sent, which is coded with 8 bits and therefore requires only 70 characters space per SMS. A Unicode SMS with e.g. 120 characters would hence cost twice as a normal SMS.

Here you can learn more about the specifications of the SMS character set and see the complete list of allowed characters in normal (not unicode) SMS: https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_.2F_GSM_03.38.

Examples

1. Simple sending of SMS

The call of the following URL sends an SMS with the content my first message as a Direct SMS with the sender sms77.io to the phone number 49160999999999:

Request:
https://gateway.sms77.io/api/sms?p=api-key&to=49160999999999&text=my%20first%20message&from=sms77.io&return_msg_id=1

Response:

100
123456789

The SMS has been transmitted successfully – the Msg ID is 123456789.

2. Debug mode with detailed output

This call doesn’t send an SMS due to the set parameter debug, but it shows a lot of details about the message.

Request: http://gateway.sms77.io/api/sms?p=api-key&to=Group1&text=Test+SMS&from=SMS&flash=0&details=1&debug=1

Response:

100
booked: 0
price: 0.089
credit: 27.38
text: Test SMS
SMS type: direct
Flash SMS: off
Encoding: ASCII
GSM0338: true
Debug: true

3. JSON

This is an example response when the parameter json is set to 1 and the parameter debug is set to 1.

{
  "success": "100",
  "total_price": 0,
  "balance": 14.693,
  "debug": "true",
  "sms_type": "direct",
  "messages": [
    {
      "id": null,
      "sender": "xaxa",
      "recipient": "491771783130",
      "text": "Dear customer, we are closed in week 14. See you soon - SuperStore",
      "encoding": "gsm",
      "label": null,
      "parts": 1,
      "price": 0,
      "success": true,
      "error": null,
      "error_text": null
    }
  ]
}

Gateway

Send SMS