De API's van MessageBird

De MessageBird API is gemakkelijk te koppelen aan jouw softwarepakket. MessageBird heeft voor de programmeertalen PHP, Java en Python voorbeeld-code (en classes) beschikbaar. Heb je informatie voor andere programmeertalen nodig? Neem dan gerust contact met ons op om dit met één van onze technische medewerkers te bespreken.

SMS aanbieden via HTTP-API

Lees meer Voor veel bedrijven de meest populaire methode om aan te sluiten op onze SMS gateway. Voor onze HTTP-API hebben wij al voorbeelden of classes klaarstaan in onder andere PHP, Java en Python. Daarnaast hebben wij code voorbeelden in ASP, C#, VB.Net, VBA, Perl & Ruby.
Een SMS versturen via onze HTTP-API kan al in één regel.
curl -X GET "https://api.messagebird.com/api/sms?username=[gebruikersnaam]&password=[password]&
destination=[ontvanger(s)]&body=[bericht]&sender=[afzender]"

Documentation

- Klik hier om de SMS HTTP-API documentatie te downloaden.

Pre-built libraries
- PHP Class (GitHub)
- Java Class (GitHub)
- Python Class (GitHub)
- GO Class (GitHub, 3rd party)

Examples
PHP
Java
Python
ASP
C#
VB.Net
Perl
Ruby
GO
<?php
// First, download the PHP class from github (https://github.com/mobiletulip/messagebird-sms-api-php/archive/master.zip)
require_once 'lib/class.MessageBird.php';

// Set the Messabeird username and password, and create an instance of the MessageBird class
$sms = new MessageBird( 'username', 'password' );

// Set the sender, could be an number (16 numbers) or letters (11 characters)
$sms->setSender ( 'YourSender' );

// Add the destination mobile number.
// This method can be called several times to add have more then one recipient for the same message
$sms->addDestination ( '31600000000' );

// Set an reference, optional
$sms->setReference ( '123456789' );

// Set a schedule date-time, optional
// $sms->setTimestamp('2014-01-01 10:02');

// Replace non GSM-7 characters by appropriate valid GSM-7 characters
// $sms->setReplacechars(false);

// If you want a dlr notification of the message send to another url then that you have set on the web site, you can use this parameter. Don't forget to set a reference!
// $sms->setDlrUrl('http://www.example.com/dlr_url.php');

// The message will be send as a voice message and the gateway_id will be overwritten to 8, which is the voice gateway. (Dutch only for the moment)
// $sms->setVoice(true);

// Set the quality of the route that you want to send the message.
// $sms->setGateway('quality');

// If $test is TRUE, then the message is not actually sent or scheduled, and there will be no credits deducted.
// $sms->setTest(true);

// Send the message to the destination(s)
$sms->sendSms ( 'This is a test message' );

echo "\nResponse:";
echo "\n" . $sms->getResponseCode ();
echo "\n" . $sms->getResponseMessage ();
echo "\n";
// First, download the Java class (https://github.com/mobiletulip/messagebird-sms-api-java/archive/master.zip)
import com.messagebird.MessageBirdApi;

public class Example {
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) throws Exception {
        MessageBirdApi smsApi = new MessageBirdApi();

        smsApi.authenticate("username", "password");        // authenticate with MessageBird SMS API

        smsApi.setSender("YourSender");                     // set the name or number from where the message come from
        smsApi.addDestination("31600000001");               // add number to destination list, this function can be called multiple times for more receivers
        smsApi.setReference("123456789");                   // your unique reference

        //smsApi.setTimestamp(2012, 2, 27, 11, 30);         // only use if you want to schedule message
        smsApi.send("This is a test message");              // send the message to the receiver(s)

        System.out.println(smsApi.getResponseCode());       // print out the response code
        System.out.println(smsApi.getResponseMessage());    // print out the response message
    }
}
# First, download the Python class (https://github.com/mobiletulip/messagebird-sms-api-python/archive/master.zip)
# Import the MessageBird Library which will send the message to our server
from MessageBird import MessageBird

# Set the MessageBird username and password, and create an instance of the SmsCity class
smsApi = MessageBird('username', 'password')

# Set the sender, could be an number (16 numbers) or letters (11 characters)
smsApi.setSender('YourSender')

# Add the destination mobile number.
# This method can be called several times to add have more then one recipient for the same message
smsApi.addDestination('31600000000')

# Set an reference
smsApi.setReference('123456789')

# Send the message to the destination(s)
smsApi.sendSms('This is a test message')

# When using in the console, it will show you what the response was from our server
print 'Response:'
print smsApi.getResponseCode()
print smsApi.getResponseMessage()
<%
  username = "your-username"
  password = Server.urlencode("your-api-password")

  body        = "This is a test message"
  body        = Server.urlencode(body) <%-- // encode special characters --%>
  sender      = "YourSender"
  destination = "31600000000" <%-- // more number can be added by seperating them with a comma (,) --%>

  test = 0 <%-- // If test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted. --%>

  api_url     = "http://api.messagebird.com/api/sms"

  request_url = api_url & "?username=" & username & "&password=" & password & "&body=" & body &_
          "&sender=" & sender & "&destination=" & destination & "&test=" & test

  set xmlhttp = CreateObject("MSXML2.ServerXMLHTTP")
  xmlhttp.open "GET", url, false
  xmlhttp.send ""

  msg = xmlhttp.responseText
  response.write(msg)
  set xmlhttp = nothing
%>
void Page_Load(Object Src, EventArgs E) {
    api.Text = readHtmlPage("http://api.messagebird.com/api/sms");
}

private String readHtmlPage(string url)
{
    String username = "your-username";
    String password = "your-api-password";

    String body        = "This is a test message";
    String body        = body; /* encode special characters */
    String sender      = "YourSender";
    String destination = "31600000000"; /* more number can be added by seperating them with a comma (,)  */

    String test = 0; /* If test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted */

    String result = "";
    String strGet = "username=" + HttpUtility.UrlEncode(username) + "&password=" + HttpUtility.UrlEncode(password) +
              "&body=" + HttpUtility.UrlEncode(body) + "&sender=" + HttpUtility.UrlEncode(sender) + "&destination=" + destination + "&test=" + test;

    StreamWriter myRequest = null;
    HttpWebRequest objRequest = (HttpWebRequest)WebRequest.Create(url);

    objRequest.Method = "POST";
    objRequest.ContentLength = Encoding.UTF8.GetByteCount(strGet);
    objRequest.ContentType = "application/x-www-form-urlencoded";
    try{
        myRequest = new StreamWriter(objRequest.GetRequestStream());
        myRequest.Write(strGet);
    }
    catch (Exception e)
    {
        return e.Message;
    }
    finally {
        myRequest.Close();
    }

    HttpWebResponse objResponse = (HttpWebResponse)objRequest.GetResponse();
    using (StreamReader sr = new StreamReader(objResponse.GetResponseStream()) )
    {
        result = sr.ReadToEnd();
        // Close and clean up the StreamReader
        sr.Close();
    }
    return result;
}
Imports System.IO
Imports System.Web

Private Function Send(
    ByVal Body As String, _
    ByVal Sender As String, _
    ByVal Destination As String, _
    ByVal Test As String
) As String

    Const UserName As String = "your-username"
    Const Password As String = "your-api-password"

    Const ApiUrl As String = "http://api.messagebird.com/api/sms"

    Dim strPost As String

    strPost = "username=" + UserName _
       + "&password=" + System.Web.HttpUtility.UrlEncode(Password) _
       + "&body=" + System.Web.HttpUtility.UrlEncode(Body) _
       + "&sender=" + Sender _
       + "&destination=" + Destination _
       + "&test=" + Test

    Dim byteArray As Byte() = Encoding.UTF8.GetBytes(strPost)

    Dim request As WebRequest = WebRequest.Create(ApiUrl)
    request.Method            = "POST"
    request.ContentType       = "application/x-www-form-urlencoded"
    request.ContentLength     = byteArray.Length

    Dim dataStream As Stream = request.GetRequestStream()
    dataStream.Write(byteArray, 0, byteArray.Length)
    dataStream.Close()

    Dim response As WebResponse = request.GetResponse()
    dataStream = response.GetResponseStream()
    Dim reader As New StreamReader(dataStream)
    Dim responseFromServer As String = reader.ReadToEnd()

    reader.Close()
    dataStream.Close()
    response.Close()

    If responseFromServer.Length > 0 Then
        Return responseFromServer
    Else
        Return CType(response, HttpWebResponse).StatusDescription
    End If
End Function
#!/usr/bin/perl -T

use strict;
use LWP::UserAgent;
use HTTP::Request::Common;

my $username = "your-username";
my $password = "your-api-password";

my $body        = "This is a test message";
my $sender      = "YourSender";
my $destination = "31600000000"; # more number can be added by seperating them with a comma (,)

my $test = 0; # If $test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted

my $api_url = "http://api.messagebird.com/api/sms";
my $ua = LWP::UserAgent->new();

my $res = $ua->request
(
 POST $api_url,
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username'    => $username,
                    'password'    => $password,
                    'body'        => $body,
                    'sender'      => $sender,
                    'destination' => $destination,
                    'test'        => $test,
                  ]
);

if ($res->is_error) {
    die "HTTP Error";
}
print "Response:\n\n" . $res->content . "\n\n";
require 'net/http'
require 'uri'

username = "your-username"
password = URI.escape("your-api-password")

body        = "This is a test message"
body        = URI.escape("body")
sender      = "YourSender"
destination = "31600000000" # more number can be added by seperating them with a comma (,)

test = 0 # If test = 1, then the message is not actually sent or scheduled, and there will be no credits deducted

api_url     = "http://api.messagebird.com/api/sms"

request_url = api_url + "?" + "username=" + username + "&password=" + password +
        "&body=" + body + "&sender=" + sender + "&destination=" + destination + "&test=" + test

url = URI.parse(request_url)
full_path = (url.query.blank?) ? url.path : "#{url.path}?#{url.query}"

the_request = Net::HTTP::Get.new(full_path)
the_response = Net::HTTP.start(url.host, url.port) {
    |http|
    http.request(the_request)
}

puts(the_response.body)
The GO library is created by an external author.

The library can be found at: https://github.com/Grovespaz/sms
The documentation can be found at http://godoc.org/github.com/Grovespaz/sms

SMS aanbieden via SMPP

Lees meer Via het SMPP-protocol kan er ook een connectie gemaakt worden met het SMS-platform van MessageBird. Hiervoor dien je zelf eerst een SMPP-account aan te vragen. Je kunt dit doen door contact met ons op te nemen. Onze SMPP-server ondersteunt het SMPP-protocol v3.3 en v3.4.

Configuratie
Voor het configureren van uw SMPP-client dien je de onderstaande instellingen te gebruiken in jouw configuratie.

Server: smpp.messagebird.com
port: 2775
system type: VMA

DCS (data coding scheme) & ESM
De DCS parameter defineert in welke charset/encoding het bericht (en alphanumeric originator) is geëncodeerd. Voor correcte aflevering van de berichtteksten is het van belang dat het DCS correct ingesteld staat.

De ESM parameter defineert wat voor type bericht het is; normale tekst, binary of concatenated (long).


DCS ESM Uitleg
0 0 GSM 03.38 7-bit; text *
0 64/67 GSM 03.38 7-bit; concatenated or binary *
1 0 ISO-8859-1(5) 8-bit; text *
1 64/67 ISO-8859-1(5) 8-bit; concatenated or binary *
3 0 Windows 1252 8-bit; text
3 64/67 Windows 1252 8-bit; concatenated or binary
8 0 Unicode in UTF-16 (16-bit)
8 64/67 Unicode in UTF-16 (16-bit); concatenated

SMS aanbieden via e-mail (Mail2SMS)

Lees meer Met de Mail2SMS dienst wordt een e-mailbericht omgezet naar een SMS-bericht en afgeleverd op het gewenste mobiele nummer. Dit werkt zonder additionele software, rechtstreeks vanuit elk e-mailprogramma.
Voor het versturen van SMS berichten via de Mail2SMS functie maken wij gebruik van het e-mailadres als authenticatie. Voeg als eerste je e-mailadres toe waarvandaan je e-mails naar ons platform wilt sturen op de Mail2SMS instellingen pagina en configureer deze. Na het instellen van je account is het versturen van een SMS heel gemakkelijk:

- Stuur een bericht vanaf het door jou ingestelde e-mailadres bij Mail to SMS instellingen
- Stuur naar: 31612345678@sms.messagebird.com
- Het onderwerp is de afzender die je wenst
- Typ het bericht dat je wilt sturen

Voorbeelden

Begin en einde aangeven van het SMS-bericht

Als je niet de totale inhoud van de e-mail wilt versturen als SMS maar slechts een deel hiervan, dan kun je het begin en het einde van het SMS-bericht in de e-mail aangeven met --begin en/of --end. Enkele voorbeelden vind je hieronder.

Gebruik van --begin en --end
Beste klant,
--begin Dit is het onderdeel van het e-mail bericht wat vervolgens echt verstuurd wordt. --end

Met vriendelijke groet,
MessageBird

Gebruik van alleen --begin
Beste klant,

Hieronder vinth u extra informatie met betrekking tot uw bestelling.
--begin Dit is het onderdeel van het e-mail bericht wat vervolgens echt verstuurd wordt.

Gebruik van alleen --end
Dit is het onderdeel van het e-mail bericht wat vervolgens echt verstuurd wordt.
--end
Met vriendelijke groet,
MessageBird

Versturen naar groepen

Het is ook mogelijk om berichten via Mail2SMS in één keer naar een hele groep te sturen. De naam van de groep waar je heen wilt sturen mag dan alleen letters, cijfers en tekens bevatten (dus geen spaties en vreemde tekens).

Stuur naar: groepsnaam@sms.messagebird.com
Stuur naar: naam-van-een-groep@sms.messagebird.com

SMS ontvangen op een eigen nummer

Lees meer Via MessageBird is het ook mogelijk om SMS te ontvangen (Mobile Originated, MO). Deze kan je lezen op onze website of door laten sturen naar een door jou opgegeven URL.

Je kunt hierbij gebruik maken van je eigen nummer (zogeheten VMN) maar natuurlijk ook van onze publieke nummers.

Download de documentatie voor het ontvangen SMS.


PHP
ASP
Ruby
<?php
    // Receiver of the message (msisdn/phonenumber), e.g. the number you received the message on
    $receiver = $_POST["receiver"];
        
    // Sender of the message (msisdn/phonenumber), e.g. the number that sent you the message
    $sender = $_POST["sender"];
        
    // The received message
    $message = $_POST["message"];
        
    // The time the message was received in our systems (in the timezone that you set in your account)
    $date = $_POST["date"];
        
    // The time in UTC (+00) the message was received in our systems
    $date_utc = $_POST["date_utc"];
        
    // The reference for the incoming message
    $reference = $_POST["reference"];

    // Check if it is a binary message
    if (isset($_POST['type']) and $_POST['type'] === 'binary' and isset($_POST['udh'])) {
        $udh = $_POST['udh'];
    }
<%
    <%-- // Receiver of the message (msisdn/phonenumber), e.g. the number you received the message on --%>
    string receiver = Request.Params["receiver"] ?? string.Empty;

    <%-- // Sender of the message (msisdn/phonenumber), e.g. the number that sent you the message --%>
    string sender = Request.Params["sender"] ?? string.Empty;

    <%-- // The received message --%>
    string message = Request.Params["message"] ?? string.Empty;

    <%-- // The time the message was received in our systems (in the timezone that you set in your account) --%>
    string date = Request.Params["date"] ?? string.Empty;

    <%-- // The time in UTC (+00) the message was received in our systems --%>
    string date_utc = Request.Params["date_utc"] ?? string.Empty;

    <%-- // The reference for the incoming message --%>
    string reference = Request.Params["reference"] ?? string.Empty;
%>
# Receiver of the message (msisdn/phonenumber), e.g. the number you received the message on
receiver = params[:receiver]

# Sender of the message (msisdn/phonenumber), e.g. the number that sent you the message
sender = params[:sender]

# The received message
message = params[:message]

# The time the message was received in our systems (in the timezone that you set in your account)
date = params[:date]

# The time in UTC (+00) the message was received in our systems
date_utc = params[:date_utc]

# The reference for the incoming message
reference = params[:reference]

SMS ontvangen op een eigen keyword

Lees meer Documentatie voor het ontvangen (MO) van SMS-verkeer op jouw keyword of eigen shortcode.
Doorsturen naar URL

Zodra er een bericht binnenkomt dat aan jouw keyword is gekoppeld, kunnen wij deze direct doorsturen naar de door jouw opgegeven URL. Dit gaat middels een HTTP-request naar jouw platform. We sturen de benodigde gegevens in GET- of POST-variabelen. Je kunt de URL instellen bij jouw keywordinstellingen.

Voorbeeld van een door jou opgegeven URL:
http://www.uwsite.nl/sms/incoming.php

Wij vragen de URL bijvoorbeeld op deze manier op:
http://www.uwsite.nl/sms/incoming.php?shortcode=1008&keyword=EXAMPLE&message=Example&originator=31612345678&operator=02F440&receive_datetime=20140418214656&mid=9000123

Meer informatie over de parameters vindt je onderaan dit blok.

Verwachte response
Als antwoord op de HTTP-request (de zogenaamde response) verwacht ons systeem het woordje'OK' (zonder quotes of HTML-code). Als uw systeem geen 'OK' terug geeft zal ons platform de aanvraag herhaald opnieuw proberen te sturen. Let op dat deze check hoofdletter gevoelig is.

Hierna kun je bijvoorbeeld het bericht in jouw database opslaan, of gegevens op basis van het bericht uit jouw database halen en een SMS-bericht terug sturen via onze (premium) SMS-gateway


ParameterUitleg
shortcode Het verkorte nummer waar de consument de SMS heen heeft gestuurd
keyword Het keyword dat gebruikt is
message Het volledige bericht (inclusief het keyword) dat de consument heeft gestuurd
originator Het telefoonnummer van de consument (inclusief landcode)
mid MO message-ID, deze ID is nodig bij het reageren op een inkomend bericht
subscription Alleen bij abonnementsdiensten: kijkt of het bericht voor een aanmelden/afmeldig van abonnementsdienst is. Als in het bericht ON/ AAN, OFF/UIT of OK/JA als woord na het keyword is (of het laatste woord) dan gaat het waarschijnlijk om een aan- of afmelding voor een abonnementsdienst. Wij sturen als hulpmiddel dan de parameter 'subscription' met de waarden 'on', 'off' of 'ok' mee. Let op: als uw abonnementsdienst gratis is dan is OK niet verplicht.
receive_datetime Tijdstip waarop het bericht is ontvangen bij de operator. Format: YYYYMMDDhhmmss

SMS afleverrapportages ontvangen

Lees meer Als je gebruik maakt van onze HTTP-API bieden wij je ook de mogelijkheid om afleverrapportages te ontvangen. Hierin wordt de status van het verzonden SMS-bericht weergegeven.

Bij de instellingen van je account kan je aangeven naar welke URL wij deze afleverrapportages moeten sturen. Reageert je server even niet? Dan proberen wij het gedurende 24 uur 10 maal.

Let op: wij versturen alleen een DLR wanneer de reference bij het verstuurde bericht is meegegeven.

Download de afleverrapportages documentatie (hoofdstuk 6)


PHP
ASP
Ruby
<?php
    // This msisdn/phonenumber of the receiver of the SMS message
    $gsm = $_GET['GSM'];

    // The status of the SMS message, possible values are: delivered, not delivered, buffered
    $status = $_GET['STATUS'];

    // The reference of the message that you provided upon sending the message
    $reference = $_GET['REFERENCE'];
<%
    <%-- // This msisdn/phonenumber of the receiver of the SMS message --%>
    string gsm = Request.Params["GSM"] ?? string.Empty;

    <%-- // The status of the SMS message, possible values are: delivered, not delivered, buffered --%>
    string status = Request.Params["STATUS"] ?? string.Empty;

    <%-- // The reference of the message that you provided upon sending the message --%>
    string reference = Request.Params["REFERENCE"] ?? string.Empty;
%>
# This msisdn/phonenumber of the receiver of the SMS message
gsm = params[:GSM]

# The status of the SMS message, possible values are: delivered, not delivered, buffered
status = params[:STATUS]

# The reference of the message that you provided upon sending the message
reference = params[:REFERENCE]

HLR-lookup (Network Query)

Lees meer Met deze API kunt u een Network Query doen. Hiermee kan er realtime gekeken worden tot welke operator een mobiel nummer (MSISDN) behoort en of het nummer actief is.

Een Network Query kan gedaan worden op het mobiele netwerk. Hiermee kan er real-time gekeken worden tot welke operator een mobiel nummer (MSISDN) behoort. Deze dienst wordt ook wel "Network Look-up Service" of "HLR lookup" genoemd. Een Network Query kan bijvoorbeeld handig zijn om erachter te komen bij welke operator een geporteerd nummer (Mobile Number Portability, MNP) hoort om zo de goedkoopste SMS-routering te gebruiken.


Aanvragen van HLR
Voor een request verstuur je de volgende aanvraag (voorbeeld):
https://api.messagebird.com/api/hlr/?username=[username]&password=[password]&recipients=[recipient]&reference=[reference]

Geef optioneel een eigen referentie mee, deze wordt later gebruikt om het resultaat bij je systeem te melden. Je kunt een URL opgeven op de API instellingen pagina waar wij de HLR-resultaten heen moeten sturen.

De kosten voor een HLR zijn 0.25 credits per nummer

Ontvangen van het HLR-resultaat
Na enige tijd (enkele seconden tot een minuut) ontvang je op de URL die je hebt ingesteld op de instellingen-pagina een aanvraag terug met daarin de netwerkinformatie van het opgevraagde nummer.

Terugkoppeling van HLR-resultaat:
http://www.your-domain.com/sms/hlr.php?reference=123456789&recipient=31612345678&status=60&network=204160
De status-parameter die je ontvangt bij de rapportage, correspondeert met een van de volgende statussen:
  • 60 - aanvraag gelukt
  • 61 - aanvraag gelukt, MSISDN/recipient afwezig
  • 62 - aanvraag gelukt, MSISDN/recipient bestaat niet
  • 69 - aanvraag gefaald

De network-parameter is de 'mobile network code' (MNC), een volledige lijst met mobile network codes is te vinden op deze Wikipedia-pagina.

Tegoed opvragen

Lees meer Met deze API kunt u de status van uw tegoeden realtime opvragen.
Onze API werkt middels een HTTP-request. Wanneer u een HTTP-request naar onze server stuurt, kunt u met behulp van POST- of GET-variabelen de waarden meesturen. Gebruik onderstaande URL voor het opvragen van uw creditstegoed:

https://api.messagebird.com/api/credits/?username=[username]&password=[password]

Verwerken van de response
Uit deze aanvraag komt het volgende resultaat (voorbeeld):
<response>
    <item>
        <credits>1300</credits>
    </item>
</response>
De status codes bij een verkeerde request sluiten aan bij de SMS-API documentatie.

Klik hier om de SMS HTTP-API documentatie te downloaden.