Logo

JSON API

This document describes Eurobate’s JSON interface for pushing SMS messages using JSON over HTTPS. You also need to register the IP address you send from in Eurobate's system. Note: this cannot be used for premium SMS, only messages that are not billed to the receiving mobile.

Endpoint URL

  • https://api.eurobate.com/json_api.php

Parameter description

Name Required Description
user yes Username provided by Eurobate
password yes Password provided by Eurobate
msisdn yes The receiver’s mobile phone number. With preceding countrycode. For example: msisdn=4799999999
messages yes Array of 1 or more messages including originator, msisdn, message & dlrurl. See JSON messages array example at the bottom of this table.
message yes The actual message text. For one SMS, the maximum length will be 160 characters
originator yes A text or GSM number identifying the sender. If it is a GSM number then you must prefix it with the countrycode (with + sign, f.ex +47). Do not use space or special characters. Field length is 15 if numeric, or 11 if alphanumeric. The limitations are due to operator and phone differences.
ttl no Time To Live. How long should the message be attempted delivered. Legal values are between 5 minutes and 72 hours and is specified in seconds. For example ttl=7200 is two hours. If the message is not delivered within the specified ttl, it will be discarded and get ”failed” status. Default value is 24 hours.
dlrurl no Specifies the url for receiving delivery reports. (See below for more information)
simulate no 0 = off (default), 1 = on. Simulates a batch sending of messages, nothing will actually be sendt to the phone. You can use this when you want to test the API.
sendtime no Delayed SMS sending Set sendtime to current datetime format: YYYY-MM-DD HH:MM

Json messages array

"messages": [
    {
      "originator": "Eurobate",
      "msisdn": 4799999999,
      "message": "TEST JSON MSG1",
      "dlrurl": "dlrtest.php"
    },
    { 
      "originator": "Eurobate",
      "msisdn": 4799999998,
      "message": "TEST JSON MSG2",
      "dlrurl": "dlrtest.php"
    }
]

Json sms result

Value Description
msisdn The gsm number.
transactionid Contains the unique message identifier set by the SMS gateway if reportID is set.
error A numerical error code (see below)
info A textual description of the error. (see below)
messageParts The number of SMS the full message consists of.
ttl TTL set for this message
logon Status for logon
reason A textual reason description of logon failure
simulate Value of simulate if set
sendtime At which time the sms would be sent. Remove if sendtime is not set
uuid Universally unique identifier of the sms transaction

Error Codes

Error code Error string
0 Ok
1 Missing parameters
2 Wrong user/password
3 IP not authorized
4 Network error
5 Message body is not valid
6 An error occurred when sending the message to the operator
7 Wrong number format
8 User not allowed
9 Unspecified error
10 Illegal originator
11 Countrycode not allowed Your account is not open for this country, contact you sales person
12 Not in use
13 PKPass is missing!
14 PKPass could not be created
15 PKPasstemplate id is missing
16 JSON decode error
17 PKPasstemplate directory does not exist
18 Invalid sendtime date format. Valid dateformat: YYYY-MM-DD HH:MM
19 Date for sending is too far into the future
20 Prepaid balance is too low

Delivery reports

It is possible to receive delivery reports (DLR) from the operator network with information on the status of the message sendt to the phone. To set it up you will need a script on your server that can receive the DLR. This script will be called by Eurobate each time the status changes. You specify the URL to this script on parameter dlrurl.

For example: dlrurl = https://host.com/script.php?myid=1234&ebmsgid=MSGID&status=STATUS

Possible parameters to be parsed to the correct values are:

Value Description
MSGID Unique Eurobate messageid
STATUS One of the following operator delivery statuses
AVSENDER Originator of the message
DELER Number of parts the message consists of
MCC Mobile country code, or ‘0’ if unknown
MNC Mobile network code, or ‘0’ if unknown
LEVERINGSTID Time the message was delivered, or empty if not provided by operator.
UUID Universally unique identifier of the sms transaction if sendtime is used.

Operator delivery status

Status Description
acked message picked up and accepted by operator’s SMSC.
buffered message was tried sendt to the phone but could not be delivered, usually because the phone was turned off. Operator will retry until timeout, whereas the final status will be set to delivered or failed
rejected message sendt from Eurobate and was rejected by operator’s SMSC. Usually due to wrong phonenumber format.
delivered message delivered to the phone.
failed message not delivered to phone. Usually because the phone has been turned off and the retry period has expired, or the message is sendt to a invalid phone-number, or billing could not be completed.

DLR Retry

We will attempt to deliver the dlr with the following intervals:

  • 1 minute
  • 5 minutes
  • 15 minutes
  • 1 hour
  • 6 hours
  • 24 hours

Encoding

The message encoding can have one of the following autodetected encodings ISO-8859-1 or UTF-8. The encoding of the message determines the alphabet used for the sms encoding. The sms encoding is either GSM 7-bit or UCS-2 (16 bit).

It is the sms encoding that determines how many characters a single sms or a part in a concatenated sms can contain.

When using ISO-8859-1 as encoding, Message encoding is always done in GSM 7bit alphabet. Some characters in the ISO-8859-1 character set do not exist in the GSM-7bit character set. These characters will typically be replaced with a question mark character in the resulting sms message.

When using UTF-8 all characters must be in the GSM-7bit alphabet. If at least one character is not in the GSM 7-bit alphabet, UCS-2 encoding will be used in the resulting sms message. Messages with UCS-2 encoding allows for less characters before the message is split into multiple parts.

GSM encoding:

  • 1 standard SMS message = up to 160 characters
  • 2 concatenated SMS messages = up to 306 characters
  • 3 concatenated SMS messages = up to 459 characters

UCS-2 encoding:

  • 1 standard SMS message = up to 70 characters
  • 2 concatenated SMS messages = up to 134 characters
  • 3 concatenated SMS messages = up to 201 characters

Testing

We have provided a couple of example clients if you would like to test this. If you already have a username and password from Eurobate for pushing SMS you can use this. Otherwise contact us for a test account.

PHP example

<?php
$user='YOURUSERNAME';
$password='YOURPASSWORD';
$simulate = 1;
$msisdn = 4799999999;
$originator = 'Eurobate';
$message = 'TEST JSON 1234';
$dlrurl = 'dlrtest.php';

### Start timing of JSON SMS API
$time_start = microtime(true); 
$i=0;
# Generate 5 sms messages to SMS JSON API
for ($i=0;$i<1;$i++) {        
        $messages[] = array( 
                            'originator' => $originator,
                            'msisdn' =>$msisdn,                            
                            'message' => $message,
                            'dlrurl'=>$dlrurl
                           );
}

$arr = array(
        'user' =>$user, 
        'password' => $password, 
        'simulate'=>$simulate,     
        'messages' =>$messages
        );

$json = json_encode($arr);
$jsond=json_decode($json);
## DEBUG - output of json array sendt to json API
echo $json."\n\n";
print_r($jsond);

   $url = 'https://api.eurobate.com/json_api.php';
   $curl = curl_init($url);
   curl_setopt($curl, CURLOPT_POST, 1);
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
   curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
   curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
 if (!$buffer = curl_exec($curl)) {
    $buffer = 'EMPTY BUFFER';
 }
 echo $buffer;
 curl_close($curl);
 $jsond=json_decode($buffer);
 # Print json decoded array answer from json sms API
 print_r($jsond);

#End timing of JSON SMS API
$time_end = microtime(true);
$execution_time = ($time_end - $time_start);
echo 'Total time = '.$execution_time."\n";
?>

C# example (RestSharp)

using System;
using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;
using RestSharp;

namespace jsonSMS {

    public class Message {
        public string originator { get; set; }
        public long msisdn { get; set; }
        public string message { get; set; }
        public string dlrurl { get; set; }
        public string sendtime { get; set; }
    }

    public class RootObject {
        public string user { get; set; }
        public string password { get; set; }
        public int simulate { get; set; }    
        public List<Message> messages { get; set; }
    }

    class Program
    {
        static void Main(string[] args)
        {
            var sms = new RootObject();
            sms.user = "YOURUSERNAME";
            sms.password = "YOURPASSWORD";
            sms.simulate = 1;         
            sms.messages = new List<Message> 
                          {
                             new Message { originator="Eurobate", msisdn = 4799999999, message = "melding1", sendtime = "2019-11-08 12:00", dlrurl = "http://cpa.eurobate.com" },
                             new Message { originator="Eurobate",msisdn = 47999999988, message = "melding2" }
                          };
           dynamic Json = JsonSerializer.Serialize<RootObject>(sms);
           Console.WriteLine("\nJSON:\n");           
           Console.WriteLine(Json);           

           var client = new RestClient("https://api.eurobate.com/json_api.php");
           var request = new RestRequest(Method.POST);                      
           request.AddHeader("Content-Type", "application/json");
           request.AddParameter("undefined", Json, ParameterType.RequestBody);
           IRestResponse response = client.Execute(request);
           Console.WriteLine("\nResponse:\n");           
           Console.WriteLine(response.Content);                      
        }
    }
}

CURL example

curl --include \
 --request POST \
 --header "Content-Type: application/json" \
 --data '{"user":"xxx","password":"xxx","simulate":1,"messages":
[{"originator":"Eurobate","msisdn":4799999999,"message":"TEST JSON
1234","dlrurl":"dlrtest.php"}]}' \
 'https://api.eurobate.com/json_api.php'

Python example


import requests
url = "https://api.eurobate.com/json_api.php"
payload = "{\n \"user\": \"*USER*\",\n \"password\": \"*PASSWORD*\",\
n \"simulate\": 1,\n \"messages\": [\n {\n
\"originator\": \"Eurobate\",\n \"msisdn\": 4799999999,\
n \"message\": \"TEST JSON \",\
n \"dlrurl\": \"dlrtest.php\"\n }\n ]\n}"
headers = { 'Content-Type': "application/json" }
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)

Json examples

Sending 1 message:

{
"user": "YOURUSERNAME",
"password": "YOURPASSWORD",
"simulate": 1,
"messages": [
      {
        "originator": "Eurobate",
        "msisdn": 4799999999,
        "message": "TEST JSON 1234",
        "dlrurl": "dlrtest.php"
      }
  ]
}

Result:

{
"simulate": 1,
"LOGON": "OK",
"error":0,
"messages": [
      {
        "msisdn": 4799999999,
        "transactionid": 30,
        "error": 0,
        "info": "Ok",
        "messageParts": 1
      }
    ]
}

Sending multiple messages:

{
"user": "YOURUSERNAME",
"password": "YOURPASSWORD",
"simulate": 1,
"messages": [
    {
      "originator": "Eurobate",
      "msisdn": 4799999999,
      "message": "TEST JSON 1234",
      "dlrurl": "dlrtest.php"
    },
    {
      "originator": "Eurobate",
      "msisdn": 4799999999,
      "message": "TEST JSON 1234",
      "dlrurl": "dlrtest.php"
    }
  ]
}

Result:

{
"simulate": 1,
"LOGON": "OK",
"error":0,
"messages": [
    {
      "msisdn": 4799999999,
      "transactionid": 27,
      "error": 0,
      "info": "Ok",
      "messageParts": 1
    },
    {
      "msisdn": 4799999999,
      "transactionid": 29,
      "error": 0,
      "info": "Ok",
      "messageParts": 1
    }
  ]
}

Sending delayed message:

{
"user": "YOURUSERNAME",
"password": "YOURPASSWORD",
"simulate": 1,
"messages": [
    {
      "originator": "Sendtime",
      "msisdn": 4799999999,
      "message": "TEST tid ut: 2019-12-04 08:01",
      "dlrurl": "https://example.com/dlrtest.php",
      "sendtime": "2019-12-04 08:01"
    }
  ]
}

JSON result:

{
"LOGON": "OK",
"error":0,
"messages": [
      {
        "msisdn": 4799999999,
        "transactionid": 12,
        "uuid": "28dae2e8-fee7-11e9-87af-762931a7605b",
        "sendtime": "2019-12-04 08:01",
        "error": 0,
        "info": "Ok",
        "messageParts": 1
    }
  ]
}

JSON result logon error for wrong user/password:

{
    "LOGON":"ERROR",
    "STATUS":"ERROR",
    "error":2,
    "REASON":"Wrong user\/passwd : 10.10.10.10"
}

JSON result logon error for IP not valid:

{
    "LOGON":"ERROR",
    "STATUS":"ERROR",
    "error":3,    
    "REASON":"IP not authorized : 10.0.10.2"
}

JSON result logon error for Invalid JSON:

{
    "LOGON":"ERROR",
    "STATUS":"ERROR",
    "error":16,
    "REASON":"JSON decode error : Syntax error"
}

Eurobate AS - www.eurobate.no