Informazioni di base
In questa pagina presentiamo alcuni esempi di utilizzo dell'API per semplificare la comprensione dell'utilizzo della stessa in diversi casi specifici.
Autenticazione
L'autenticazione avviene con la chiave X-API-Key che va inserita nell'header della chiamata.
Crea una chiave per le API direttamente dalla tua area riservata dalla sezione "App e Integrazioni" ( https://app.nifteem.com/integration )
Base url
L'indirizzo base di tutte le chiamate è il seguente:
https://api.nifteem.com/v1/api
SMS standard
Inviando il body JSON riportato sotto vengono inviati 2 SMS ai due numeri +39340XXXXXX1 e +39340XXXXXX2 presenti come recipientIdentifiers all'interno dell'elemento recipients .
Il placeholder {{fistname}} presente nella proprietà body dell'oggetto text viene rimpiazzato con il valore della proprietà firstname all'interno dell'oggetto placeholders che è sempre contenuto in ogni elemento dell'array di recipients. Il nome del placeholder e il nome della proprietà devono corrispondere tra di loro ma il nome del placeholder può essere scelto liberamente.
Nell'oggetto options si trovano alcune opzioni generali da utilizzare per l'invio. All'interno di options ci sono opzioni generali e opzioni specifiche per canale. In questo caso è presente l'oggetto sms che tramite la proprietà senderId specifica il mittente del messaggio. L'ID dell'alias SMS da indicare come valore può essere reperito direttamente dal pannello di controllo dalla sezione Impostazioni -> SMS (https://app.nifteem.com/channel/sms) .
Nel caso di esempio nell'oggetto options sono indicate anche le proprietà countryCodeFixEnabled impostata a 'true' e countryCodeDefault impostata a 'IT': con queste opzioni nel caso i numeri di destinazione risultino non validi il sistema proverà a renderli validi aggiungendo in testa il prefisso internazionale della country IT.
Attenzione: Questa opzione può aiutarti a sistemare automaticamente i numeri ma può anche in taluni casi generare dei numeri errati. Utilizza questa opzione considerando le casistiche presenti nel tuo database di numeri.
[POST] https://api.nifteem.com/v1/api/dispatch
{
"message": {
"languageDefault": "en",
"translations": {
"en": {
"contents": [
{
"text": {
"body": "Hello {{firstname}}!
This is a simple SMS test."
}
}
]
}
}
},
"recipients": [
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "+39340XXXXXX1"
}
],
"placeholders": {
"firstname": "Mark"
}
},
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "+39340XXXXXX2"
}
],
"placeholders": {
"firstname": "Robert"
}
}
],
"options": {
"sms": {
"senderId": "0GRA9Z4DXXXXX"
},
"countryCodeFixEnabled": true,
"countryCodeDefault": "IT"
}
}
RCS testo con SMS fallback
L'esempio seguente è molto simile all'esempio "SMS standard" ma essendo specificata anche la proprietà senderId in questo caso dell'oggetto rcs sempre in options viene utilizzato il canale RCS se il dispositivo di ricezione è compatibile, altrimenti viene utilizzato il canale di fallback SMS inviando quindi al destinatario un SMS standard.
[POST] https://api.nifteem.com/v1/api/dispatch
{
"message": {
"languageDefault": "en",
"translations": {
"en": {
"contents": [
{
"text": {
"body": "Hello {{firstname}}! This is
a simple RCS with SMS fallback test."
}
}
]
}
}
},
"recipients": [
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "+39340XXXXXX1"
}
],
"placeholders": {
"firstname": "Mark"
}
},
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "+39340XXXXXX2"
}
],
"placeholders": {
"firstname": "Robert"
}
}
],
"options": {
"sms": {
"senderId": "0GRA9Z4DXXXXX"
},
"rcs": {
"senderId": "0HK1QV51XXXXX"
}
}
}
RCS testo specifico con SMS fallback
L'esempio seguente è molto simile all'esempio "RCS testo con SMS fallback" ma in questo caso il sul canale RCS viene inviato un contenuto specifico utilizzando l'oggetto channelContents con la relativa proprietà rcs all'interno della quale con l'oggetto text viene specificato un testo specifico per il canale.
[POST] https://api.nifteem.com/v1/api/dispatch
{
"message": {
"languageDefault": "en",
"translations": {
"en": {
"contents": [
{
"text": {
"body": "Hello {{firstname}}! this
is a reminder for your appointment
on {{date}} at {{time}}.
Call us at +39 02 000XXXXX"
}
}
],
"channelContents": {
"rcs": [
{
"text": {
"body": "Hello {{firstname}}, this
is a reminder for your appointment
on {{date}} at {{time}}
with {{doctorname}} at {{location}}.
Please arrive 10 minutes early.
Need to reschedule or have questions?
Call us at +39 02 000XXXXX .
See you soon!"
}
}
]
}
}
}
},
"recipients": [
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "+39340XXXXXX1"
}
],
"placeholders": {
"firstname": "Mark",
"date": "14/02/2025",
"time": "14:14",
"doctorname": "Dr. John Smith",
"location": "Via Roma, 48 - Milano"
}
}
],
"options": {
"sms": {
"senderId": "0GRA9Z4DXXXXX"
},
"rcs": {
"senderId": "0HK1QV51XXXXX"
}
}
}
Invio di template con placeholders
L'esempio seguente mostra come inviare un template creato precedentemente nell'area riservata e che viene inviato personalizzando i placeholder (segnaposto) del messaggio.
In questo caso al posto dell'oggetto message viene indicato l'oggetto template che ha come unica proprietà il campo id che dovrà contenere l'identificatico del template reperibile nella pagina di configurazione del template stesso.
Nell'esempio il template contiene 3 segnaposto {{firstname}}, {{date}} e {{time}} che vengono dinamicamente sostituiti con i valori delle proprietà dell'oggetto placeholders.
Si può notare che in questo caso nell'oggetto options non vanno specificati i mittenti o alias dei messaggi in quanto il template stesso definisce il contenuto ed i mittenti da utilizzare per ogni canale.
[POST] https://api.nifteem.com/v1/api/dispatch
{
"template": {
"id": "0JKMTJEGXXXXX"
},
"recipients": [
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "39347XXXXXX1"
}
],
"placeholders": {
"firstname": "Mark",
"date": "31/01/2025",
"time": "14:14"
}
}
],
"options": {
"countryCodeFixEnabled": true,
"countryCodeDefault": "IT"
}
}
Invio di template multilingua
L'esempio seguente mostra come inviare un template creato precedentemente nell'area riservata che contiene la versione del contenuto sia in Italiano che in Inglese.
Nell'esempio ci sono due destinatari specificati nell'oggetto recipients ed in particolare per ogni destinatario è stata specificata la lingua preferenziale utilizzando la proprietà language.
Ogni destinatario riceverà quindi, se disponibile, la versione del template nella propria lingua in caso questa non sia disponibile verrà invita la versione con lingua di default specificata per il template stesso.
[POST] https://api.nifteem.com/v1/api/dispatch
{
"template": {
"id": "0JKN4F54XXXXX"
},
"recipients": [
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "39347XXXXXX1"
}
],
"language": "en",
"placeholders": {
"pin": "123456"
}
},
{
"recipientIdentifiers": [
{
"channelIdType": "MSISDN",
"channelIdentifier": "39347XXXXXX2"
}
],
"language": "it",
"placeholders": {
"pin": "987654"
}
}
],
"options": {
"countryCodeFixEnabled": true,
"countryCodeDefault": "IT"
}
}
