API-SMS Documentation: Send SMS

POST

https://api.octopush.com/v1/public/sms-campaign/send

Encodage : UTF-8

Authentification

Your “api-key” and “api-login” identifiers must be added in the headers.

Definition

This sends a simple SMS.

simple (1 contact)
campaign (up to 500 contacts)

You must indicate your phone numbers in the “recipients” parameter, which is an array containing objects of type “contact”.

Special parameters

Name	Type	Description
text	string	Message text (from 1 to 1224 characters).
recipients	array	List of Contact objects array of objects: [ { "phone_number": "+111222233334444", "first_name": "Axelle", "last_name": "Durand", "param1": null, "param2": null, "param3": Mme, "param4": null, "param5": null }, ..., { "phone_number": "+2222333334444555", "first_name": "John", "last_name": "Smith", "param3": "M" } ]
sender	string	Sender of the message (if the user allows it), 3-11 alphanumeric characters (a-zA-Z0-9).
send_at	string	(optional) ‘When you want to send the sms campaign. Format: DateTime ISO8601 (for ex: “2018-10-03T07:42:39-07:00”).’
purpose	string	(optional) Campaign purpose: (transactional/alert or marketing) : [“alert”,”wholesale”]
with_replies	boolean	(optional) “true” for getting back recipient replies
simulation_mode	boolean	(optional) If this value is “true”, your request will be simulated, and you will receive a fake result. Only some minimal validations will be executed.
request_id	string	(optional) To avoid sending same request multiple times, setup an request ID. In case the duplication will be detected, a validation error will be returned. A request_id will expire after 24 hours.
auto_optimize_text	boolean	(optional) By transmitting this field with “false” value, your text will not be optimized by Octopush robot (your message could contain unicode characters, or useless spaces that could increase the number of needed SMS for each contact)..
`auto_remove_blacklisted_numbers`	boolean	(optional) By transmitting this field with “true” value, the blacklisted numbers will be automatically removed from your list of numbers. This service will add a charge of 0.01€ per request.

Exemple Curl

curl -X POST \ 
'https://api.octopush.com/v1/public/sms-campaign/send' \ 
-H 'Content-Type: application/json' \ 
-H 'api-key: ************' \ 
-H 'api-login: ******@email.org' \ 
-H 'cache-control: no-cache' \ 
-d '{
  "recipients": [
    {
      "phone_number": "+442038828112",    
                "first_name": "Axelle",
       "last_name": "Durand",
       "param3": "Mme"
    }
  ],
     "text": "This is a premium SMS with stop mention. STOP at XXXXX", 
  "type": "sms_premium",
  "purpose": "wholesale",
  "sender": "Company X"
}'

Curl Code to copy-past

curl -X POST 'https://api.octopush.com/v1/public/sms-campaign/send' -H 'Content-Type: application/json' -H 'api-login: @email.org' -H 'api-key: **********' -H 'cache-control: no-cache' -d '{"recipients": [{"phone_number": "+336000123", "first_name": "Axelle", "last_name": "Durand", "param3": "Mme"}], "text": "Voici un SMS Premium avec mention STOP. STOP au 30101", "purpose": "wholesale", "sender": "Entreprise"}'

Server Response in JSON

Success : 201 CREATED

{
  "sms_ticket": "sms_5f3fbce61266e",
  "number_of_contacts": 1,
  "total_cost": 5.00502839 
}

Failure : 400 Bad Request

{
  "code": 121,
  "message": "Mention STOP is missing."
}

* For some ovh users, using curl_setopt($ch, CURLOPT_FRESH_CONNECT, true); in their Curl sending sequence might be useful.

Interpretation of the data

The API we provide will try to interpret your request as best it can. If a parameter has the wrong type, we will try to understand it anyway. If the parameter has the wrong value, we will try to format it as best we can. Thus, we have determined default values, which are indicated in our documentation. If a parameter could not be recognized or “fixed”, we will ignore it, but your request will be sent.

If one of your parameters does not have the right value, or does not have the right type, we will try to :

“cast” (convert) him so that he is understood.
format it (delete prohibited characters for example)
replace it with the default value (if you do not specify the type of SMS correctly, we will use for example, Premium SMS)

Limitations

Be careful with the number of contacts per request. For campaigns, a good use is to transmit several frames of 200 to 500 numbers at a time.

< 200: you multiply calls and waste connection time
> 500: the frame becomes heavy and the risk of data loss increases.

Menu

Send SMS