Utvecklare

RESTful SMS 2.0

Introduktion

Här hittar du allt du behöver för att koppla vårt RESTful SMS 2.0 API till ditt system eller applikation.

Vårt SMS API låter dig koppla upp dina webbtjänster och applikationer mot mobiloperatörer världen över och är designat för att hantera höga volymer av SMS-trafik och lämpar sig perfekt för bland annat större grupputskick vid exempelvis marknadsföring, men även singelutskick för automatiserade SMS-larm etc.

Skapa konto

För att komma igång behöver du först och främst ett konto, vilket du kan skapa här.

När du skapat ditt konto loggar du in i vår användarportal för att få tillgång till dina autentiseringsuppgifter, som beskrivs närmare i steget nedan.

Autentisering

Alla våra API endpoints är skyddade av autentisering via HTTP Bearer tokens, som vi tillhandahåller. Varje konto du skapar kan ha flera nycklar med olika restriktioner på tillåtna IP-adresser som du själv anger. API-nycklarna hanterar du i vår Användarportal.

Paginering

Alla endpoints som returnerar en samling av dokument (Batcher, meddelanden etc.) har paginering aktiverat. Vi använder oss av databas-stilen av paginering med start, limit och order som parameternamn. start, limit och order är sätt till 0, 50 och ASC i respektive ordning, men du kan ändra dem genom att ange dem som query-parametrar när du gör ett HTTP-anrop på detta vis: ?start=0&limit=200&order=DESC

Länk-huvud

Du kommer också ta emot ett länk-huvud som innehåller paginerings-information.

Link: <https://api.ip1sms.com/v2/batches?start=201&limit=100&order=ASC> rel="next",
<https://api.ip1sms.com/v2/batches?start=4901&limit=100&order=ASC> rel="last"
                        

Detta exempel innehåller radbryt för läsbarhetens skull.

Möjliga värden för rel är följande:

Registrera avsändare

Innan du kan använda vårt API behöver du registrera en eller flera avsändare. Du kan ha så många avsändare du vill och du kan sedan avregistrera de du inte behöver.

Läs registrerade avsändare

Endpoint: GET me/senders

Denna endpoint listar alla dina registrerade avsändare som är knutna till ditt konto, sorterade i alfabetisk ordning.

Registrera en avsändare

Endpoint: PUT me/senders/{sender}

Denna endpoint tillåter dig att registrera en ny avsändare.

Avregistrera en avsändare

Endpoint: DELETE me/senders/{sender}

Den här endpointen låter dig avregistrera en avsändare. Outputen är densamma som vid registrering av avsändare.

Responsdata-typ

{
    "sender": "TestNOS",
    "created": "2018-10-23T17:43:19Z"
}
                        

Du kan också registrera och ta bort avsändare via vår webbapplikation Capacity SMS.

Kodexempel

• C#
• PHP
• Visual Basic

                                      
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("https://api.ip1sms.com/v2/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "API Key");

    var sms = new
    {
        sender = "iP1",
        recipients = new string[] { "46712345678" },
        body = "Test Message",
        type = "sms",
        datacoding = "gsm",
        priority = 1,
        reference = "Test"
    };

    StringContent content = new StringContent(JsonConvert.SerializeObject(sms), Encoding.UTF8, "application/json");
    HttpResponseMessage response = await client.PostAsync("batches", content);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                                    
                                

                                      
$conf = array(
    'password' => 'API key',
    'apiUrl' => 'api.ip1sms.com/v2/',
    'method' => 'POST',
    'endpoint' => 'batches',
);

$message = array(
    "sender" => "iP1",
    "recipients" => ["46712345678"],
    "body" => "Test message rest v2",
    "type" => "sms",
    "datacoding" => "gsm",
    "priority" => 1,
    "reference" => "Test",
    "tags" => ["Test SMS"],
);

$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Bearer '.$conf['password'],
            'Content-Length: ' . strlen($jsonEncodedMessage)
        ),
        'method'  => $conf['method'],
        'content' => $jsonEncodedMessage,
    )
);

$url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context  = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
                                    
                                

                                      
Dim client As New HttpClient()

client.BaseAddress = New Uri("https://api.ip1sms.com/v2/")
client.DefaultRequestHeaders.Accept.Clear()
client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Bearer", "Insert API Key Here")

Dim sms As New With
{
    Key .sender = "iP1sms",
    Key .recipients = New List(Of String)() From {"46712345678"},
    Key .body = "Test",
    Key .type = "sms",
    Key .datacoding = "gsm",
    Key .priority = 1
}

Dim content = New StringContent(JsonConvert.SerializeObject(sms), Encoding.UTF8, "application/json")
    Dim response As HttpResponseMessage = Await client.PostAsync("batches", content)

                                    
                                

Statuskoder

Nedan hittar du samtliga statuskoder för RESTful 2.0. Statuskoderna är uppdelade i 4 olika grupper:

Info

Informativa statusar som talar of vart SMS:et befinner sig innan det når mottagarens telefon.

Success

Talar om SMS:ets slutgiltiga status.

Rejection

Talar om ifall något i själva meddelandet är fel, exempelvis längden, spärrade nyckelord etc.

Error

Talar om ifall meddelandet är olevererbart eller andra tekniska fel.

Statusgrupp Info

Statusgrupp Success

Statusgrupp Rejection

Statusgrupp Error

RESTful SMS 1.0

Introduktion

Här hittar du allt du behöver för att koppla vårt RESTful SMS API 1.0 till ditt system eller applikation. Med hjälp av ett SMS API kan du enkelt skräddarsy dina egna SMS-funktioner.

Autentisering

HTTP Basic Läs mer om HTTP Basic Authentication här

Alla requester till vårt RESTful SMS API 1.0 kräver autentisering med dina kontouppgifter. Vi använder oss av autentisering via Konto-ID och API-nyckel genom HTTP Basic. Dessa uppgifter kan du hitta genom att logga in i vår Användarportal.

För att skapa din Basic Authentication sträng, ta ditt kontonummer (ex. ip1-12345) och din API-nyckel (ex. cCnbXFfyTM5BTKh7uNV#tz) och kör dem genom en Base64 encoder i följande format: ip1-12345:CnbXFfyTM5BTKh7uNV

Du bör få ut en sträng som ser ut ungefär så här: aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==

Du har nu genererat din HTTP Basic Authentication-sträng, som du sedan anger som en HTTP header på följande sätt:

Authorization: Basic aXAxLTEyMzQ1OkNuYlhGZnlUTTVCVEtoN3VOVg==

HTTP Bearer Läs mer om HTTP Bearer Authentication här

Du kan också autentisera viaHTTP Bearer tokens, som vi tillhandahåller. Varje konto du skapar kan ha flera nycklar med olika restriktioner på tillåtna IP-adresser som du själv anger. Dessa API-nycklar hanterar du i vår Användarportal.

Anropsstruktur

För varje anrop som görs rekommenderar vi en maxmängd på 500 mottagare/anrop. Vid större mottagarlistor rekommenderar vi att dela upp antalet mottagare i flera anrop med max 500 mottagare i varje.

api.ip1sms.com är den URL som ligger som bas för samtliga API-anrop är och nås via HTTPS och kan användas på följande sätt:

https://api.ip1sms.com

Resten av ovannämnda URL är olika för olika anrop och kallas för anropets URI. En URI pekar i de flesta fall till en entitet eller samling av det som anropats (ex. api/contacts pekar på en samling av kontakter). HTTP verbet förtydligar operationen som behöver göras på målet (ex. GET läser och POST skapar).

Kodexempel

Kodexempel med HTTP Basic Autentisering

• C#
• PHP
• VB

                                          
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("https://api.ip1sms.com/api/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));

    var sms = new OutgoingSMS()
    {
        From = "iP1",
        Numbers = new List() { "46123456789" },
        Contacts = new List(),
        Groups = new List(),
        Message = "test",
        Prio = 1,
        Email = false
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("sms/send", sms);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                                        
                                    

                                          
$conf = array(
    'account' => 'ip1-xxxxx',
    'password' => 'apiKey',
    'apiUrl' => 'api.ip1sms.com',
    'method' => 'POST',
    'endpoint' => '/api/sms/send',
);

$message = array(
    'Numbers' => ['4673055555'],
    'From' => 'iP.1',
    'Message' => "Test message via iP.1's REST API",
);

$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
            'Content-Length: ' . strlen($jsonEncodedMessage)
        ),
        'method'  => $conf['method'],
        'content' => $jsonEncodedMessage,
    )
);

$url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context  = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
                                        
                                    

                                          
Dim account As String = "ip1-xxxxxx"
Dim password As String = "API-Key"

Dim client As New HttpClient()

client.BaseAddress = New Uri("https://api.ip1sms.com/api/")
client.DefaultRequestHeaders.Accept.Clear()
client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))

Dim authString As String = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{account}:{password}"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", authString)

Dim sms As New With
    {
        Key .From = "iP1sms",
        Key .Numbers = New List(Of String)() From {"46123456789"},
        Key .Contacts = New List(Of Integer)(),
        Key .Groups = New List(Of Integer)(),
        Key .Message = "Test", Key .Email = False
    }

Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("sms/send", sms)


End Sub`;
                                        
                                    

RESTful SMS Survey 1.0

Beskrivning

Vårt SMS Survey API låter dig skicka undersökningar via SMS. Perfekt för att automatisera kundundersökningar, vid exempelvis ordrar eller andra typer av registreringar. Du kan enkelt skapa, skicka och hantera enkäter direkt via API:et.

Kodexempel

• C#
• PHP
• VB

                                          
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("https://api.ip1sms.com/api/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));

    var survey = new OutgoingSurvey()
    {
        From = "iP1",
        Numbers = new List() { "46123456789" },
        Contacts = new List(),
        Groups = new List(),
        Message = "test survey",
        Prio = 1,
        Email = false
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("surveys/{survey}/send", survey);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Survey Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                                        
                                    

                                          
$conf = array(
    'account' => 'ip1-xxxxx',
    'password' => 'apiKey',
    'apiUrl' => 'api.ip1sms.com',
    'method' => 'POST',
    'endpoint' => '/surveys/{survey}/send',
);

$message = array(
    'Numbers' => ['4673055555'],
    'From' => 'iP.1',
    'Message' => "Test message via iP.1's REST API",
);

$jsonEncodedMessage = json_encode($message);
// Set up request options
$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
            'Content-Length: ' . strlen($jsonEncodedMessage)
        ),
        'method'  => $conf['method'],
        'content' => $jsonEncodedMessage,
    )
);

$url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context  = stream_context_create($options);
// Send the request
$response = file_get_contents($url, false, $context);
// Print the response
echo $response;
                                        
                                    

                                          
Dim account As String = "ip1-xxxxxx"
Dim password As String = "API-Key"

Dim client As New HttpClient()

client.BaseAddress = New Uri("https://api.ip1sms.com/api/")
client.DefaultRequestHeaders.Accept.Clear()
client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json"))

Dim authString As String = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{account}:{password}"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", authString)

Dim survey As New With
    {
        Key .From = "iP1sms",
        Key .Numbers = New List(Of String)() From {"46123456789"},
        Key .Contacts = New List(Of Integer)(),
        Key .Groups = New List(Of Integer)(),
        Key .Message = "Test", Key .Email = False
    }

Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("surveys/{survey}/send", survey)


End Sub`;
                                        
                                    

RESTful 2FA

Beskrivning

Genom att koppla på 2FA vid exempelvis registrering av nya konton kan du enkelt säkerställa att personen har angivit rätt uppgifter genom att bekräfta användarens telefonummer. Koden skickas som ett SMS till angivet nummer på nolltid.

När du integrerar tvåfaktorsautentisering via SMS från iP.1 får du automatisk tillgång till vår globala spamfilterlista som innehåller tusentals virtuella nummersom använts vid illasinnade bot-registreringar.

Kodexempel

                                                
$conf = array(
    'account' => 'ip1-XXXXX',
    'password' => 'APIKey',
    'apiUrl' => 'api.ip1sms.com',
    'endpoint' => '/api/authentications',
    'method' => 'POST'
    );
    
$message = array(
    'Phone' => '46712345678',
    'From' => 'iP1sms',
    'MessageFormat' => 'Använd denna kod för att verifiera: {0}',
    'Length' => '6',
    'ExpirationTime' => '1200'
);

$jsonEncodedMessage = json_encode($message);


$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
            'Content-Length: ' . strlen($jsonEncodedMessage)
        ),
        'method'  => $conf['method'],
        'content' => $jsonEncodedMessage,
    )
);

$Url = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context  = stream_context_create($options);

$response = file_get_contents($SendUrl, false, $context);

echo $response;
                                                
                                            

                                                
$submittedCode = $_POST["code"]; // e. g. 453342

$conf = array(
    'account' => 'ip1-XXXXX',
    'password' => 'APIKey',
    'apiUrl' => 'api.ip1sms.com',
    'endpoint' => '/api/authentications/validate',
    'method' => 'POST'
    );

$validate = array(
    'Phone' => '46712345678',
    'Code' => $submittedCode
);

$jsonEncodedValidation = json_encode($validate);

$options = array(
    'http' => array(
        'header'  => array(
            'Content-Type: application/json',
            'Authorization: Basic '. base64_encode($conf['account'].":".$conf['password']),
            'Content-Length: ' . strlen($jsonEncodedValidation)
        ),
        'method'  => $conf['method'],
        'content' => $jsonEncodedValidation,
    )
);

$ValidationUrl = "https://" . $conf['apiUrl'] . $conf['endpoint'];
$context  = stream_context_create($options);

$response = file_get_contents($ValidationUrl, false, $context);

echo $response;
                                                
                                            

                                                
using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("http://api.ip1sms.com/api/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));

    var authentication = new AuthenticationDTO()
    {
        Phone = "46712345678",
        From = "iP1sms",
        MessageFormat = "Använd {0} för att verifiera dig",
        Length = "6"
        ExpirationTime = "1200"
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("authentications", authentication);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                                                
                                            

                                                
string submittedCode = Console.ReadLine(); // e. g. 453342

using (var client = new HttpClient())
{
    client.BaseAddress = new Uri("http://api.ip1sms.com/api/");
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes(string.Format("{0}:{1}", "ip1-xxxxx", "API-Key"))));

    var validation = new AuthenticationValidationRequest()
    {
        Phone = "46712345678",
        Code = submittedCode,
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("authentications/validate", validation);

    if (response.IsSuccessStatusCode)
    {
        Console.Log("Validated");
    }
    else
    {
        Console.Log("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
                                                
                                            

Statuskoder

Nedan hittar olika statuskoder för både HTTP-anrop samt status på SMS.

Statuskoder HTTP

Statuskoder SMS

SMS Gateway (Soap) Deprecated

Kodexempel

                            
$conf['apiurl'] = 'https://web.smscom.se/sendsms/sendsms.asmx?wsdl';
$conf['mmsapiurl'] = 'https://web.smscom.se/mms/mms.asmx?wsdl';
$conf['account'] = 'ip1-xxxxx';  
$conf['password'] = 'API-Key'; 

$conf['to'] = '46712345678'; 
$conf['from'] = 'iP1';
$conf['prio'] = '1';
$conf['msg'] = 'Test message via iP.1 API (Web Service)';
$conf['msg_at'] = "Test send at message via iP.1 API (Web Service)";
$conf['msg_bundle'] = "Test bundle message via iP.1 API (Web Service)";

$client = new SoapClient($conf['apiurl']);
$mmsClient = new SoapClient($conf['mmsapiurl']);

$result = $client->balans(array('konto'=>$conf['account'], 'passwd' => $conf['password']));
echo 'Balnace: ' . $result->balansResult;

$smsresult = $client->sms(array('konto'=>$conf['account'], 'passwd' => $conf['password'], 'till' => $conf['to'], 'from' => $conf['from'], 'meddelande' =>$conf['msg'], 'prio' => $conf['prio']));

echo 'Result of SMS: ' . $smsresult->smsResult;
                            
                        

SMS Gateway (http) Deprecated

Kodexempel

                            
$conf['account'] = 'ip1-xxxx';  
$conf['password'] = 'api-key'; 
$conf['apiurl'] = 'https://web.smscom.se/sendsms.aspx';

$conf['to'] = '4673055555';     
$conf['from'] = 'iP.1';        
$conf['msg'] = 'Test message via iP.1 HTTP Request';       
$conf['prio'] = '1';

$data = http_build_query(array('acc'=>$conf['account'],'pass'=>$conf['password'],'msg'=>  $conf['msg'],'from'=>$conf['from'],'to'=> $conf['to'],'prio'=>$conf['prio'], 'type' => ''));
        

$opts = array('http' =>
    array(
        'method'  => 'GET',
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'content' => $data
    )
);

$context  = stream_context_create($opts);            
$result = file_get_contents($conf['apiurl'] . '?' . $data, false, $context);

echo 'Result/SMS ID: ' . $result;