Integração por SMPP

O protocolo SMPP (Short Message Peer to Peer) é um protocolo aberto, desenvolvido para proporcionar uma interface para a comunicação de dados flexível, para a transferência de mensagens curtas entre um Short Message Service Centre (SMSC) e uma aplicação SMS.

O termo SMSC (Short Message Service Centre) é utilizado quando se refere à entidade servidora da conexão SMPP. No caso da entidade cliente da conexão SMPP, o nome adotado pelo protocolo é ESME (External Short Message Entity).

A versão 3.4 do protocolo SMPP permite:

  • Transmitir mensagens de uma ESME para um único ou múltiplos destinos via SMSC;
  • Que uma ESME possa receber mensagens de um terminal móvel via o SMSC;
  • Enviar mensagens com confirmação de recebimento;
  • Cancelar ou repor mensagens;
  • Consultar o status de entrega de uma determinada mensagem;
  • Agendar a entrega de mensagens, selecionando a data e a hora de entrega;
  • Selecionar o modo de transmissão da mensagem, i.e. datagrama ou store and forward
  • Definir o tipo de codificação dos dados da mensagem;
  • Definir um período de validade para a mensagem;
  • Associar um tipo de serviço para cada mensagem.

A tabela a seguir apresenta os parâmetros para acesso e envio de mensagens ao SMSC Zenvia:

Parâmetros de acesso Valor Mandatório (Sim/Não) Observações
Host Name smpp.zenvia360.com Sim Nome do SMSC Zenvia.
Port 8057 Sim Porta do SMSC Zenvia.
system_id Sim Nome do usuário – Solicite o nome do usuário de sua conta à nossa equipe de Atendimento ao Cliente.
password Sim Senha – Solicite a senha de sua conta à nossa equipe de Atendimento ao Cliente.
interface_version 34 Sim O SMSC Zenvia suporta apenas a versão 3.4 do protocolo SMPP. A versão 3.3 não é suportada.
Parâmetros de envio (PDU: submit_sm) Valor Mandatório (Sim/Não) Observações
type_name submit_sm Sim
command_id 4 = 0x00000004 Sim
command_status 0 = 0x00000000 Sim
service_type NULL Sim
source_addr_ton 1 Sim
source_addr_npi 1 Sim
source_addr NULL Sim Atribuído pelo SMCS Zenvia, exceto para short codes dedicados previamente cadastrados
dest_addr_ton 1 = 0x00000001 Sim
dest_addr_npi 1 = 0x00000001 Sim
destination_addr Sim Telefone de destino da mensagem. PPPAAAANNNNNNNNN, Exemplo Brasil: 5511999887766 onde 55 = país, 11 = área , 99887766 = número do telefone móvel de destino da mensagem.
data_coding 0x00 -> GSM_7BIT

0x01 -> US_ASCII

0x03 -> ISO_8859_1

0x08 -> UTF-16BE

Sim GSM_7BIT: https://en.wikipedia.org/wiki/GSM_03.38

ISO_8859_1: https://en.wikipedia.org/wiki/ISO/IEC_8859-1

UTF16: https://en.wikipedia.org/wiki/UTF-16

esm_class 3 = 0x00000003 Sim

 

NOTA: O número máximo de BINDs simultâneos por conta é 20.

Temporizadores

Para garantir que a sessão não será finalizada devido à inatividade entre o ESME e o SMSC, é necessário que um PDU enquire_link seja enviado a cada intervalo de tempo. O SMSC Zenvia, ao estabelecer a conexão, envia um enquire_link a cada 5 segundos, com um tempo de resposta de 2 segundos. Caso um enquire_link_resp (ou qualquer resposta a um PDU enviado) não seja recebido dentro deste tempo, a conexão será finalizada.

Protocolo SMPP

O protocolo SMPP trafega sobre TCP/IP e é baseado em sessões entre cada entidade ESME x SMSC pelas quais são enviados os pacotes ou PDU (Protocol Data Unit), contendo as informações de cada operação SMPP específica. Utiliza um sistema de troca de mensagens e confirmações de recebimento para garantir a confiabilidade das transações. O protocolo SMPP define:

  • Um conjunto de operações para a troca de mensagens entre a ESME e o SMSC;
  • Os dados que uma entidade pode trocar com a outra, durante uma operação SMPP.

Todas as operações de envio de mensagens SMPP devem ser seguidas de uma mensagem de resposta. A exceção à esta regra é no caso da mensagem de ALERT_NOTIFICATION, que não requer resposta.

Os três grupos distintos de transações de mensagens SMPP são os seguintes:

  • Mensagens enviadas a partir da ESME para o SMSC;
  • Mensagens enviadas a partir do SMSC para a ESME;
  • Mensagens trocadas entre a ESME e o SMSC simultaneamente;

A figura 1 mostra os três tipos de seção possíveis dentro do protocolo SMPP. Observe o sentido de envio das mensagens.

  • Conexão Transmitter – Utilizado para envio de mensagens por meio de um BIND TRANSMITTER
  • Conexão Receiver – Utilizado para recebimento de mensagens por meio de um BIND RECEIVER
  • Conexão Transceiver – Utilizado tanto para envio quanto para recebimento de mensagens por meio de um BIND RECEIVER

SMPP-figura1-transmitter-receiver-transceiver
Figura 1 – Diagrama de seções do protocolo SMPP – Transmitter, Receiver e Transceiver

Uma sessão SMPP entre uma ESME e um SMSC é iniciada pelo estabelecimento de um link TCP/IP entre estas duas entidades. Em seguida a ESME, entidade cliente da sessão SMPP, faz a solicitação da conexão, chamada BIND. Se esta entidade deseja enviar mensagens, deve fazer um “BIND TRANSMITTER”, se deseja receber mensagens, deve fazer um “BIND RECEIVER” e se deseja tanto enviar quanto receber, deve fazer ou um “BIND TRANSMITTER” e um “BIND RECEIVER” ou simplesmente um “BIND TRANSCEIVER”. Os passos para esta conexão estão descritos abaixo:

  • OPEN (Conectado via TCP/IP, aguardando o BIND): A ESME já possui um caminho lógico via TCP/IP, entretanto ainda não solicitou a abertura da conexão SMPP;
  • BOUND_TX: A ESME solicitou a abertura da conexão SMPP transmitter, enviando um PDU bind_transmitter. Ao receber este PDU, o SMSC devolve um bind_transmitter_resp, informando se aceitou ou não a conexão. Caso a conexão seja estabelecida, a ESME já estará apta a enviar mensagens para o SMSC;
  • BOUND_RX: A ESME solicitou a abertura da conexão SMPP receiver, enviando um PDU bind_receiver. Ao receber este PDU, o SMSC devolve um bind_receiver_resp, informando se aceitou ou não a conexão. Caso a conexão seja estabelecida, a ESME já estará apta a receber mensagens do SMSC;
  • CLOSED: A ESME solicitou a desconexão ao SMSC.

Outra operação do SMPP é o OUTBIND, que é a mensagem SMPP enviada pelo SMSC para a ESME, solicitando que a ESME envie um BIND_RECEIVER. Observe que a regra da ESME solicitar a conexão não foi quebrada, uma vez que o SMSC não estabeleceu a conexão e sim a ESME. O diagrama abaixo ilustra esta situação:

SMPP-figura2-outbind-esme-smcs
Figura 2 – Diagrama OUTBIND entre ESME e SMSC

A tabela a seguir exibe as funcionalidades suportadas e não suportadas pela SMSC Zenvia:

Funcionalidades de mensagens suportadas Disponível (Sim/Não/Parcial) Observações
Alphanumeric Originators Não Funcionalidade restrita pelas Operadoras de telefonia móvel
Shortcode Originators Sim
Numeric Originators Sim
Special Character Support within Originator Não
Supports dynamic originators? Não
Standard Text Sim
Standard Binary Sim
Standard Unicode Sim
Delivery Receipts Sim
Support for Concatenated Text Sim Cada mensagem deve ser enviada com até 153 caracteres.
Support for Concatenated Binary Sim
Support for Concatenated Unicode Sim
Full Character-set support Sim
Flash Message (message type 0) Sim
Wap-Push Não
Local/Dynamic timestamp support Não

Para mais informações, consulte o manual oficial do protocolo SMPP.

Recibo de Entrega

Um recibo de entrega (DLR) é enviado pela SCMC como um PDU deliver_sm. Este PDU é o mesmo utilizado para enviar mensagens originadas no aparelho (MO). Assim, para verificar se o PDU é um recibo de entrega, é preciso verificar o campo esm_class: caso ele tenha o bit 2 ligado (0x04), então é um DLR.

A informação de entrega pode ser encontrada no campo short_message do PDU (codificada em ASCII). Ela seguirá a estrutura abaixo:

id:3e058590 sub:001 dlvrd:001 submit date:1711231558 done date:1711231558 stat:REJECTD err:000 text:
  • id: o ID da mensagem
  • sub: o número de mensagens enviadas originalmente
  • dlvrd: o número de mensagens entregues
  • submit date: a data e hora em que a mensagem foi enviada, no formato YYMMDDhhmm
  • done date: a data e hora em que a mensagem alcançou seu estado final, no formato YYMMDDhhmm
  • stat: o status final da mensagem
  • err: o código de status adicional, específico do SMSC Zenvia (veja tabela abaixo)
  • text: (vazio)

Códigos de Status

Os valores possíveis para o status final da mensagem são:

Código Descrição
DELIVRD Mensagem foi entregue no destino
EXPIRED Período de validade da mensagem expirou
DELETED Mensagem foi apagada
UNDELIV Mensagem não-entregável
ACCEPTD Mensagem foi aceita
UNKNOWN Mensagem em estado inválido
REJECTD Mensagem rejeitada

 

Os códigos de status adicionais específicos da Zenvia estão descritos na tabela abaixo:

Código Descrição
000 Message Sent
002 Message successfully canceled
010 Empty message content
011 Message body invalid
012 Message content overflow
013 Incorrect or incomplete ‘to’ mobile number
014 Empty ‘to’ mobile number
015 Scheduling date invalid or incorrect
016 ID overflow
017 Parameter ‘url’ is invalid or incorrect
018 Field ‘from’ invalid
021 ‘id’ field is mandatory
080 Message with same ID already sent
100 Message Queued
110 Message sent to operator
111 Message confirmation unavailable
120 Message received by mobile
130 Message blocked
131 Message blocked by predictive cleansing
132 Message already canceled
133 Message content in analysis
134 Message blocked by forbidden content
135 Aggregate is Invalid or Inactive
136 Message expired
140 Mobile number not covered
141 International sending not allowed
145 Inactive mobile number
150 Message expired in operator
160 Operator network error
161 Message rejected by operator
162 Message cancelled or blocked by operator
170 Bad message
171 Bad number
172 Missing parameter
180 Message ID not found
190 Unknown error
200 Messages Sent
210 Messages scheduled but Account Limit Reached
240 File empty or not sent
241 File too large
242 File readerror
300 Received messages found
301 No received messages found
400 Entity saved
900 Authentication error
901 Account type not support this operation
990 Account Limit Reached – Please contact support
998 Wrong operation requested
999 Unknown Error

 

Exemplos de PDUs

Neste link pode-se encontrar exemplos de PDUs no formato pcap.