# Parametri opzionali TLV di SMPP

> I TLV (parametri opzionali, introdotti nella v3.4) estendono una PDU oltre i suoi campi obbligatori. Ciascuno è codificato come un Tag di 2 byte, una Length di 2 byte e un Value di Length byte, tutti big-endian. I TLV compaiono dopo il body obbligatorio, in qualsiasi ordine, e permettono a SMPP di trasportare payload, metadati di concatenazione e correlazione delle ricevute senza modificare il layout fisso dei campi.

- URL canonico: https://www.broadnet.me/it/reference/smpp-tlv-parameters
- Lingua: it
- Ultimo aggiornamento: 2026-07-18
- Editore: BroadNet (https://www.broadnet.me)

I parametri opzionali di SMPP usano un formato Tag-Length-Value. Il layout in byte del TLV più i tag comuni: message_payload, receipted_message_id, message_state, user_message_reference e l'insieme sar_* per la concatenazione.

## Il formato TLV

Un TLV (detto anche parametro opzionale) è un campo auto-descrittivo: un Tag di 2 ottetti identifica il parametro, una Length di 2 ottetti indica la dimensione del Value in ottetti e il Value segue. Sia Tag sia Length sono big-endian. Poiché sono taggati, i TLV possono comparire in qualsiasi ordine dopo i parametri obbligatori e un ricevente ignora semplicemente i tag che non riconosce.

*TLV message_payload che trasporta un valore di 5 byte*

```hex
04 24        Tag    = 0x0424 (message_payload)
00 05        Length = 5 octets
48 65 6C 6C 6F   Value = "Hello"
```

## Tag TLV comuni

Una manciata di TLV svolge la maggior parte del lavoro in produzione. message_payload trasporta un messaggio troppo lungo per short_message. receipted_message_id e message_state rendono le ricevute di consegna interpretabili automaticamente. user_message_reference consente di allegare il proprio id di correlazione. L'insieme sar_* fornisce una concatenazione basata sugli standard senza byte UDH nel body.

*Parametri opzionali di uso frequente*

| Tag | Nome | Valore | Utilizzo |
|---|---|---|---|
| 0x0424 | message_payload | Octet String | Corpo del messaggio quando supera short_message |
| 0x001E | receipted_message_id | C-Octet String (65) | message_id originale in una ricevuta di consegna |
| 0x0427 | message_state | Integer (1) | Stato finale/intermedio in una conferma di consegna (vedi sotto) |
| 0x0204 | user_message_reference | Integer (2) | Riferimento di correlazione assegnato dall'ESME |
| 0x020C | sar_msg_ref_num | Integer (2) | Concatenazione: riferimento condiviso tra segmenti |
| 0x020E | sar_total_segments | Integer (1) | Concatenazione: numero totale di segmenti |
| 0x020F | sar_segment_seqnum | Integer (1) | Concatenazione: la sequenza di questo segmento |
| 0x0423 | network_error_code | Octet String (3) | Dettaglio dell'errore specifico della rete in una conferma di consegna |
| 0x0426 | more_messages_to_send | Integer (1) | Segnala che seguono altri segmenti |
| 0x020A | source_port | Integer (2) | Indirizzamento della porta dell'applicazione (origine) |
| 0x020B | dest_port | Integer (2) | Indirizzamento della porta dell'applicazione (destinazione) |

## Valori di message_state

Il TLV message_state (0x0427) riporta numericamente lo stato del ciclo di vita di un messaggio — il complemento leggibile automaticamente della parola chiave stat nel testo del DLR. Questi valori compaiono anche in query_sm_resp.

*Valori di message_state*

| Valore | Stato | Parola chiave stat del DLR |
|---|---|---|
| 1 | ENROUTE | (in transito) |
| 2 | DELIVERED | DELIVRD |
| 3 | EXPIRED | EXPIRED |
| 4 | DELETED | DELETED |
| 5 | UNDELIVERABLE | UNDELIV |
| 6 | ACCEPTED | ACCEPTD |
| 7 | UNKNOWN | UNKNOWN |
| 8 | REJECTED | REJECTD |
| 9 | SKIPPED (v5.0) | — |

## Concatenazione SAR vs UDH

SMPP offre due modi per concatenare un messaggio lungo. Il metodo UDH inserisce un User Data Header di 6 byte all'interno di short_message e imposta il bit UDHI di esm_class. Il metodo SAR mantiene pulito il body e trasporta invece i tre TLV sar_*. Sceglietene uno e mantenetelo coerente per rotta — alcune reti accettano solo UDH, altre solo SAR. Non mescolate mai i due sullo stesso messaggio.

## Regole e insidie

Non popolate sia short_message sia message_payload — i provider lo rifiutano. I TLV personalizzati al di fuori degli intervalli approvati dal provider vengono spesso rimossi o causano errori di parsing a valle, quindi inviate i metadati solo nei tag concordati. Un ricevente deve tollerare i TLV sconosciuti saltandone i byte di Length; una Length malformata è la classica causa di un parsing corrotto di tutto ciò che segue.

## Domande frequenti

### Cosa significa TLV in SMPP?

Tag-Length-Value. Ogni parametro opzionale è codificato come un tag di 2 byte, una length di 2 byte e altrettanti byte di valore. I TLV sono stati introdotti nella v3.4 di SMPP e compaiono dopo il body obbligatorio di una PDU.

### Quando dovrei usare message_payload invece di short_message?

Usate il TLV message_payload (0x0424) quando il messaggio supera il campo short_message di 254 ottetti, o quando il vostro provider lo preferisce per contenuti lunghi. Non impostate entrambi i campi sulla stessa PDU.

### Come correlo una ricevuta di consegna al messaggio inviato?

Confrontate il TLV receipted_message_id (0x001E) della ricevuta con il message_id che avete conservato da submit_sm_resp. Normalizzate prima i formati, poiché alcuni SMSC restituiscono l'id in esadecimale al submit e in decimale nella ricevuta.

### I TLV sar_* sono migliori dell'UDH per la concatenazione?

Nessuno dei due è universalmente migliore — sono due codifiche della stessa idea. SAR mantiene il body del messaggio libero da byte di header; UDH è più ampiamente accettato. Usate quello supportato dalla vostra rotta e restate coerenti.

### Posso aggiungere TLV personalizzati?

Solo nell'intervallo di tag specifico del fornitore approvato dal vostro provider. I TLV personalizzati non approvati vengono spesso rimossi o rifiutati in transito, quindi concordate prima i tag e il loro significato con il provider.

## Fonti

- [SMPP v3.4 specification — §5.3 optional parameters](https://smpp.org/SMPP_v3_4_Issue1_2.pdf)
- [SMPP v5.0 specification](https://smpp.org/SMPP_v5.pdf)

## Correlati

- [Ricevute di consegna SMPP (formato DLR)](https://www.broadnet.me/it/reference/smpp-delivery-receipts-dlr)
- [Segmentazione SMS e UDH](https://www.broadnet.me/it/reference/sms-segmentation-concatenation-udh)
- [Riferimento submit_sm di SMPP](https://www.broadnet.me/it/reference/smpp-submit-sm)
- [Decoder PDU SMPP (strumento gratuito)](https://www.broadnet.me/it/tools/smpp-pdu-decoder)
- [Anatomia della PDU SMPP](https://www.broadnet.me/it/reference/smpp-pdu-anatomy)