Ir para o conteúdo

Guia da API RESTful SMSBAT

Guia completo para a API RESTful SMSBAT – tudo o que você precisa saber.

Última atualização: 29 de agosto de 2025

A API RESTful SMSBAT permite que você envie vários tipos de mensagens: Viber-carousel, Viber-survey, Viber-promo (imagens, vídeo), chats de negócios Viber, mensagens OTP (Viber OTP, Flash Call) e suas variantes substitutas.

Observação: Esta é a API HTTP unificada para mensagens de saída. Se você precisar de integrações com bots de entrada (Viber Bot/Telegram Bot), consulte a API Cascade.

1. Protocolo

  • Protocolo: HTTPS
  • Request Body: objeto JSON contendo um array de messages.
  • Métodos:
  • GET para buscar dados (status da mensagem, saldo, etc.)
  • POST para criar objetos (por exemplo, iniciar uma transmissão/despacho)
  • PATCH para modificar objetos

2. Autorização

Fornecemos vários métodos de autorização para sua conveniência: - Autenticação HTTP Básica (login e senha do seu painel). - Cabeçalho HTTP personalizado X-Authorization-Key contendo um token de API. - Campo de senha de autenticação básica HTTP contendo o token da API (passe @ como login).

API Token pode ser gerado no Dashboard em User Profile.

Exemplos de solicitação

Com autenticação básica: 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

Com X-Autorização-Chave: 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Envio de mensagens

Na plataforma SMSBAT, qualquer envio de mensagem (mesmo uma única mensagem) é considerado uma “Broadcast” (lista de mensagens).

Ponto final - Método: POSTAR - URL: https://api.smsbat.com/bat/messagelist - Cabeçalhos: Tipo de conteúdo: aplicativo/json

Estrutura básica de carga útil: 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Campos obrigatórios para cada objeto de mensagem:

  • from: Nome alfa do remetente verificado.
  • to: Número de telefone do destinatário (formato E.164).
  • type: enum do tipo de mensagem.
  • text: Texto principal da mensagem (opcional se o tipo não requer texto).

Valores type suportados: - sm - viber_service (ou viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

Campos Comuns Opcionais:

  • customerMessageId: String ID dentro do seu próprio sistema (usado para rastrear retornos de chamada). Deve ser exclusivo por mensagem.
  • dtSend: Data/Hora ISO8601 de envio futuro programado.
  • dtExpire: ISO8601 Data/Hora do prazo de entrega.
  • ttl: Tempo de vida em segundos. (Se dtExpire não for fornecido, a API calcula o mapeamento padrão a partir do type).

TTLs padrão (segundos):

  • sms - 86400 (24h)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. Roteamento substituto (em cascata)

Você pode especificar uma fila de fallback para garantir a entrega de mensagens se o canal primário falhar ou expirar.

CODE_BLOCO_3 Os fallbacks são acionados quando o provedor rejeita a mensagem principal ou quando o TTL expira.

5. Visão geral dos tipos de mensagens e dados de mensagens

Tipos de mensagens complexos requerem configurações adicionais injetadas na propriedade messageData.

5.1 Promoção Viber (viber_promo)

Somente imagem 

"messageData":{
  "img":"https://domain.com/image.png"
}

Texto + Botão CODE_BLOCO_5

Imagem + Texto + Botão Combina img, buttonText e buttonAction.

Carga útil de vídeo: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Você também pode combinar propriedades de vídeo com buttonText e buttonAction).

5.2 Viber Transacional/Serviço (viber_trans, viber_service)

Se você tiver um modelo aprovado contendo um arquivo anexado: 

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

Requer um array carousel.items dentro de messageData.

Limitações: - Comprimento dos itens: entre 2 e 5 itens - Título: 2 a 38 caracteres - imageUrl: tamanho recomendado JPEG/PNG 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Pesquisa/lista do Viber (viber_survey)

Cria uma enquete interativa na visualização do chat. CODE_BLOCO_9 A propriedade text da mensagem atua como o título da pesquisa (máximo de 85 caracteres). Você pode passar entre 2 e 5 opções, cada uma com no máximo 50 caracteres.

5.5 Viber OTP (viber_otp)

Usa modelos Viber localizados pré-registrados globalmente. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Os parâmetros do modelo (pin, business_platform_name) diferenciam estritamente maiúsculas de minúsculas. A API suporta várias variantes de linguagem de código ISO (EN, ES, RU, TR, UK, etc.).

5.6 Chamada Flash (flashcall)

Os últimos dígitos do número discado (código gerado) devem ser passados através do parâmetro texto. Se text for omitido, o código será randomizado e você deverá extraí-lo do corpo da resposta síncrona 200 OK da API (messages/text).

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}