Language

Italiano English Français

RavenWeb API

Invio SMS Singolo

Attraverso questa tipologia di invio sarà possibile inviare un singolo messaggio verso un numero di telefono cellulare.

URL di riferimento : http://gateway.airtelco.com/raven/sms/send

Esempio :

               http://gateway.airtelco.com/raven/sms/send?login=LOGIN&password=PASSWORD
                             &phone=%2b393330000000&from=Mittente&body=Testo

Parametri

  • login

Identificativo dell'account, fornito all'atto dell'attivazione del servizio.

  • password

Password dell'account, fornita all'atto dell'attivazione del servizio.

  • from

Parametro non obbligatorio. Il valore di questo parametro sarà visualizzato come mittente del messaggio.

  • body

Il valore di questo parametro sarà utilizzato come corpo del messaggio.

  • phone

Parametro obbligatorio. Indica il destinatario del messaggio.

Il numero telefonico deve essere nel formato internazionale : +[prefisso internazionale][prefisso operatore][numero telefonico] Esempio : +393330000000

  • quality

Parametro non obbligatorio. Indica la qualità del messaggio. Nel caso in cui il parametro quality non venga valorizzato sarà utilizzata la qualità Premium.

Valori possibili : p (Qualità Premium), s (Qualità Standard)

  • action

Parametro non obbligatorio nell'Invio Singolo. Nel caso in cui non venga valorizzato sarà utilizzata l'azione di default sms.

  • type

Parametro non obbligatorio. Indica la tipologia del messaggio che si sta inviando.

Valori possibili : text, ucs, long, lucs, binary, wappush, int

Il valore di default è text.

  • encoding

Parametro non obbligatorio. E' possibile specificare l'encoding utilizzato dal client.

Valori possibili : latin-1, utf8.

Nel caso in cui non venga valorizzato sarà utilizzato l'encoding di default.

  • url

Parametro obbligatorio per sms di tipo wappush. Indica l'URL che sarà utilizzato per la creazione del messaggio WAP PUSH.

  • udh

Parametro obbligatorio per sms di tipo binary. Indica il valore del campo User Data Header del messaggio ad 8bit che sarà inoltrato al cellulare.

Descrizione dei valori possibli del parametro type

  • text

Messaggio testuale (7bit) da 160 caratteri

  • ucs

Messaggio unicode da 70 caratteri. Per inviare messaggi di tipo Unicode è necessario convertire ogni carattere del testo del messaggio con il corrispettivo valore unicode esadecimale. (Utilizzando questa modalità sarà possibile inviare testi che contengono caratteri non supportati dall'alfabeto GSM, come ad esempio gli ideogrammi giapponesi.)

Esempio : per il testo “AABB” il valore del campo body dovrà essere “41414242”

  • long

Messaggio long. Permette di inviare messaggi testuali con più di 160 caratteri in un'unica richiesta. Ogni singola parte di un messaggio long testuale è composto da 152 caratteri. Ad esempio un messaggio da 320 caratteri sarà conteggiato come 3 messaggi, la prima e la seconda parte da 152 caratteri e la terza parte da 16 caratteri.

  • lucs

Messaggio long unicode. Permette di inviare messaggi Unicode con più di 70 caratteri in un'unica richiesta. Ogni singola parte di un messaggio long unicode è composto da 62 caratteri. Ad esempio un messaggio da 140 caratteri sarà conteggiato come un 3 messaggi, la prima e la seconda da 62 caratteri e la terza parte da 16 caratteri.

  • binary

Messaggio binario (8bit). Permette di inviare messaggi binari come ad esempio loghi, suonerie, picture message ed EMS. Utilizzando questa tipologia di messaggio sarà necessario valorizzare anche il parametro udh. Per inviare messaggi di tipo binary è necessario convertire ogni byte del corpo del messaggio nel suo corrispettivo valore esadecimale.

  • wappush

Messaggio WAP PUSH. Permette di inviare messaggi wap push (Messaggio composto da una parte testuale ed un URL) . Utilizzando questa tipologia di messaggio sarà necessario valorizzare anche il parametro url.

  • int

Messaggio Interattivo. Permette di inviare messaggi interattivi. Il messaggio interattivo è un SMS al quale è possibile rispondere e l'account riceverà in automatico la risposta ad un URL pre-impostato.

Risposte del gateway SMS

  • Successo

Il gateway restituirà una stringa formattata come segue : SENT [Identificativo Spedizione] - [Identificativo del messaggio]

Esempio : SENT 346 - 1344

  • Errore

Il gateway restituirà una stringa formattata come segue : ERR [Codice Errore] [Messaggio]

Invio SMS Multiplo

Attraverso questa tipologia di invio sarà possibile inviare lo stesso messaggio verso una lista di numeri separati da virgola. All'interno della lista sarà possibile inserire un massimo di 500 numeri.

URL di riferimento : http://gateway.airtelco.com/raven/sms/send

Esempio :

http://gateway.airtelco.com/raven/sms/send?login=LOGIN&password=PASSWORD&phone=%2b393330000000,%2b393112222222&
from=Mittente&body=Testo&action=batch

Parametri

La descrizione dei parametri resta invariata rispetto all'invio SMS singolo

  • action

Parametro obbligatorio. Per poter abilitare questo metodo di invio il parametro action dovrà contenere il valore batch.

  • phone

Parametro obbligatorio. Il parametro phone potrà contenere uno o più numeri di telefono separati da virgola come da esempio.

Risposta del gateway SMS

  • Successo

Il gateway restituirà una stringa formattata come segue : SENT [Identificativo spedizione] – [Inviati con successo] – [Non inviati]

Esempio : SENT 100 – 500 – 0

  • Errore

Il gateway restituirà una stringa formattata come segue : ERR [Codice Errore] [Messaggio]

Invio SMS posticipato

Specificando data e ora di partenza dei messaggi è possibile programmarne l'invio. Per indicare al gateway che si intende effettuare una spedizione posticipata è necessario valorizzare i seguenti parametri :

  • date

Indica giorno, mese e anno di invio. Il parametro va specificato nel seguente formato : aaaa-mm-gg

  • hour

Indica l'ora di spedizione. Il parametro va specificato nel seguente formato : hh

  • minute

Indica i minuti di spedizione. Il parametro va specificato nel seguente formato: mm

  • timezone

Indica il timezone di riferimento. Il parametro è opzionale e va specificato, ad esempio, come segue : Europe/Rome. Il timezone di default sarà Europe/Rome.

Esempio date=2009-12-31 hour=23, minute=59. Il 31 dicembre alle 23:59 il gateway invierà un SMS ai destinatari specificati nella richiesta

Eliminare Spedizioni posticipate

Per eliminare una spedizione posticipata è necessario utilizzare la action “stop” come riportato di seguito

Esempio :

http://gateway.airtelco.com/raven/sms/send?login=LOGIN&password=PASSWORD&action=stop&sid=222222

Parametri:

  • action - il parametro deve essere valorizzato a stop
  • sid - il parametro send id deve essere valorizzato con l'identificativo univoco della spedizione posticipata che si intende bloccare

Invio SMS INTERATTIVO

Attraverso questa tipologia di invio sarà possibile inviare un singolo messaggio interattivo. Il destinatario potrà rispondere al messaggio ricevuto. Le risposte saranno automaticamente inoltrate ad URL associato precedentemente all'account. (Vedere servizio Virtual SIM)

URL di riferimento : http://gateway.airtelco.com/raven/sms/send

Esempio :

               http://gateway.airtelco.com/raven/sms/send?login=LOGIN&password=PASSWORD
                             &phone=%2b393330000000&from=Mittente&body=Testo&type=int

Controllo SMS e credito residui

Attraverso questa funzione è possibile controllare il credito residuo o il numero di SMS ancora a disposizione.

URL di riferimento : http://gateway.airtelco.com/raven/sms/send

Credito residuo

SMS disponibili

SMS disponibili per qualità

Risposta del gateway SMS

  • credit

Abstract : [Valuta] [Credito Residuo]

Esempio : EUR 45,10

  • sms

Abstract : [Numero SMS]

Esempio : 1100

  • smsdetails
<?xml version="1.0" encoding="iso-8859-1"?><xml><premium>80</premium><standard>100</standard></xml>

Notifiche SMS

Inviando i messaggi in qualità premium sarà possibile ricevere la notifica di avvenuta consegna del messaggio. La notifica di avvenuta consegna è un messaggio inviato dal cellulare destinatario al centro servizi dell'operatore che ha inoltrato l'SMS. E' possibile ricevere le notifiche in due modalità: PUSH o PULL, nel primo caso il gateway inoltrerà al client la notifica, ricevuta dall'operatore, attraverso una POST HTTP verso un URL precedentemente impostato dal cliente all'interno dell'area riservata. Nel secondo caso sarà il client a richiedere, al gateway, le notifiche attualmente disponibili.

Esempio PUSH: Iniziata dal Gateway SMS AirTelco http://sitoclient/script?obj_id=1344&send_id=340&status=Delivered&timestamp=2008-11-07%2015:10:00&phone=%2b393112222222

Esempio PULL: Iniziata dal Client http://gateway.airtelco.com/raven/sms/statusdev?login=LOGIN&password=PASSWORD&send_id=11111&action=getxmlstatus

Notifiche PUSH - Parametri richiesti lato Client

  • obj_id

Identificativo univoco del messaggio inviato. Questo parametro sarà valorizzato con l'identificativo precedentemente restituito dal gateway in risposta ad un invio singolo.

  • send_id

Identificativo univoco di una spedizione. Questo parametro sarà valorizzato con l'identificativo precedentemente restituito dal gateway in risposta ad un invio multiplo.

  • status

Stato del messaggio. Valori possibili “Delivered” “Undelivered”, rispettivamente indicheranno l'avvenuta consegna o la mancata consegna del messaggio.

  • timestamp

Data e ora di ricezione del messaggio. Nel caso in cui lo stato del messaggio sarà “Delivered” il timestamp indicherà la data e l'ora di consegna del messaggio. In caso contrario indicherà la data e l'ora di ricezione della notifica.

  • phone

Numero di telefono destinatario del messaggio.

Nel caso in cui l'URL del cliente risulti non raggiungibile, il sistema effettuerà un retry incrementale per 10 minuti. In caso di continuo esito negativo salverà i dati associati alla notifica all'interno di un proprio repository per permettere al cliente di richiedere, contattando l'assistenza, un report delle notifiche ricevute in un preciso arco di tempo. I dettagli delle notifiche saranno mantenuti all'interno del repository per 30 giorni. Il gateway riterrà l'URL non raggiungibile anche a causa di timeout, il tempo massimo di attesa è di 5 secondi.

Notifiche PULL - Parametri richiesti lato Gateway

  • login
  • password
  • send_id
  • action

Esempio di risposta


<xml>
<result>
<statusdetails>
<object>
<id>40680736</id>
<phone>+39XXXXXXXX</phone>
<status>Delivered - 2012-05-22 11:29:21</status>
</object>
<object>
<id>40680737</id>
<phone>+39XXXXXXXX</phone>
<status>Delivered - 2012-05-22 11:29:22</status>
</object>
</statusdetails>
</result>
</xml>

<xml>
<result>
<statusdetails>
<xml>
<error>
<code>70<\/code>
<message>
Error while getting status response. Request out of time.
</message>
</error>
</xml>
</statusdetails>
</result>
</xml>

Lista Errori

ERR 10 Authentication error
ERR 11 No user or password
ERR 12 IP Address not allowed
ERR 20 Wrong action value
ERR 23 Wrong deferred date or time
ERR 64 Sender content not allowed
ERR 65 Message content not allowed
ERR 66 Deferred mode blocked
ERR 67 Quality Blocked
ERR 68 Account Blocked
ERR 299 Wrong message type
ERR 301 Wrong Wap Push URL
ERR 302 Wrong unicode or binary encoding
ERR 303 Wrong user data header
ERR 304

  • Binary message too long
  • Unicode message too long (Max 140 byte)
  • Long Unicode message too long (Max 496 byte - 4 parts)

ERR 305 Wrong Sender
ERR 306 Message too long (Max 760 characters)
ERR 307 Message type not available in standard quality
ERR 308 Not enough credit
ERR 309 Phone number out of coverage list
ERR 400 System error
ERR 401 Unable to enqueue message

Esempi in PHP

Per maggiori informazioni su come utilizzare le API in altri linguaggi di programmazione, contatta telefonicamente il supporto tecnico oppure all'indirizzo support@airtelco.com

Link Utili

ravenweb_api.txt · Last modified: 2015/12/03 09:40 (external edit)
 
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki