Skip to main content

Spedizioni in batch

Spedire in batch consente di ottimizzare le richieste e velocizzare il processo di invio. A differenza dell'invio multiplo (stesso testo a più contatti), con l'invio in batch è possibile:

  • Personalizzare il testo per ogni contatto
  • Personalizzare callback per le notifiche per ogni contatto
  • Utilizzare i placeholders

Come creare spedizioni in batch

Endpoint: /api/rest/v1/sms-batch.json

Method: POST

Parametri:

  • gateway: (default). Vedi documentazione gateway. Per test usare 99
  • username: Richiesto in base alla configurazione di api_token vedi documentazione
  • send_at: Impostare solamente se si vuole posticipare invio
  • sender: Nome mittente (Potrebbe essere limitato in base alle impostazioni del tuo account)
  • text_template: Testo base, può essere personalizzato utilizzando i placeholder (vedi sezione)
  • delivery_callback: Webhook per la ricevuta di consegna. Può contenere placeholder. Questa può essere sovrascritta per ogni destinazione
  • default_placeholders: Oggetto, sono i valori di default dei placeholder validi per tutte le destinazione.
  • async: boolean, default true. Quando impostato a false si possono creare massimo 100 spedizioni. Se false il limite è 10000.
  • max_sms_length: (facoltativo, numerico). Default è il limite massimo di sms concatenabili. In caso il testo superi il numero massimo la destinazione viene ignorata.
  • utf8_enabled (boolean, facoltativo default true). Se false la destinazione viene ignorata in caso nel testo ci siano caratteri unicode.
  • destinations: (array di oggetti):
    • number: (obbligatorio). Numero a cui spedire. E' possibile indicare più numeri separando con virgola i campi
    • placeholders: (facoltativo) Oggetto con i placeholders da sostituire.
    • delivery_callback: (facoltativo) Se indicato sostituisce il campo delivery_callback comune indicato nel corpo principale.

Placeholders

I placeholders sono stringhe racchiuse da doppie { e }, esempio: {{nomePlaceHolder}}.

text_template

Se si desidera personalizzare l'intero corpo del messaggio è possibile indicare in text_template un unico placeholder, esempio:

invio con messaggio personalizzato per intero
{
"text_template": "{{body}}",
"destinations": [
{
"number": "32112345678",
"placeholders": {
"body": "Testo del messaggio"
}
}
]
}

Esempio invio asincrono:

body richiesta
const request = {
"gateway": 99,
"username": "MIA_USERNAME",
"password": "MIA_PASSWORD",
"send_at": null,
"sender": "MITTENTE",
"text_template": "Ciao {{fullName}}, come stai? Il tuo codice è {{code}}",
"delivery_callback": "https://www.google.com?code={{code}}",
"default_placeholders": {
"code": "0000"
},
"async": true, // valore di default
"max_sms_length": 1,
"utf8_enabled": false,
"destinations": [
{
"number": "+3933311122233,+3933311122234",
"placeholders": {
"fullName": "Santi",
"code": "1234"
}
},
{
"number": "+3933311122235",
"delivery_callback": "https://www.bing.com?q={{code}}",
"placeholders": {
"fullName": "Francesco",
"code": "1234"
}
}
]
}
esempio risposta
{
"async": true,
"error": 0,
"credit": 3041,
"sending_contacts_count": 80,
"sending_batch_id": "21140441168080785"
}

Esempio invio sincrono:

body richiesta
const request = {
"gateway": 99,
"text_template": "{{body}}",
"delivery_callback": "https://www.code.com?res={{res}}",
"async": false,
"destinations": [
{
"number": "+3933311122233,+3933311122234",
"placeholders": {
"body": "Ciao, hai vinto il premio",
"res": "win"
}
},
{
"number": "+3933311122235",
"placeholders": {
"body": "Mi dispiace, non hai vinto, riprova",
"res": "lose"
}
}
]
}
esempio risposta
{
"async": false,
"error": false,
"credit": 2957,
"sending_sms_count": 3,
"sending_contacts_count": 3,
"sending_cost": 3,
"sending_errors_count": 0,
"destinations": [
{
"number": "+3933311122233,+3933311122234",
"queue_id": "21140563372082912",
"sms_count": 2,
"cost": 2,
"delivery_callback": "https://www.code.com?res=win"
},
{
"number": "+3933311122235",
"queue_id": "21140563378006075",
"sms_count": 1,
"cost": 1,
"delivery_callback": "https://www.code.com?res=lose"
}
]
}

Esempi di invio utilizzando vari linguaggi

CURL

Bash (cURL)
curl --location 'https://v2.smsviainternet.it/api/rest/v1/sms-batch.json' \
--header 'X-Api-Token: MyToken' \
--header 'Content-Type: application/json' \
--data '{
"gateway": 0,
"sender": "Mittente",
"text_template": "Ciao {{fullName}}, come stai? Il tuo codice è {{code}}",
"default_placeholders": {},
"async": true,
"max_sms_length": 1,
"utf8_enabled": false,
"destinations": [
{
"number": "+393801234567",
"placeholders": {
"fullName": "Mario Rossi",
"code": "1901"
}
}
]
}'

NodeJS + Axios

NodeJS + Axios
var axios = require('axios');
var data = JSON.stringify({
"gateway": 0,
"sender": "Mittente",
"text_template": "Ciao {{fullName}}, come stai? Il tuo codice è {{code}}",
"default_placeholders": {},
"async": true,
"max_sms_length": 1,
"utf8_enabled": false,
"destinations": [
{
"number": "+393801234567",
"placeholders": {
"fullName": "Mario Rossi",
"code": "1901"
}
}
]
});

var config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://v2.smsviainternet.it/api/rest/v1/sms-batch.json',
headers: {
'X-Api-Token': 'MyToken',
'Content-Type': 'application/json'
},
data
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

GO Lang

GO Lang
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {

url := "https://v2.smsviainternet.it/api/rest/v1/sms-batch.json"
method := "POST"

payload := strings.NewReader(`{
"gateway": 0,
"sender": "Mittente",
"text_template": "Ciao {{fullName}}, come stai? Il tuo codice è {{code}}",
"default_placeholders": {},
"async": true,
"max_sms_length": 1,
"utf8_enabled": false,
"destinations": [
{
"number": "+393801234567",
"placeholders": {
"fullName": "Mario Rossi",
"code": "1901"
}
}
]
}`)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)

if err != nil {
fmt.Println(err)
return
}
req.Header.Add("X-Api-Token", "MyToken")
req.Header.Add("Content-Type", "application/json")

res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}

Python

Python
import requests
import json

url = "https://v2.smsviainternet.it/api/rest/v1/sms-batch.json"

payload = json.dumps({
"gateway": 0,
"sender": "Mittente",
"text_template": "Ciao {{fullName}}, come stai? Il tuo codice è {{code}}",
"default_placeholders": {},
"async": True,
"max_sms_length": 1,
"utf8_enabled": False,
"destinations": [
{
"number": "+393801234567",
"placeholders": {
"fullName": "Mario Rossi",
"code": "1901"
}
}
]
})
headers = {
'X-Api-Token': 'MyToken',
'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

PHP

PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => 'https://v2.smsviainternet.it/api/rest/v1/sms-batch.json',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"gateway": 0,
"sender": "Mittente",
"text_template": "Ciao {{fullName}}, come stai? Il tuo codice è {{code}}",
"default_placeholders": {},
"async": true,
"max_sms_length": 1,
"utf8_enabled": false,
"destinations": [
{
"number": "+393801234567",
"placeholders": {
"fullName": "Mario Rossi",
"code": "1901"
}
}
]
}',
CURLOPT_HTTPHEADER => array(
'X-Api-Token: MyToken',
'Content-Type: application/json'
),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Ruby

Ruby
require "uri"
require "json"
require "net/http"

url = URI("https://v2.smsviainternet.it/api/rest/v1/sms-batch.json")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Token"] = "MyToken"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"gateway": 0,
"sender": "Mittente",
"text_template": "Ciao {{fullName}}, come stai? Il tuo codice è {{code}}",
"default_placeholders": {},
"async": true,
"max_sms_length": 1,
"utf8_enabled": false,
"destinations": [
{
"number": "+393801234567",
"placeholders": {
"fullName": "Mario Rossi",
"code": "1901"
}
}
]
})

response = https.request(request)
puts response.read_body