Overview

You can use our API to send messages via individual StreamIn sources. That means you’ve created your custom source using the web office and you can obtain an API key. Every time you attempt to send a notification through StreamIn the source is determined based on the API key you used to sign the request.

The API is accessible through the following URL:

http://app.streamin.io/api/source

This is a RESTful API so you can use your browser to access URL’s.

The result of requests sent to the API is a JSON object that has the following structure:

status

Status code of the request. Default status codes are:

  • 0 - request failure
  • 1 - request success

There are some other specific error codes that can you can manage in your applications. Check out the full list of error codes below.

message Message describes the request status code. When request succeeded, message is “n/a” but in case of errors you get the error description.
result This is the result of the request. It’s content structure depends on the request you made.

List of API request status codes:

0 error
1 success
101 invalid API key
102 no API key
103 request not supported
104 invalid API call structure
105 unknown API request
201 over refresh limit

Currently, the API is focused on sending notifications. We are considering offering more options.


API key

To use the API you’ll need an API key that you can find in StreamIn web office in your source settings:

API key

You should not reveal your API key in public and we advise you to reset it periodically. This can be done manually in the web office or automatically by using the API.

In order to make it simple for you to use our API, we developed libraries in PHP and Ruby. Take a look at some example usages.


API requests

Here is a list of API requests you can make:

  • ping
  • refresh_api_key
  • new_message

ping

You can use this API call to determine if you have a valid API key and if StreamIn API is available.

Params:

api_key Your 32 characters long alphanumeric source API key.

Example:

                                                require 'StreamIn.php';
                                                $lib = new StreamIn('c197a6f761adb8ce1a47cdf9f22d705c');
                                                try {
                                                    $lib->ping();
                                                    // ping successful
                                                }
                                                catch (StreamInException $e) {
                                                    // ping unsuccessful
                                                }
                                            
                                                require 'streamin.rb'
                                                lib = Streamin.new 'c197a6f761adb8ce1a47cdf9f22d705c'

                                                begin
                                                  lib.ping
                                                  # ping successful
                                                rescue StreamInException => exception
                                                  # ping unsuccessful
                                                end
                                            
                                                curl --request GET
                                                http://app.streamin.io/api/source/ping?api_key=c197a6f761adb8ce1a47cdf9f22d705c
                                            

Result:

                                        {
                                            "status" : 1,
                                            "message" : "n/a",
                                            "result" : {
                                                "success" : "Pong! You have a valid API key!"
                                            }
                                        }
                                    

refresh_api_key

You can refresh your API key once per day. Any attempt to refresh the API key more than once per day will result in an error code -201 (over refresh limit). On successful request, the result will contain the new key.

Params:

api_key Your 32 characters long alphanumeric source API key.

Example:

                                                require 'StreamIn.php';
                                                $lib = new StreamIn('c197a6f761adb8ce1a47cdf9f22d705c');
                                                try {
                                                    $api_key = $lib->refresh_api_key();
                                                    // store the new API key
                                                }
                                                catch (StreamInException $e) {
                                                    echo $e->errorMessage();
                                                }
                                            
                                                require 'streamin.rb'
                                                lib = Streamin.new 'c197a6f761adb8ce1a47cdf9f22d705c'

                                                begin
                                                  api_key = lib.refresh_api_key
                                                  # store the new API key
                                                rescue StreamInException => exception
                                                  puts exception.message
                                                end
                                            
                                                curl --request GET http://app.streamin.io/api/source/refresh_api_key?api_key=c197a6f761adb8ce1a47cdf9f22d705c
                                            

Result:

                                        {
                                            "status" : 1,
                                            "message" : "n/a",
                                            "result" : {
                                                "api_key" : "e8468bc7a055e0601f1842c515bffeb2"
                                            }
                                        }
                                    

new_message

You can send unlimited number of messages via your StreamIn sources. After a successful request, the response will contain information about the newly created message.

Params:

api_key Your 32 characters long alphanumeric source API key.
external_id

This is the message identifier inside your system that cannot be more than 255 characters long.

It is not obligatory to use it if you don’t have an identifier or you don’t want to point it out when sending the message. In that case, we recommend you to generate a timestamp string as your message ID.

content
Message content cannot have more than 1000 characters in total. We enabled some basic Wiki-formatting that you can use to point out parts of your message:
bold '''this will be bold'''
italic ''this will be italic''
bold & italic ''''this will be bold and italic''''
link [http://my_link_url my_link_text]
delivery_confirmation Delivery Confirmation is still an experimental feature. The param can have values 0 for yes or 1 for no.

* all params are required

Example:

                                                require 'StreamIn.php';
                                                $lib = new StreamIn('c197a6f761adb8ce1a47cdf9f22d705c');
                                                try {
                                                    $timestamp = $lib->new_message(“message_345185”,”This is a test message”);
                                                    // use timestamp to update internally
                                                }
                                                catch (StreamInException $e) {
                                                    echo $e->errorMessage();
                                                }
                                            
                                                require 'streamin.rb'
                                                lib = Streamin.new 'c197a6f761adb8ce1a47cdf9f22d705c'

                                                begin
                                                  timestamp = lib.new_message message_345185,'This is a test message’
                                                  # use timestamp to update internally
                                                rescue StreamInException => exception
                                                  puts exception.message
                                                end
                                            
                                                curl --request GET  http://app.streamin.io/api/source/new_message?api_key=c197a6f761adb8ce1a47cdf9f22d705c&external_id=message_345185&content=This%20is%20a%20test%20message&delivery_confirmation=0
                                            

Result:

                                        {
                                            "status" : 1,
                                            "message" : "n/a",
                                            "result" : {
                                                "message_info" : {
                                                    "external_id" : "message_345185",
                                                    "content" : "This is a test message",
                                                    "created_at" : "2013-05017 12:02:50 +0200",
                                                    "delivery_confirmation" : false
                                                }
                                            }
                                        }
                                    

PHP Library

The library is single PHP file (“StreamIn.php”) that contains the library class and the exception class. The only dependency is having cURL enabled on server side.

To use the library, you have to create a new library object by specifying the API key of the source you want to use:

                                    require 'StreamIn.php';
                                    $lib = new StreamIn('c197a6f761adb8ce1a47cdf9f22d705c');
                                    // use library methods
                                

You can change the API key dynamically to use other sources:

                                    $lib->api_key = ‘e8468bc7a055e0601f1842c515bffeb2’;
                                    // use library methods with another source
                                

In order to properly use the API methods, you should wrap your calls in try catch blocks:

                                    try {
                                        $result = $lib->refresh_api_key();
                                    }
                                    catch (StreamInException $e) {
                                        echo $e->errorMessage();
                                    }
                                

You can view and download the library on GitHub.

Ruby library

The library is single Ruby file (“streamin.rb”) that contains the library class and the exception class. There are two dependencies: ‘uri’ and ‘net/https’. You should add them to your Gemfile.

To use the library, you have to create a new library object by specifying the API key of the source you want to use:

                                    require 'streamin.rb'
                                    lib = Streamin.new 'c197a6f761adb8ce1a47cdf9f22d705c'
                                    // use library methods
                                

You can change the API key dynamically to use other sources:

                                    lib.api_key = ‘e8468bc7a055e0601f1842c515bffeb2’;
                                    // use library methods with another source
                                

In order to properly use the API methods, you should be ready to handle errors:

                                    begin
                                      response = lib.refresh_api_key
                                    rescue StreamInException => exception
                                      puts exception.message
                                    end
                                

You can view and download the library on GitHub.