© blackforestbytes made by Mike Schwörer
Send

# Simple Cloud Notifier

## Introduction

With this API you can send push notifications to your phone.

To recieve them you will need to install the SimpleCloudNotifier app from the play store. When you open the app you can click on the account tab to see you unique `user_id` and `user_key`. These two values are used to identify and authenticate your device so that send messages can be routed to your phone.

You can at any time generate a new `user_key` in the app and invalidate the old one.

There is also a web interface for this API to manually send notifications to your phone or to test your setup.

## Quota

By default you can send up to 100 messages per day per device. If you need more you can upgrade your account in the app to get 1000 messages per day, this has the additional benefit of removing ads and supporting the development of the app (and making sure I can pay the server costs).

## API Requests

To send a new notification you send a `POST` request to the URL `https://scn.blackforestbytes.com/`. All Parameters can either directly be submitted as URL parameters or they can be put into the POST body.

You need to supply a valid `user_id` - `user_key` pair and a `title` for your message, all other parameter are optional.

## API Response

If the operation was successful the API will respond with an HTTP statuscode 200 and an JSON payload indicating the send message and your remaining quota

    {
        "success":true,
        "message":"Message sent",
        "response":
        {
            "multicast_id":8000000000000000006,
            "success":1,
            "failure":0,
            "canonical_ids":0,
            "results": [{"message_id":"0:10000000000000000000000000000000d"}]
        },
        "quota":17,
        "quota_max":100
    }

If the operation is not successful the API will respond with an 4xx HTTP statuscode.

Statuscode | Explanation
--- | ---
200 (OK) | Message sent
400 (Bad Request) | The request is invalid (missing parameters or wrong values)
401 (Unauthorized) | The user_id was not found or the user_key is wrong
403 (Forbidden) | The user has exceeded its daily quota - wait 24 hours or upgrade your account
412 (Precondition Failed) | There is no device connected with this account - open the app and press the refresh button in the account tab
500 (Internal Server Error) | There was an internal error while sending your data - try again later

There is also always a JSON payload with additional information. The `success` field is always there and in the error state you the `message` field to get a descritpion of the problem.

    {
        "success":false,
        "error":2101,
        "errhighlight":-1,
        "message":"Daily quota reached (100)"
    }

## Message Content

Every message must have a title set. But you also (optionally) add more content, while the title has a max length of 120 characters, the conntent can be up to 10.000 characters. You can see the whole message with title and content in the app or when clicking on the notification.

If needed the content can be supplied in the `content` parameter.

    curl                                          \
        --data "user_id={userid}"                 \
        --data "user_key={userkey}"               \
        --data "title={message_title}"            \
        --data "content={message_content}"        \
        https://scn.blackforestbytes.com/

## Message Priority

Currently you can send a message with three different priorities: 0 (low), 1 (normal) and 2 (high). In the app you can then configure a different behaviour for different priorities, e.g. only playing a sound if the notification is high priority.

Priorites are either 0, 1 or 2 and are supplied in the `priority` parameter. If no priority is supplied the message will get the default priority of 1.

    curl                                          \
        --data "user_id={userid}"                 \
        --data "user_key={userkey}"               \
        --data "title={message_title}"            \
        --data "priority={0|1|2}"                 \
        https://scn.blackforestbytes.com/s

## Message Uniqueness

Sometimes your script can run in an environment with an unstable connection and you want to implement an automatic re-try mechanism to send a message again if the last try failed due to bad connectivity.

To ensure that a message is only send once you can generate a unique id for your message (I would recommend a simple `uuidgen`). If you send a message with an UUID that was already used in the near past the API still returns OK, but no new message is sent.

The message_id is optional - but if you want to use it you need to supply it via the `msg_id` parameter.

    curl                                          \
        --data "user_id={userid}"                 \
        --data "user_key={userkey}"               \
        --data "title={message_title}"            \
        --data "msg_id={message_id}"              \
        https://scn.blackforestbytes.com/

Be aware that the server only saves send messages for a short amount of time. Because of that you can only use this to prevent duplicates in a short time-frame, older messages with the same ID are probably already deleted and the message will be send again.

## Custom Time

You can modify the displayed timestamp of a message by sending the `timestamp` parameter. The format must be a valid UNIX timestamp (elapsed seconds since 1970-01-01 GMT)

The custom timestamp must be within 48 hours of the current time. This parameter is only intended to supply a more precise value in case the message sending was delayed.

    curl                                          \
        --data "user_id={userid}"                 \
        --data "user_key={userkey}"               \
        --data "title={message_title}"            \
        --data "timestamp={unix_timestamp}"       \
        https://scn.blackforestbytes.com/

## Bash script example

Depending on your use case it can be useful to create a bash script that handles things like resending messages if you have connection problems or waiting if there is no quota left.
Here is an example how such a scrippt could look like, you can put it into `/usr/local/sbin` and call it with `scn_send "title" "content"`

    #!/usr/bin/env bash

    #
    # Call with   `scn_send title`
    #        or   `scn_send title content`
    #        or   `scn_send title content priority`
    #
    #

    if [ "$#" -lt 1 ]; then
        echo "no title supplied via parameter"
        exit 1
    fi

    ################################################################################
    # INSERT YOUR DATA HERE                                                        #
    ################################################################################
    user_id=999
    user_key="????????????????????????????????????????????????????????????????"
    ################################################################################

    title=$1
    content=""
    sendtime=$(date +%s)

    if [ "$#" -gt 1 ]; then
        content=$2
    fi

    priority=1

    if [ "$#" -gt 2 ]; then
        priority=$3
    fi

    usr_msg_id=$(uuidgen)

    while true ; do

        curlresp=$(curl -s -o /dev/null -w "%{http_code}" \
                        -d "user_id=$user_id" -d "user_key=$user_key" -d "title=$title" -d "timestamp=$sendtime" \
                        -d "content=$content" -d "priority=$priority" -d "msg_id=$usr_msg_id" \
                        https://scn.blackforestbytes.com/)

        if [ "$curlresp" == 200 ] ; then
            echo "Successfully send"
            exit 0
        fi

        if [ "$curlresp" == 400 ] ; then
            echo "Bad request - something went wrong"
            exit 1
        fi

        if [ "$curlresp" == 401 ] ; then
            echo "Unauthorized - wrong userid/userkey"
            exit 1
        fi

        if [ "$curlresp" == 403 ] ; then
            echo "Quota exceeded - wait one hour before re-try"
            sleep 3600
        fi

        if [ "$curlresp" == 412 ] ; then
            echo "Precondition Failed - No device linked"
            exit 1
        fi

        if [ "$curlresp" == 500 ] ; then
            echo "Internal server error - waiting for better times"
            sleep 60
        fi

        # if none of the above matched we probably hav no network ...
        echo "Send failed (response code $curlresp) ... try again in 5s"
        sleep 5
    done

Be aware that the server only saves send messages for a short amount of time. Because of that you can only use this to prevent duplicates in a short time-frame, older messages with the same ID are probably already deleted and the message will be send again.