NAV
curl C# Go PHP

Introduction

Welcome to the iLiveIt API!

The iLiveIt API is aimed at making integration with our services as simple as possible. We provide a full REST API to all our services, although some services might not be available to your subscription level.

We have language bindings for C# and Go with code samples and raw curl calls. 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.

Getting Started

We provide client libraries in multiple languages to make integration even easier. See the Client Libraries section for the links.

Bug reporting

If you find a bug in any of the client libraries, please contect us at bugs@iliveit.co.za.

C# Client Library

Prerequisites

Installation

  1. Copy the files downloaded from the Client Libraries section to your application’s lib directory
  2. Add iliveit.MessagingAPI.dll as a reference in your application

Go Client Library

Prerequisites

Installation

  1. go get github.com/iliveit/go-messaging-client
  2. Include github.com/iliveit/go-messaging-client in your application

PHP Client Library

Prerequisites

Installation

  1. Download the files from Client Libraries and extract to your application
  2. Add require_once(getcwd() . '/iliveit/Iliveit.php'); to load the autoloader
  3. Add use Iliveit\IliveitApi; to your code

Samples

All client library packages include sample applications with working API calls to get your started. Check the samples directory for the applications.

Note: The PHP library only implements Email sending (with attachments) as well as Parsing and retrieving message statuses

Available Environments

We provide seperated development and production environments, named staging and production respectively.

Access tokens for both can be managed on the developer portal.

Authentication

Our MessagingAPI uses Application Tokens to authenticate every request. You can generate application tokens at our developer portal.

We expect the token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer HelloWorldToken

Rate Limiting

We apply rate limiting to all API calls (per application). You can view your limit or request an increase on our developer portal.

When your application hits its rate limit, an HTTP Error 429: Maximum messages per second exceeded. It is safe to retry the message later. See the errors section for more information.

API Guarantees

We provide the following guarantees when a message is submitted to our API:

  1. No message will ever be submitted to a network more than once
  2. PostBacks of statuses will be submitted back to you within one hour of the status changing
  3. One Time PIN messages will never be archived (One Time PIN permission must be requested)
  4. Messages and their statuses can only be accessed by the application that initially sent the message
  5. We load balance across multiple instances of the API to ensure the highest uptime possible

API Reference

Below follows a complete reference of all available API calls with their respective code samples. Error handling is omitted for brevity.

Initialization

No curl equivalent

using iliveit.MessagingAPI;
using iliveit.MessagingAPI.Structs;

APIConfig config = new APIConfig();
config.AccessToken = "Your-Application-Access-Token";
config.Endpoint = "http://api-endpoint";

MessagingAPI api = new MessagingAPI(config);

import(
    "github.com/iliveit/go-messaging-client"
)

apiConfig := messagingapi.APIConfig{
    AccessToken: "Your-Application-Access-Token",
    Endpoint: "http://api-endpoint",
}

api, err := messagingapi.New(apiConfig)

Basic API initialization using the client libraries. This section will not be repeated in sample code for all API calls.

Ping

curl "http://api-endpoint/ping" -H "Authorization: Bearer Your-Application-Access-Token"

using iliveit.MessagingAPI;
using iliveit.MessagingAPI.Structs;

APIConfig config = new APIConfig();
config.AccessToken = "Your-Application-Access-Token";
config.Endpoint = "http://api-endpoint";

MessagingAPI api = new MessagingAPI(config);

APIResult result = api.Ping();

import(
    "github.com/iliveit/go-messaging-client"
)

apiConfig := messagingapi.APIConfig{
    AccessToken: "Your-Application-Access-Token",
    Endpoint: "http://api-endpoint",
}

api, err := messagingapi.New(apiConfig) 
result, err := api.Ping()

The above command returns JSON structured like this:

{
    "Body":"Pong!"
}

The Ping call is regarded as the easiest way to check your application’s access. It simply responds with ‘Pong!’, an error if you are rate-limited or Authentication failure if your access token is incorrect

HTTP Request

GET http://api-endpoint/ping

Submit MMS

curl "http://api-endpoint/message/send" -H "Authorization: Bearer Your-Application-Access-Token" -H "Content-Type: application/json" -X POST -d '{"Action":1,"MVNOID":1,"Data":{"message_type":"mms","msisdn":["27000000000"],"network":"*","slides":[{"duration":"5","content":[{"type":"text","mime":"text/plain","data":"Sample MMS Text","name":"text.txt"}]}],"subject":"Sample MMS"},"Campaign":"Sample MMS"}'

using iliveit.MessagingAPI;
using iliveit.MessagingAPI.Structs;
using iliveit.MessagingAPI.Enums;

APIConfig config = new APIConfig();
config.AccessToken = "Your-Application-Access-Token";
config.Endpoint = "http://api-endpoint";

MessagingAPI api = new MessagingAPI(config);

NewMessage msg = new NewMessage();
msg.Action = APIActionTypes.SubmitMMS;
msg.MVNOID = 1;
msg.Campaign = "Sample MMS";

SubmitMMSMessageData msgData = new SubmitMMSMessageData();
msgData.MSISDN.Add("27000000000");
msgData.Subject = "Sample MMS";
msgData.Network = "*";
MMSSlideContent slideContent = new MMSSlideContent();
slideContent.Type = MMSSlideTypes.Text;
slideContent.Mime = "text/plain";
slideContent.Name = "text.txt";
slideContent.Data = "Sample MMS Text";
msgData.Slides.Add(new MMSSlide(5, slideContent));
msg.Data = msgData;

APIResult result = api.Create(msg);
Console.WriteLine("Message ID:" + result.MessageResult.MessageID);

import(
    "github.com/iliveit/go-messaging-client"
)

apiConfig := messagingapi.APIConfig{
    AccessToken: "Your-Application-Access-Token",
    Endpoint: "http://api-endpoint",
}

api, err := messagingapi.New(apiConfig) 

msg := messagingapi.NewMessage{
    Action: messagingapi.APIActionTypesSubmitMMS,
    MVNOID: 1,
    Campaign: "Sample MMS",
}

msgData := messagingapi.SubmitMMSMessageData{
    Network: "*",
    MSISDN: []string{"27000000000"},
    Subject: "Sample MMS",
}

slideContent := messagingapi.MMSSlideContent{
    Type: messagingapi.MMSContentTypeText,
    Mime: "text/plain",
    Name: "text.txt",
    Data: "Sample MMS Text",
}

slide := messagingapi.MMSSlide{
    Duration: "5",
}
slide.Content = append(slide.Content, slideContent)
msgData.Slides = append(msgData.Slides, slide)
msg.Data = msgData

result, err := api.Create(msg)
fmt.Println(result.MessageResult.MessageID)

The above command returns JSON structured like this:

{
    "MessageID": "returned-message-id-string"
}

Submit MMS sends an MMS to a mobile device. All parameters are submitted as a single JSON structure.

HTTP Request

POST http://api-endpoint/message/send

JSON Structure

Parameter Value Type Description
Action 1 APIActionTypes An APIActionTypes with value 1 denotes an MMS message
MVNOID ? int Also known as a client ID. This will be supplied by iLiveIt
Campaign “Sample” string Optional. Your campaign ID. Makes reporting easier by grouping related messages by campaign
PostBackStatusTypes PostBackStatusTypes string (comma delimited) The type of postbacks you wish to receive on PostbackStatusUrl
PostbackStatusUrl “http://your-endpoint” string (url) The location you wish to receive status PostBacks on
Data ? SubmitMMSMessageData The data for the MMS, see SubmitMMSMessageData Structure

Generate and Submit Video MMS

curl "http://api-endpoint/generate/video" -H "Authorization: Bearer Your-Application-Access-Token" -H "Content-Type: application/json" -X POST -d '{"MVNOID":1,"Data":"JSON String supplied by iLiveIt","Campaign":"Sample Campaign","BuildTemplate":1,"AfterBuildAction":1,"AfterBuildData":"{\"message_type\":\"mms\",\"msisdn\":[\"27000000000\"],\"network\":\"*\",\"slides\":[],\"subject\":\"\"}"}'

using iliveit.MessagingAPI;
using iliveit.MessagingAPI.Structs;
using iliveit.MessagingAPI.Enums;

APIConfig config = new APIConfig();
config.AccessToken = "Your-Application-Access-Token";
config.Endpoint = "http://api-endpoint";

MessagingAPI api = new MessagingAPI(config);

// Create the Video build request
BuildRequest msg = new BuildRequest();
msg.MVNOID = 1;
msg.Campaign = "Sample Campaign";
msg.BuildTemplate = 1;

msg.Data = "JSON String or Serializable object supplied by iLiveIt";
// Specify what the API needs to do when the build is complete
msg.AfterBuildAction = APIActionTypes.SubmitMMS;

// You need to supply data for the post build action
SubmitMMSMessageData postBuildData = new SubmitMMSMessageData();

// A network with a value of '*' will tell the API to
// determine the network using the number ranges and portability
// database. '*' is preferred unless you know exactly which network
// to use.
postBuildData.Network = "*";
List<string> msisdnList = new List<string>();
msisdnList.Add("27760913077");
postBuildData.MSISDN = msisdnList;
//
// No need to include the Slide content or Subject, that is handled
// by the templating system that generates
// the MMS images and videos
//
msg.AfterBuildData = postBuildData;

APIResult result = api.Generate(msg);
Console.WriteLine("Message ID:" + result.MessageResult.MessageID);

import(
    "github.com/iliveit/go-messaging-client"
)

apiConfig := messagingapi.APIConfig{
    AccessToken: "Your-Application-Access-Token",
    Endpoint: "http://api-endpoint",
}

api, err := messagingapi.New(apiConfig)

// Create the Video build request
buildRequest := messagingapi.BuildRequest{
    MVNOID: 1,
    Campaign: "Sample Campaign",
    BuildTemplate: 1,
    AfterBuildAction: messagingapi.APIActionTypesSubmitMMS,
}
buildRequest.Data = "JSON String or Serializable object supplied by iLiveIt" 
msgData := messagingapi.SubmitMMSMessageData{
    // Network '*' uses the portability list to determine
    // the destination network
    Network: "*",
    MSISDN: []string{"27000000000"},
}
buildRequest.AfterBuildData = msgData

result, err := api.Generate(buildRequest);
// Handle the result
fmt.Println(result.MessageResult.MessageID)

The above command returns JSON structured like this:

{
    "MessageID": "returned-message-id-string"
}

This call will generate a video and send it to the mobile device using MMS if the build succeeds. This call will also check the MSISDN for MMS capability and determine the correct size, quality and format to send to the MSISDN.

HTTP Request

POST http://api-endpoint/generate/video

JSON Structure

Parameter Value Type Description
AfterBuildAction 1 APIActionTypes The action to be taken after the build completes. An APIActionTypes with value 1 denotes an MMS message
MVNOID ? int Also known as a client ID. This will be supplied by iLiveIt
Campaign “Sample” string Optional. Your campaign ID. Makes reporting easier by grouping related messages by campaign
BuildTemplate 1 int The template to be used. Will be supplied by iLiveIt **
PostBackStatusTypes PostBackStatusTypes string (comma delimited) The type of postbacks you wish to receive on PostbackStatusUrl
PostbackStatusUrl “http://your-endpoint” string (url) The location you wish to receive status PostBacks on
Data ? string or object The data for building the video, this will be supplied by iLiveIt**
AfterBuildData ? string or object The data for the MMS, see SubmitMMSMessageData Structure, left blank with only MSISDN and network completed

Submit Email

curl "http://api-endpoint/message/send" -H "Authorization: Bearer Your-Application-Access-Token" -H "Content-Type: application/json" -X POST -d '{"Action":3,"MVNOID":1,"Data":{"message_type":"email","network":"local_email","subject":"My Email Test","address":["me@example.com"],"html":"This is the HTML part","text":"This is the Plaintext part","attachments":[]},"Campaign":"Email Test","PostbackReplyUrl":null,"PostbackStatusUrl":null,"PostBackStatusTypes":null}'

using iliveit.MessagingAPI;
using iliveit.MessagingAPI.Structs;
using iliveit.MessagingAPI.Enums;

APIConfig config = new APIConfig();
config.AccessToken = "Your-Application-Access-Token";
config.Endpoint = "http://api-endpoint";

MessagingAPI api = new MessagingAPI(config);

NewMessage msg = new NewMessage();
msg.Action = APIActionTypes.SubmitEmail;
msg.MVNOID = 1;
msg.Campaign = "Sample Email";

SubmitEmailMessageData msgData = new SubmitEmailMessageData();
msgData.Address.Add("example@example.com");
msgData.Network = "email_network";
msgData.Subject = "Testing Email";
msgData.HTML = "<h1>This is the heading</h1>";
msgData.Text = "This is the heading";
msg.Data = msgData;

APIResult result = api.Create(msg);
Console.WriteLine("Message ID:" + result.MessageResult.MessageID);

 // Not available yet

<?php
require_once(getcwd() . '/iliveit/Iliveit.php');
use Iliveit\IliveitApi;
// This helper method is included in the sample code
$api = Helper::GetApiInstance();

$message = new Iliveit\Service\NewMessage();
$message->Action = 3;
$message->MVNOID = 1;
$message->Campaign = 'PHP Email Test';

// A URL where status updates for this message should be POSTed (optional)
//$message->PostbackStatusUrl = 'http://your.domain.to/postback/to';
// Which updates you want to receive in the postback if PostbackStatusUrl is set
// Possible values of "build", "submit", "archive", "sent", "delivery"
// comma delimited - i.e. "build,submit,delivery"
//$message->PostBackStatusTypes = 'submit,sent,delivery';

$email_data = new Iliveit\Service\SubmitEmailMessageData();
// Even though it's an array, only add a single email address per packet
array_push($email_data->address, 'example@example.com');
// We'll provice you with the correct network to use
$email_data->network = 'email_network';
$email_data->subject = 'My Email PHP Test';
$email_data->html = '<h1>This is the HTML part</h1>';
$email_data->text = 'This is the Plaintext part';

// Attach the email data to the Message
$message->Data = $email_data;

$result = $api->Create($message);
//StatusCode 0 means everything went fine
print_r($result);
?>

The above command returns JSON structured like this:

{
    "MessageID": "returned-message-id-string"
}

Submit Email sends an Email to the specified email address. All parameters are submitted as a single JSON structure.

HTTP Request

POST http://api-endpoint/message/send

JSON Structure

Parameter Value Type Description
Action 3 APIActionTypes An APIActionTypes with value 1 denotes an email message
MVNOID ? int Also known as a client ID. This will be supplied by iLiveIt
Campaign “Sample” string Optional. Your campaign ID. Makes reporting easier by grouping related messages by campaign
PostBackStatusTypes PostBackStatusTypes string (comma delimited) The type of postbacks you wish to receive on PostbackStatusUrl
PostbackStatusUrl “http://your-endpoint” string (url) The location you wish to receive status PostBacks on
Data ? SubmitEmailMessageData The data for the Email, see SubmitEmailMessageData Structure

Retrieve message status

curl "http://api-endpoint/message/:id/status" -H "Authorization: Bearer Your-Application-Access-Token"

> :id Should be the Message ID you received when the message was submitted 

using iliveit.MessagingAPI;
using iliveit.MessagingAPI.Structs;

APIConfig config = new APIConfig();
config.AccessToken = "Your-Application-Access-Token";
config.Endpoint = "http://api-endpoint";

MessagingAPI api = new MessagingAPI(config);

APIResult result = api.GetMessageStatus("your-message-id");
Console.WriteLine(result.MessageStatus)

import(
    "github.com/iliveit/go-messaging-client"
)

apiConfig := messagingapi.APIConfig{
    AccessToken: "Your-Application-Access-Token",
    Endpoint: "http://api-endpoint",
}

api, err := messagingapi.New(apiConfig) 
result, err := api.GetMessageStatus("your-message-id")
fmt.Println(result.MessageStatus)

<?php 
require_once(getcwd() . '/iliveit/Iliveit.php');
use Iliveit\IliveitApi;
// This helper method is included in the sample code
$api = Helper::GetApiInstance();

$result = $api->GetMessageStatus('message_id');
if ($result instanceof Iliveit\Service\MessageStatus)
{
    // Message status fetched
    print_r($result);
}
else echo 'Unable to fetch Message: ' . $result;

?>

The above command returns JSON structured like this:

{
    "type":"message_type",
    "campaign":"campaign_name",
    "message_id":"message-id",
    "template":1,
    "network":"actual submitted network",
    "msisdn":"27000000000",
    "email":"email@example.com",
    "mvno":1,
    "date_received":"2015-01-06T10:20:30Z",
    "build_status":14,
    "build_timestamp":"2015-01-06T10:20:30Z",
    "archive_status":4,
    "archive_timestamp":"2015-01-06T10:20:30Z",
    "submit_status":2,
    "submit_timestamp":"2015-01-06T10:20:30Z",
    "sent_status":1,
    "sent_timestamp":"2015-01-06T10:20:30Z",
    "delivered_status":1,
    "delivered_timestamp":"2015-01-06T10:20:30Z"
}

We provide two methods of retrieving message statuses:

  1. Fetch the message status from the API
  2. PostBacks to your server when the status changes

This will describe the first.

HTTP Request

GET http://api-endpoint/message/:id/status

Constants and Structures

Below is a list of constants used within the API

Constants

APIActionTypes

ActionTypes is the command to execute for the given message request.

Constant Meaning
1 SubmitMMS – Submit an MMS message
2 SubmitSMS – Submit an SMS message
3 SubmitEmail – Submit an Email message
4 Archive – Archive the message

MMSSlideTypes

MMS message slide content types are used when creating slides for an MMS message

Constant Meaning
Text text – Defines a text slide
Image image – Defines an image slide
Video video – Defines a video slide
Audio audio – Defines an audio slide

PostBackStatusTypes

The list of postback types that you can request for a message

Type Meaning
build Received once a video message’s build status changes
submit Received once the messagehas been submitted to our internal messaging backend
archive Received as soon as the message content has been archive. Once this is received, the content gan be retrieved using GET message/:id
sent Received once the message has been submitted to the network
delivery Received when the delivery status of the message changes

Structures

SubmitEmailMessageData structure

Parameter Value Meaning
message_type “email” The type of message to send
address List A list containing email addresses, only a single address is allowed
network “*” The email network to send through, we’ll provide this
subject “string” The subject of your Email message
html “string” The HTML body of the email
text “string” The Text body of the email
attachments List A list of EmailAttachment

EmailAttachment structure

Parameter Value Meaning
filename “string” The filename to display in the email
data “base64 string” The Base64 encoded value of the data to send

SubmitMMSMessageData structure

Parameter Value Meaning
message_type “mms” The type of message to send
msisdn List A list of mobile numbers in international format to send to (excluding ‘+’)
network “*” The mobile network to send to. Use wildcard ‘*’ if you want the API to determine the correct network
subject “string” The subject of your MMS message
slides List A list of MMSSlides to include in the MMS message

MMSSlide structure

Parameter Value Meaning
duration “string” The duration of the slide in seconds
content List A list of MMSSlideContent which specifies all the content of the slide

MMSSlideContent structure

Parameter Value Meaning
type MMSSlideTypes The type of content
mime “string” The official MIME type of the content, eg. “text/plain”, “video/mp4”
data “string” or base64 The base64’d content of the data, or plain text if type if MMSSlideTypes.Text
name “string” The name of the content, eg. “MyVideo.mp4”

Client Libraries

C#

v1.0.3.0 (2021-09-10)
Download now

The C# client library includes everything to work with the API from C#/.NET. See the Getting Started with C# section for more information.

Go

v1.0.2.0 (6c68400930) (2015-06-05)

The Go client library is go-gettable using
go get github.com/iliveit/go-messaging-client

Github

See Getting Started with Go section for more information and how to install.

PHP

v1.0.0.0 (2016-04-08)
Download now

See Getting Started with PHP section for more information and how to install.

curl C# Go PHP