Como Receber SMS Usando a API SMPP

O protocolo Short Message Peer-to-Peer (SMPP) é um protocolo poderoso e padrão do setor, projetado para facilitar a troca de mensagens SMS entre Entidades de Mensagens Curtas Externas (ESMEs) e Centros de Serviço de Mensagens Curtas (SMSCs). Para desenvolvedores e empresas que utilizam a API SMPP com o Ozeki SMS Gateway como sua plataforma principal, entender as operações de baixo nível do protocolo é essencial para construir soluções robustas de SMS. Este artigo fornece um guia abrangente sobre como receber mensagens SMS usando a API SMPP, focando nas interações em nível de protocolo e nas Unidades de Dados de Protocolo (PDUs) específicas envolvidas na configuração, manutenção e utilização de uma conexão de cliente da API SMPP com o Ozeki SMS Gateway.

Introdução à API SMPP e ao Ozeki SMS Gateway

A API SMPP é amplamente utilizada na indústria de telecomunicações por sua eficiência no tratamento de mensagens SMS em massa sobre conexões TCP/IP. O Ozeki SMS Gateway, um software SMPP versátil, funciona tanto como cliente quanto servidor SMPP, tornando-o uma plataforma ideal para enviar e receber mensagens SMS. Ao implementar o protocolo SMPP (versões 3.3 e 3.4, com suporte para 5.0 no Ozeki 10 SMS Gateway), o Ozeki permite conectividade perfeita com SMSCs, suportando aplicações como campanhas de marketing, autenticação de dois fatores e sistemas de notificação. Este artigo foca em receber mensagens SMS, detalhando as PDUs SMPP necessárias para configuração de conexão, manutenção e recebimento de mensagens.

Entendendo as PDUs SMPP

O SMPP opera trocando Unidades de Dados de Protocolo (PDUs) entre o cliente SMPP (por exemplo, Ozeki SMS Gateway) e o servidor SMPP (por exemplo, um SMSC). Cada PDU é uma mensagem estruturada que carrega instruções ou dados específicos, como credenciais de autenticação, conteúdo de SMS ou consultas de status de conexão. Para receber mensagens SMS usando a API SMPP, o cliente deve estabelecer uma conexão, mantê-la e processar mensagens recebidas. As PDUs principais envolvidas são:

  • bind_transceiver: Estabelece uma conexão para enviar e receber SMS.
  • enquire_link: Mantém a conexão verificando seu status.
  • deliver_sm: Entrega mensagens SMS recebidas do SMSC para o cliente.
  • unbind: Termina a sessão SMPP.

Abaixo, exploraremos cada PDU em detalhes, incluindo sua estrutura, configuração no Ozeki SMS Gateway e seu papel no recebimento de mensagens SMS via API SMPP.

Configurando uma Conexão de Cliente SMPP API

Para receber mensagens SMS, o primeiro passo é estabelecer uma conexão estável de cliente SMPP API com o SMSC. O Ozeki SMS Gateway simplifica esse processo com sua interface intuitiva, mas entender as operações em nível de protocolo é crucial para usuários avançados.

1. Configurando o Cliente SMPP no Ozeki SMS Gateway

Para configurar uma conexão de cliente SMPP API no Ozeki SMS Gateway, siga estas etapas:

  1. Acesse o Console de Gerenciamento: Acesse a interface web do Ozeki SMS Gateway usando a conta de administrador (nome de usuário padrão: "admin").
  2. Adicione uma Nova Conexão: Navegue até o painel "Conexões", clique em "Adicionar nova conexão" e selecione "Cliente SMPP" na seção "Conexões SMS IP".
  3. Configure as Configurações SMPP: Forneça os seguintes detalhes, geralmente fornecidos pelo seu provedor de SMS:
    • Nome do Host: O endereço IP ou nome do host do SMSC (por exemplo, "192.168.1.1").
    • Número da Porta: A porta TCP/IP para comunicação SMPP (o padrão é 9500, mas confirme com seu provedor).
    • Nome de Usuário (ID do Sistema): Seu identificador de conta para o SMSC.
    • Senha: A senha associada ao ID do Sistema.
    • Versão SMPP: Selecione v3.4 para suporte transceptor (recomendado para enviar e receber).
    • Tipo de Sistema: Opcional, geralmente "SMPP", conforme especificado pelo provedor.
    • Endereço do Remetente: O número de telefone padrão para SMS de saída (por exemplo, "+1234567890").
    • Faixa de Endereço: Opcional, usado para receber mensagens de vários números.
  4. Modo de Vinculação: Escolha "Transceptor" para ativar o envio e recebimento de SMS em uma única conexão.
  5. Configurações Avançadas: Ative "Conectar automaticamente na inicialização" para reconexão contínua e marque "Enviar pacotes keepalive" para manter a conexão.
  6. Ativar Registro: Na aba "Avançado", ative "Registrar Eventos de Comunicação" para capturar PDUs SMPP para depuração.
  7. Salvar e Conectar: Clique em "OK" para salvar a configuração e depois em "Conectar" para iniciar a conexão.

Essas configurações preparam o Ozeki SMS Gateway para estabelecer uma conexão SMPP API usando o PDU bind_transceiver.

2. O PDU bind_transceiver

O PDU bind_transceiver é o primeiro PDU enviado pelo cliente SMPP para autenticar e estabelecer uma conexão com o SMSC. Ele permite enviar e receber mensagens SMS em uma única conexão TCP/IP, tornando-o ideal para a maioria das aplicações SMPP API.

Estrutura do PDU bind_transceiver

Comprimento do Comando: 4 bytes (comprimento total do PDU)
ID do Comando: 0x00000009 (bind_transceiver)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU
ID do Sistema: Nome de usuário para autenticação (por exemplo, "smppuser")
Senha: Senha para autenticação (por exemplo, "password123")
Tipo de Sistema: Opcional, geralmente "SMPP"
Versão da Interface: Versão SMPP (por exemplo, 0x34 para v3.4)
Faixa de Endereço: Opcional, para receber mensagens de números específicos

Exemplo de PDU bind_transceiver (hexadecimal):

0000002F 00000009 00000000 00000001 736D70707573657200 70617373776F726431323300 534D505000 34 00

Explicação:

  • Comprimento do Comando (0000002F): Comprimento total do PDU (47 bytes).
  • ID do Comando (00000009): Identifica o PDU como bind_transceiver.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000001): Um ID único para rastrear o PDU.
  • ID do Sistema (736D70707573657200): ASCII para "smppuser" seguido de um terminador nulo.
  • Senha (70617373776F726431323300): ASCII para "password123" seguido de um terminador nulo.
  • Tipo de Sistema (534D505000): ASCII para "SMPP" seguido de um terminador nulo.
  • Versão da Interface (34): Indica SMPP v3.4.
  • Faixa de Endereço (00): Nulo, pois é opcional.

Ao receber o PDU bind_transceiver, o SMSC valida as credenciais. Se for bem-sucedido, ele responde com um PDU bind_transceiver_resp com um status de comando 0x00000000, indicando uma conexão bem-sucedida. O Ozeki SMS Gateway registra essa interação, que pode ser visualizada no log "Eventos de Comunicação".

Mantendo a Conexão SMPP API

Uma vez estabelecida, a conexão deve ser mantida ativa para garantir a recepção contínua de SMS. O protocolo SMPP usa o PDU enquire_link para verificar o status da conexão e evitar desconexão por inatividade.

O PDU enquire_link

O PDU enquire_link é uma mensagem leve enviada periodicamente pelo cliente SMPP ao SMSC para confirmar que a conexão está ativa. Isso é particularmente importante para manter conexões de longa duração, pois servidores proxy ou SMSCs podem encerrar conexões ociosas.

Estrutura do PDU enquire_link

Comprimento do Comando: 0x00000010 (16 bytes)
ID do Comando: 0x00000015 (enquire_link)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU

Exemplo de PDU enquire_link (hexadecimal):

00000010 00000015 00000000 00000002

Explicação:

  • Comprimento do Comando (00000010): Comprimento total (16 bytes).
  • ID do Comando (00000015): Identifica o PDU como enquire_link.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000002): Um ID único para rastrear o PDU.

O SMSC responde com um PDU enquire_link_resp, confirmando o status da conexão. No Ozeki SMS Gateway, ativar a opção "Enviar pacotes keepalive" na aba "Comunicação" garante que os PDUs enquire_link sejam enviados automaticamente em intervalos regulares (por exemplo, a cada 30 segundos). Essa configuração é crítica para manter uma conexão SMPP API estável, especialmente ao receber mensagens SMS intermitentemente.

Recebendo Mensagens SMS com a API SMPP

Uma vez que a conexão é estabelecida e mantida, o cliente da API SMPP pode receber mensagens SMS via o PDU deliver_sm. Este PDU é enviado pelo SMSC ao cliente quando uma mensagem SMS de entrada ou um relatório de entrega está disponível.

O PDU deliver_sm

O PDU deliver_sm transporta o conteúdo de uma mensagem SMS de entrada ou um relatório de entrega. Para receber SMS, o PDU contém o número de telefone do remetente, o número do destinatário (número virtual atribuído pelo provedor) e o texto da mensagem.

Estrutura do PDU deliver_sm

Comprimento do Comando: Variável (depende do comprimento da mensagem)
ID do Comando: 0x00000005 (deliver_sm)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU
Tipo de Serviço: Opcional, geralmente nulo
TON do Endereço de Origem: Tipo de Número para o remetente
NPI do Endereço de Origem: Indicador de Plano de Numeração para o remetente
Endereço de Origem: Número de telefone do remetente (ex., "+1234567890")
TON do Endereço de Destino: Tipo de Número para o destinatário
NPI do Endereço de Destino: Indicador de Plano de Numeração para o destinatário
Endereço de Destino: Número de telefone do destinatário (ex., número virtual)
Classe ESM: Tipo de mensagem (ex., 0x04 para SMS)
Codificação de Dados: Codificação de caracteres (ex., 0x00 para GSM 7-bit)
Mensagem Curta: O texto da mensagem (até 160 caracteres para GSM)

Exemplo de PDU deliver_sm (hexadecimal):

0000005F 00000005 00000000 00000003 00 01 01 2B3132333435363738393000 01 01 2B3938373635343332313000 00 00 00 00 00 48656C6C6F2C207468697320697320616E20534D5321

Explicação:

  • Comprimento do Comando (0000005F): Comprimento total (95 bytes).
  • ID do Comando (00000005): Identifica o PDU como deliver_sm.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000003): Um ID único para rastrear o PDU.
  • Tipo de Serviço (00): Nulo, pois é opcional.
  • TON do Endereço de Origem (01): Número internacional.
  • NPI do Endereço de Origem (01): Plano de numeração ISDN/telefônico.
  • Endereço de Origem (2B3132333435363738393000): ASCII para "+1234567890".
  • TON do Endereço de Destino (01): Número internacional.
  • NPI do Endereço de Destino (01): Plano de numeração ISDN/telefônico.
  • Endereço de Destino (2B3938373635343332313000): ASCII para "+9876543210".
  • Classe ESM (00): Indica um SMS padrão.
  • Codificação de Dados (00): Codificação GSM 7-bit.
  • Mensagem Curta (48656C6C6F2C207468697320697320616E20534D5321): ASCII para "Olá, isto é um SMS!".

Ao receber um PDU deliver_sm, o Ozeki SMS Gateway processa a mensagem e a encaminha para a aplicação ou banco de dados configurado. O cliente deve responder com um PDU deliver_sm_resp para confirmar o recebimento, garantindo uma entrega confiável. No Ozeki, esta resposta é tratada automaticamente, e a mensagem é registrada no painel "Mensagens" ou armazenada no banco de dados, se configurado.

Configurando o Ozeki SMS Gateway para Recebimento de SMS

Para garantir que o Ozeki SMS Gateway possa receber mensagens SMS:

  1. Configuração de Número Virtual: Colabore com seu provedor de SMS para atribuir um número virtual (IMSI) para receber SMS. Este número é especificado no campo "Intervalo de Endereços" durante a configuração.
  2. Integração com Banco de Dados: Configure o Ozeki para armazenar mensagens de entrada em um banco de dados modificando a instrução SQL SELECT na configuração do "Usuário de banco de dados" (ex., "SELECT id, sender, receiver, msg, msgtype FROM ozekimessagein").
  3. Registro: Ative o registro de PDUs SMPP para monitorar PDUs deliver_sm de entrada para fins de depuração.

Uma vez configurado, as mensagens SMS de entrada são automaticamente encaminhadas para a aplicação ou banco de dados especificado, tornando o Ozeki SMS Gateway uma plataforma robusta para recebimento de SMS baseado na API SMPP.

Encerrando a Conexão da API SMPP

Quando a sessão da API SMPP não é mais necessária, o cliente envia um PDU unbind para encerrar a conexão de forma adequada.

O PDU unbind

O PDU unbind sinaliza ao SMSC para encerrar a sessão SMPP.

Estrutura do PDU unbind

Comprimento do Comando: 0x00000010 (16 bytes)
ID do Comando: 0x00000006 (unbind)
Status do Comando: 0x00000000 (definido como 0 para solicitações)
Número de Sequência: Identificador único para o PDU

Exemplo de PDU unbind (hexadecimal):

00000010 00000006 00000000 00000004

Explicação:

  • Comprimento do Comando (00000010): Comprimento total (16 bytes).
  • ID do Comando (00000006): Identifica o PDU como unbind.
  • Status do Comando (00000000): Definido como 0 para a solicitação.
  • Número de Sequência (00000004): Um ID único para rastrear o PDU.

O SMSC responde com um PDU unbind_resp, confirmando o encerramento da sessão. No Ozeki SMS Gateway, você pode iniciar isso clicando em "Desconectar" no painel "Conexões".

Melhores Práticas para Usuários da API SMPP

Para otimizar sua implementação da API SMPP com o Ozeki SMS Gateway para recebimento de SMS:

  • Ativar Pacotes Keepalive: Certifique-se de que a opção "Enviar pacotes keepalive" esteja ativada para manter uma conexão estável.
  • Monitorar Registros: Verifique regularmente os registros de PDUs SMPP para solucionar problemas com PDUs bind_transceiver, enquire_link ou deliver_sm.
  • Usar Modo Transceiver: Prefira o modo transceiver para eficiência, pois ele suporta envio e recebimento em uma única conexão.
  • Conexões Seguras: Se suportado pelo seu provedor, use SMPPS (SMPP sobre SSL/TLS) para comunicação criptografada.
  • Processar Relatórios de Entrega: Configure o Ozeki para processar PDUs deliver_sm contendo relatórios de entrega para acompanhar o status das mensagens.

Conclusão

Receber mensagens SMS usando a API SMPP com o Ozeki SMS Gateway envolve estabelecer uma conexão com o PDU bind_transceiver, mantê-la com PDUs enquire_link e processar mensagens recebidas através de PDUs deliver_sm. Ao entender esses PDUs e configurar o Ozeki SMS Gateway adequadamente, os desenvolvedores podem construir aplicações SMS confiáveis e de alto desempenho. A flexibilidade da API SMPP e a implementação robusta da Ozeki tornam-na uma excelente escolha para empresas que necessitam de soluções SMS escaláveis. Para mais detalhes, consulte a documentação do Ozeki SMS Gateway ou entre em contato com o seu provedor de serviços SMS para obter parâmetros de configuração específicos.

More information