Como Enviar SMS através da API SMPP usando Java

A API Short Message Peer-to-Peer (SMPP) é um protocolo de telecomunicações poderoso projetado para trocar mensagens SMS entre Centros de Serviço de Mensagens Curtas (SMSCs) e Entidades Externas de Mensagens Curtas (ESMEs). Ao utilizar Java e a API SMPP, os desenvolvedores podem construir aplicações robustas para enviar e receber mensagens SMS de forma eficiente. Este guia abrangente orienta você através do processo de implementação da API SMPP em Java para se conectar ao Ozeki SMS Gateway, com exemplos práticos de código para gerenciamento de conexão, envio de mensagens e tratamento de relatórios de entrega.

Por que Usar Java e a API SMPP para Mensagens SMS?

Java é uma linguagem de programação versátil e independente de plataforma, amplamente utilizada para construir aplicações de nível empresarial. Quando combinada com a API SMPP, Java permite que os desenvolvedores criem soluções de SMS escaláveis que se integram perfeitamente com gateways de SMS como o Ozeki. O protocolo SMPP é ideal para aplicações de SMS de alto volume devido à sua confiabilidade, suporte a mensagens em massa e capacidades de rastreamento de entrega. Este guia utiliza a biblioteca jSMPP, uma implementação pura Java do protocolo SMPP, para simplificar o desenvolvimento.

Configuração do Cliente da API SMPP em Java para Envio de Mensagens SMS

Para começar a enviar mensagens SMS usando a API SMPP em Java, você precisa configurar uma conta de usuário SMPP no servidor SMPP do Ozeki SMS Gateway e configurar sua aplicação Java para se conectar ao seu servidor SMPP. A biblioteca jSMPP é uma escolha popular para desenvolvedores Java devido ao seu suporte abrangente para recursos do protocolo SMPP. Abaixo, descrevemos as etapas para configurar seu projeto Java.

Passo 1: Adicionar a Dependência jSMPP

Para usar a biblioteca jSMPP em seu projeto Java, inclua a seguinte dependência Maven no seu arquivo pom.xml: 

<dependency>
    <groupId>org.jsmpp</groupId>
    <artifactId>jsmpp</artifactId>
    <version>2.3.10</version>
</dependency>

Esta dependência fornece todas as classes necessárias para implementar a API SMPP em Java, incluindo gerenciamento de sessão, codificação de mensagens e tratamento de recibos de entrega.

Passo 2: Exemplo Básico de Conexão SMPP

Conectar-se a um servidor SMPP requer estabelecer uma sessão e vinculá-la ao Ozeki SMS Gateway. O seguinte código Java demonstra como criar um cliente SMPP simples usando a biblioteca jSMPP: 

import org.jsmpp.*;
import org.jsmpp.bean.*;
import org.jsmpp.session.*;

public class SimpleSMPPClient {
    public static void main(String[] args) {
        SMPPSession session = new SMPPSession();
        try {
            // Conectar e vincular ao Ozeki SMS Gateway
            session.connectAndBind(
                "your.ozeki.server", 
                2775, 
                new BindParameter(
                    BindType.BIND_TX, 
                    "your_username", 
                    "your_password", 
                    "cp", 
                    TypeOfNumber.ALPHANUMERIC, 
                    NumberingPlanIndicator.UNKNOWN, 
                    null)
            );
            
            System.out.println("Conectado com sucesso ao servidor SMPP");
            
            // Adicione o código de envio de mensagem aqui
            
        } catch (Exception e) {
            System.err.println("Falha ao conectar e vincular ao servidor SMPP: " + e.getMessage());
        } finally {
            session.unbindAndClose();
        }
    }
}

Neste exemplo, substitua your.ozeki.server, your_username, e your_password pelas credenciais reais fornecidas pelo administrador do Ozeki SMS Gateway. O BindType.BIND_TX indica um vínculo transmissor, adequado para enviar mensagens SMS.

Gerenciamento de Conexões da API SMPP em Java para Entrega Confiável de SMS

A entrega confiável de SMS requer a manutenção de uma conexão SMPP ativa. O protocolo SMPP utiliza mensagens keep-alive (PDUs enquire_link) para garantir que a conexão permaneça ativa. Abaixo está um exemplo de como configurar as definições de keep-alive e monitorar alterações de estado de sessão em Java: 

session.setEnquireLinkTimer(30000); // Enviar keep-alive a cada 30 segundos
session.setTransactionTimer(10000); // Definir tempo limite de transação para 10 segundos

// Adicionar listener de estado de sessão para monitoramento
session.addSessionStateListener(new SessionStateListener() {
    @Override
    public void onStateChange(SessionState newState, SessionState oldState, Session source) {
        System.out.println("O estado da sessão SMPP mudou de " + oldState + " para " + newState);
    }
});

Essas configurações garantem que a conexão permaneça estável, e o listener de estado de sessão ajuda você a monitorar alterações, como desconexões, para um tratamento robusto de erros.

Enviando SMS com Java através da API SMPP

Uma vez conectado, você pode enviar mensagens SMS usando o PDU submit_sm. O seguinte método Java demonstra como enviar um SMS usando a API SMPP em Java: 

public static void sendSMS(SMPPSession session, String sender, String recipient, String message) throws Exception {
    try {
        String messageId = session.submitShortMessage(
            "CMT", // Tipo de serviço
            TypeOfNumber.ALPHANUMERIC, // TON de origem
            NumberingPlanIndicator.UNKNOWN, // NPI de origem
            sender, // Endereço do remetente
            TypeOfNumber.INTERNATIONAL, // TON de destino
            NumberingPlanIndicator.ISDN, // NPI de destino
            recipient, // Endereço do destinatário
            new ESMClass(), // Classe ESM
            (byte)0, // ID do protocolo
            (byte)1, // Flag de prioridade
            null, // Tempo de entrega agendado
            null, // Período de validade
            new RegisteredDelivery(SMSCDeliveryReceipt.SUCCESS_FAILURE), // Recibo de entrega
            (byte)0, // Flag de substituição se presente
            new GeneralDataCoding(Alphabet.ALPHA_DEFAULT), // Codificação de dados
            (byte)0, // ID da mensagem padrão
            message.getBytes() // Conteúdo da mensagem
        );
        
        System.out.println("SMS enviado com ID da mensagem: " + messageId);
    } catch (PDUException e) {
        System.err.println("Parâmetro PDU inválido: " + e.getMessage());
        throw e;
    } catch (ResponseTimeoutException e) {
        System.err.println("Tempo limite de resposta: " + e.getMessage());
        throw e;
    } catch (InvalidResponseException e) {
        System.err.println("Resposta inválida: " + e.getMessage());
        throw e;
    } catch (NegativeResponseException e) {
        System.err.println("Resposta negativa recebida: " + e.getMessage());
        throw e;
    } catch (Exception e) {
        System.err.println("Falha ao enviar SMS: " + e.getMessage());
        throw e;
    }
}

Este método envia um SMS com rastreamento de recibo de entrega habilitado. O parâmetro RegisteredDelivery garante que você receba notificações sobre o status de entrega da mensagem.

Tratando Relatórios de Entrega de SMS com Java e a API SMPP

Para rastrear se um SMS foi entregue com sucesso, você pode vincular sua sessão SMPP como um transceptor (BindType.BIND_TRX) e implementar um listener de receptor de mensagens. Abaixo está um exemplo de como tratar relatórios de entrega em Java: 

// Vincular como transceptor para enviar e receber mensagens
BindParameter bindParam = new BindParameter(
    BindType.BIND_TRX,
    "seu_usuario",
    "sua_senha",
    "cp",
    TypeOfNumber.ALPHANUMERIC,
    NumberingPlanIndicator.UNKNOWN,
    null
);

// Definir listener de receptor de mensagens para relatórios de entrega
session.setMessageReceiverListener(new MessageReceiverListener() {
    @Override
    public void onAcceptDeliverSm(DeliverSm deliverSm) {
        if (MessageType.SMSC_DEL_RECEIPT.containedIn(deliverSm.getEsmClass())) {
            DeliveryReceipt delReceipt = deliverSm.getShortMessageAsDeliveryReceipt();
            System.out.println(String.format(
                "Recebido recibo de entrega para a mensagem %s: %s",
                delReceipt.getId(),
                delReceipt.getFinalStatus()
            ));
        }
        
        // Responder ao relatório de entrega
        try {
            byte[] messageId = new byte[]{1};
            session.deliverSmResponse(0, messageId, deliverSm);
        } catch (PDUException e) {
            System.err.println("Falha ao responder a deliver_sm: " + e.getMessage());
        }
    }
});

Este código processa recibos de entrega, permitindo que você rastreie o sucesso ou falha de cada SMS enviado através da API SMPP em Java.

Cliente Java SMPP Completo para Envio de SMS via API SMPP

Abaixo está uma classe Java completa que integra gerenciamento de conexão, envio de mensagens, e tratamento de relatórios de entrega. Esta implementação está pronta para produção com tratamento adequado de erros e gerenciamento de recursos: 

import org.jsmpp.*;
import org.jsmpp.bean.*;
import org.jsmpp.session.*;
import org.jsmpp.util.*;

public class SMPPClient implements AutoCloseable {
    private SMPPSession session;
    private String host;
    private int port;
    private String username;
    private String password;
    
    public SMPPClient(String host, int port, String username, String password) {
        this.host = host;
        this.port = port;
        this.username = username;
        this.password = password;
        this.session = new SMPPSession();
    }
    
    public void connect() throws Exception {
        try {
            BindParameter bindParam = new BindParameter(
                BindType.BIND_TRX,
                username,
                password,
                "cp",
                TypeOfNumber.ALPHANUMERIC,
                NumberingPlanIndicator.UNKNOWN,
                null
            );
            
            session.connectAndBind(host, port, bindParam);
            
            // Configurar parâmetros da sessão
            session.setEnquireLinkTimer(30000);
            session.setTransactionTimer(10000);
            
            // Configurar o listener de relatórios de entrega
            session.setMessageReceiverListener(new DeliveryReceiptListener());
            
            System.out.println("Conectado com sucesso ao servidor SMPP");
        } catch (Exception e) {
            System.err.println("Falha ao conectar ao servidor SMPP: " + e.getMessage());
            throw e;
        }
    }
    
    public String sendSMS(String sender, String recipient, String message) throws Exception {
        try {
            return session.submitShortMessage(
                "CMT",
                TypeOfNumber.ALPHANUMERIC,
                NumberingPlanIndicator.UNKNOWN,
                sender,
                TypeOfNumber.INTERNATIONAL,
                NumberingPlanIndicator.ISDN,
                recipient,
                new ESMClass(),
                (byte)0,
                (byte)1,
                null,
                null,
                new RegisteredDelivery(SMSCDeliveryReceipt.SUCCESS_FAILURE),
                (byte)0,
                new GeneralDataCoding(Alphabet.ALPHA_DEFAULT),
                (byte)0,
                message.getBytes()
            );
        } catch (Exception e) {
            System.err.println("Falha ao enviar SMS: " + e.getMessage());
            throw e;
        }
    }
    
    @Override
    public void close() {
        if (session != null) {
            session.unbindAndClose();
        }
    }
    
    private static class DeliveryReceiptListener implements MessageReceiverListener {
        @Override
        public void onAcceptDeliverSm(DeliverSm deliverSm) {
            if (MessageType.SMSC_DEL_RECEIPT.containedIn(deliverSm.getEsmClass())) {
                DeliveryReceipt delReceipt = deliverSm.getShortMessageAsDeliveryReceipt();
                System.out.println(String.format(
                    "Relatório de entrega recebido para a mensagem %s: %s",
                    delReceipt.getId(),
                    delReceipt.getFinalStatus()
                ));
            }
        }
    }
    
    public static void main(String[] args) {
        try (SMPPClient client = new SMPPClient(
                "your.ozeki.server", 
                2775, 
                "your_username", 
                "your_password")) {
            
            client.connect();
            
            String messageId = client.sendSMS(
                "12345", 
                "+1234567890", 
                "Olá do cliente Java SMPP!"
            );
            
            System.out.println("SMS enviado com ID: " + messageId);
            
            // Manter o aplicativo em execução para receber relatórios de entrega
            System.out.println("Pressione Ctrl+C para sair...");
            Thread.sleep(Long.MAX_VALUE);
            
        } catch (Exception e) {
            System.err.println("Erro no cliente SMPP: " + e.getMessage());
        }
    }
}

Esta implementação completa encapsula a funcionalidade do cliente SMPP em uma classe reutilizável, facilitando a integração em aplicações Java maiores. A interface AutoCloseable garante o gerenciamento adequado de recursos.

Melhores Práticas para Construir Clientes Java SMPP

Para garantir que seu cliente Java SMPP API seja robusto e escalável, siga estas melhores práticas:

  • Pool de Conexões: Use pool de conexões para aplicações de SMS de alto volume para gerenciar várias sessões SMPP com eficiência.
  • Tratamento de Exceções: Implemente tratamento abrangente de exceções para recuperar-se de problemas de rede ou erros do servidor.
  • Pools de Threads: Use pools de threads para processamento concorrente de mensagens e melhore o desempenho.
  • Enfileiramento de Mensagens: Implemente um mecanismo de fila para garantir entrega confiável de mensagens durante interrupções de rede.
  • Monitoramento de Conexão: Monitore o estado da sessão SMPP e implemente lógica de reconexão automática para maior confiabilidade.
  • Codificação de Caracteres: Lide com diferentes codificações de caracteres (ex: GSM 7-bit, UCS-2) para suportar mensagens SMS internacionais.
Conclusão

Implementar a API SMPP em Java com o Ozeki SMS Gateway fornece uma solução poderosa para enviar e receber mensagens SMS em suas aplicações. A biblioteca jSMPP simplifica as complexidades do protocolo SMPP, permitindo que os desenvolvedores se concentrem em construir recursos robustos de mensagens. Este guia abordou o essencial para configurar um cliente Java SMPP, gerenciar conexões, enviar mensagens SMS e tratar relatórios de entrega. Seguindo os exemplos e melhores práticas fornecidos, você pode criar aplicações de SMS escaláveis e confiáveis usando Java e a API SMPP.

Para ambientes de produção, considere adicionar recursos avançados como concatenação de mensagens para SMS longos, registro detalhado de logs e monitoramento de desempenho. O protocolo SMPP oferece capacidades adicionais, como agendamento de entrega de mensagens e configurações de prioridade, para aprimorar sua aplicação conforme os requisitos evoluem.

More information