NAV Navbar
shell php javascript

Introduction

Welcome to the SMSO API! You can use our API to access SMSO API endpoints.

We have language bindings in Shell, PHP, JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl -H "X-Authorization: API-KEY"  "https://app.smso.ro/api/v1/"

# full example as query string
curl "https://app.smso.ro/api/v1/send?sender=4&to=0722334455&body=Message%20Body&apiKey=API-KEY"


<?php

// via file_get_contents
$opts = [
    "http" => [
        "method" => "POST",
        "header" => "X-Authorization: API-KEY"
    ]
];

$context = stream_context_create($opts);

$content = file_get_contents('https://app.smso.ro/api/v1/', false, $context);

var_dump($content);

// via guzzle
use GuzzleHttp\Client;

$client = new Client;
$request =  $client->request('GET', 'https://app.smso.ro/api/v1/', [
    'headers' => [
        'X-Authorization' => 'API-KEY',
    ],
]);

var_dump(json_decode($request->getBody()->getContents()));


// soon

Make sure to replace API-KEY with your Tean's API key from our developer page.

SMSO uses API keys to allow access to the API. You can register a new SMSO API key at our developer page.

SMSO expects for the API key to be included in all API requests to the server in a header that looks like the following:

  1. Via a header: X-Authorization: API-KEY
  2. Via a query string, either POST OR GET, just append it to the URL like &apiKey=API-KEY

Senders

Get the list of available senders


curl -H "X-Authorization: API-KEY"  "https://app.smso.ro/api/v1/senders"


<?php
use GuzzleHttp\Client;

$client = new Client;
$request = $client->request('GET', 'https://app.smso.ro/api/v1/senders', [
        'headers' => [
            'X-Authorization' => 'API-KEY',
        ],
    ]);

// nothing yet

The above command returns JSON structured like this:

[
   {
      "id":4,
      "name":"1847",
      "pricePerMessage":3
   },
   ...
]

This endpoint retrieves all the available senders in the the team.

HTTP Request

GET https://app.smso.ro/api/v1/senders

Query Parameters

None

Messages

Sending a message


curl --request POST --header 'X-Authorization: smso-api-key' "https://app.smso.ro/api/v1/send" \
  -d "sender=4" \
  -d "to=+40722334455" \
  -d "body=Testing"


<?php
use GuzzleHttp\Client;

$client = new Client;
$request = $client->request('POST', 'https://app.smso.ro/api/v1/send', [
        'headers' => [
            'X-Authorization' => 'smso-api-key',
        ],
       'form_params' => [
           'to' => '',
           'body' => '',
           'sender' => '',
       ],
]);

var_dump(json_decode($request->getBody()->getContents()));

// nothing yet

The above command returns JSON structured like this:

{
  "status": 200,
  "responseToken": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "transaction_cost" : 3.5 // in eurocents
}

This endpoint sends an SMS Message

HTTP Request

POST https://app.smso.ro/api/v1/send

Query Parameters

Parameter Required? Description
to Yes E.164 Format. The + is optional
sender Yes The ID of the sender
body Yes Contents of the message
type No Type of the message. Can be 'marketing', 'transactional' or 'otp', based on the type of communication the message is intended for. Used to filter out unsubscribed users when set to 'marketing'.
webhook No Identical to webhook_status, preserved for legacy purposes
webhook_status No Webhook for receiving the SMS message status
webhook_responses No Webhook for receiving the SMS message reply
generate_unsubscribe_link No Possible values 1/0. If 1, replaces the [unsubscribe] tag from the body with a generated short URL unsubscribe link. Only for 'marketing' message type!
remove_special_chars No Possible values 1/0. If 1, replaces special characters like diacritics with ASCII characters (Ex.: ĂÂ = A, Ș = S, etc.)

Checking the message status


curl --request POST "https://app.smso.ro/api/v1/status" \
  -d "responseToken=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"

// also GET
curl "https://app.smso.ro/api/v1/status?responseToken=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"

<?php
use GuzzleHttp\Client;s

$client = new Client;

$request = $client->request('GET', 'https://app.smso.ro/api/v1/status?responseToken=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');
// also POST
$request = $client->request('POST', 'https://app.smso.ro/api/v1/status', [
          'form_params' => [
              'responseToken' => 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
          ],
      ]);

var_dump(json_decode($request->getBody()->getContents()));

// soon

The above command returns JSON structured like this:

{
    "status": 200,
    "data": {
        "status": "delivered",
        "sent_at": "2019-05-1 15:18:20",
        "delivered_at": "2019-05-1 15:18:25",
        "receiver": {
            "number": "+40722334455",
            "mcc": "226",
            "mnc": "01"
        }
    }
}

This endpoint sends an SMS Message

HTTP Request

POST or GET https://app.smso.ro/api/v1/status

Query Parameters

Parameter Required? Description
responseToken Yes The uuid from the SEND

Message Statuses

// nothing

// nothing

// nothing

The above command returns JSON structured like this:

// nothing

Message status description

The message can take a number of states.

Status Descriptions

Status Final Description
dispatched No The message is in the process of sending to the network. (rarely seen)
sent No The message has been sent to the network.
delivered Yes The message has been delivered to the phone.
undelivered Yes The message was undelivered.
expired Yes The message is expired.
error Yes There was an error sending the message.

Webhooks

Message status


# use this command to simulate an incomming request to test yout webhook

curl --request POST "https://your-server.com/your-webhook-endpoint" \
  -d "uuid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
  -d "status=sent" \
  -d "sent_at=2019-05-01 12:30:09" \
  -d "delivered_at=2019-05-01 12:20:09" \
  -d "receiver[number]=+40722334455" \
  -d "receiver[mcc]=226" \
  -d "receiver[mnc]=03"

// nothing yet

// nothing yet

You can use an app like postb.in to test incoming requests.

// no output

This is an endpoint on your application side that handles the status of the message.

HTTP Request

POST https://your-server.com/your-webhook-endpoint

Query Parameters

Parameter Can be empty? Description
uuid No Uuid received from sending the message
status No Message status
sent_at No Time sent to the network
delivered_at Yes Time delivered to phone
receiver['number'] No Receiving number in E.164 Format.
receiver['mcc'] No Mobile Country Code
receiver['mnc'] No Mobile Network Code

Receiving messages


# use this command to emulate a webhopok

curl --request POST "https://your-server.com/your-webhook-endpoint" \
  -d "body=Nu raspunzi la sms..." \
  -d "replied_to=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
  -d "received_at=2019-05-01 12:30:09" \
  -d "sender['number']=+40722334455" \
  -d "sender['mcc']=226" \
  -d "sender['mnc']=03"


// soon


// soon

You can use an app like https://postb.in/ to test incoming requests.

This is an endpoint on your application side that handles receiving messages.

HTTP Request

POST https://your-server.com/your-webhook-endpoint

Query Parameters

Parameter Can be empty? Description
body Yes Contents of the message
replied_to Yes Uuid of the message that the number received and is now responding to
received_at No Time the message was received
sender['number'] No Sender number in E.164 Format.
sender['mcc'] No Mobile Country Code
sender['mnc'] No Mobile Network Code

Errors

The SMSO API uses the following error codes:

Error Code Meaning
200 OK
400 Bad Request -- Your request is invalid. See errors attached.
401 Unauthorized -- Your API key is wrong.
402 Payment Required -- You don't have enough credit to send the message.

Credit

Checking remaining credit


curl --request GET --header 'X-Authorization: smso-api-key' "https://app.smso.ro/api/v1/credit-check"


<?php
use GuzzleHttp\Client;

$client = new Client;
$request = $client->request('GET', 'https://app.smso.ro/api/v1/credit-check', [
        'headers' => [
            'X-Authorization' => 'smso-api-key',
        ],
]);

var_dump(json_decode($request->getBody()->getContents()));

// nothing yet

The above command returns JSON structured like this:

{
  "status" : 200,
  "credit_value" : 4847.72
}

This endpoint returns the remaining credit for the team

HTTP Request

GET https://app.smso.ro/api/v1/credit-check

Query Parameters

None.

shell php javascript