Compatibilidade da API Messagio

SMSBAT oferece suporte a uma camada de compatibilidade com a API Messagio. Isso permite que você migre suas integrações Viber existentes projetadas para Messagio diretamente para SMSBAT sem precisar reescrever sua estrutura de carga útil ou alterar a lógica de integração.

Configurações de conexão

Para rotear solicitações por meio de SMSBAT, atualize a URL base e as credenciais de autenticação em sua integração:

URL base: https://restapi.smsbat.com
Ponto final: POST /api/SendMessage
Formato de solicitação: application/x-www-form-urlencoded (dados do formulário)

Autenticação e credenciais

As solicitações são autenticadas usando parâmetros enviados diretamente nos dados do formulário do corpo da solicitação:

Parâmetro	Tipo	Obrigatório	Descrição
`usuário`	corda	Sim	O login da sua conta SMSBAT ou identificador de usuário.
`sinal`	corda	Sim	Segredo ou assinatura da API registrada para o nome do remetente.
`de`	corda	Sim	Nome alfa do remetente registrado.
`metodo_de_envio`	corda	Sim	Tipo de canal. Use `viber` para mensagens regulares do Viber Business ou `viber_otp` para modelos Viber OTP.
`telefone`	corda	Sim	Número de telefone do destinatário em formato internacional (por exemplo, `380501234567`).

Tipos de mensagens Viber

Escolha uma guia abaixo para visualizar os parâmetros específicos e solicitar cargas para diferentes estruturas de mensagens do Viber:

Mensagem de textoTexto + BotãoMensagem de imagemTexto + Imagem + BotãoMensagem de vídeoModelo OTP

Envia uma mensagem de texto simples.

Parâmetros Adicionais:

Parâmetro	Tipo	Obrigatório	Descrição
`txt`	corda	Sim	Texto da mensagem.

Exemplo de carga útil de solicitação:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Envia uma mensagem de texto com um botão de call to action interativo.

Parâmetros Adicionais:

Parâmetro	Tipo	Obrigatório	Descrição
`txt`	corda	Sim	Texto da mensagem.
`botão_texto`	corda	Sim	Texto exibido no botão.
`botão_link`	corda	Sim	URL de destino quando o botão é clicado.

Exemplo de carga útil de solicitação:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Envia um arquivo de imagem pública.

Parâmetros Adicionais:

Parâmetro	Tipo	Obrigatório	Descrição
`image_link`	corda	Sim	URL HTTPS público da imagem.
`txt`	corda	Não	Texto de legenda opcional para exibir abaixo da imagem.

Exemplo de carga útil de solicitação:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Envia um rich card contendo texto, uma imagem e um botão.

Parâmetros Adicionais:

Parâmetro	Tipo	Obrigatório	Descrição
`txt`	corda	Sim	Texto da legenda.
`image_link`	corda	Sim	URL HTTPS público da imagem.
`botão_texto`	corda	Sim	Texto exibido no botão.
`botão_link`	corda	Sim	URL de destino quando o botão é clicado.

Exemplo de carga útil de solicitação: CODE_BLOCO_3

Envia um arquivo de vídeo com legenda de texto opcional e botões de ação.

Parâmetros Adicionais:

Parâmetro	Tipo	Obrigatório	Descrição
`vídeo.url`	corda	Sim	URL HTTPS público do arquivo de vídeo.
`vídeo.thumbnail`	corda	Sim	URL HTTPS público da imagem de visualização do vídeo.
`video.size_mb`	inteiro	Sim	Tamanho aproximado do arquivo de vídeo em Megabytes.
`video.duration_sec`	inteiro	Sim	Duração do vídeo em segundos.
`txt`	corda	Não	Texto de descrição opcional.
`botão_texto`	corda	Não	Texto do botão opcional (pode funcionar como legenda ou link).
`botão_link`	corda	Não	URL do link do botão opcional.

Exemplo de carga útil de solicitação:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Envia senhas de uso único (OTP) do Viber usando um modelo pré-aprovado.

Nota

Ao enviar mensagens OTP, você deve definir sending_method como viber_otp.

Parâmetros Adicionais:

| Parâmetro | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| `template.id` | corda | **Sim** | ID do modelo Viber OTP pré-aprovado. |
| `template.lang` | corda | **Sim** | Código de idioma do modelo (por exemplo, `en`, `uk`). |
| `template.params.pin` | corda | **Sim** | O valor do pino OTP a ser injetado no modelo. |
| `template.params.business_platform_name` | corda | **Sim** | O espaço reservado para o nome da empresa no modelo. |
| `template.params.code_validity_time` | corda | **Sim** | Período de validade do PIN em minutos. |

**Exemplo de carga útil de solicitação:**
__CODE_BLOCO_5__

Mensagem do carrosselMensagem da pesquisa

Envia um cartão de mensagem interativo contendo vários slides (cartões) que o usuário pode percorrer.

Parâmetros Adicionais:

Parâmetro	Tipo	Obrigatório	Descrição
`txt`	corda	Sim	Texto do título do carrossel.
`carrossel[N].título`	corda	Sim	Título do cartão `N` (começando em 0).
`carrossel[N].image_url`	corda	Sim	URL da imagem HTTPS pública do cartão `N`.
`carrossel[N].primary_label`	corda	Sim	Legenda do botão principal do cartão `N`.
`carrossel[N].primary_url`	corda	Sim	URL do link do botão principal do cartão `N`.
`carrossel[N].secondary_label`	corda	Não	Legenda do botão secundário do cartão `N`.
`carrossel[N].secondary_url`	corda	Não	URL do link do botão secundário do cartão `N`.

Exemplo de carga útil de solicitação:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Envia uma mensagem contendo uma enquete interativa ou pergunta de pesquisa.

Parâmetros Adicionais:

Parâmetro	Tipo	Obrigatório	Descrição
`txt`	corda	Sim	Texto da pergunta da pesquisa.
`opções_de_pesquisa[N]`	corda	Sim	Texto da opção de pesquisa para o item `N` (índice começando em 0). São necessárias pelo menos 2 opções.
`opção_tipo`	inteiro	Sim	Tipo de seletor: `1` (RadioButtons) ou `2` (Botões normais).

Exemplo de carga útil de solicitação:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

Formato de resposta

O endpoint de compatibilidade da API Messagio retorna respostas em formato XML com um código de status HTTP 200 OK.

Resposta aceita (sucesso)

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Respostas de erro

Se a validação dos parâmetros de uma solicitação falhar ou a autenticação falhar, a resposta retornará um código diferente de zero.

Assinatura ausenteNão autorizado

CODE_BLOCO_9

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Retornos de chamada

URLs de retorno de chamada devem ser implementadas e hospedadas em sua plataforma. SMSBAT envia retornos de chamada HTTP para atualizar seu sistema em relação a eventos de entrega, respostas de pesquisas e respostas de usuários.

1. Retorno de chamada de status de entrega

Enviado quando uma mensagem muda de status (entregue, lida, falhou).

Tipo de conteúdo: application/x-www-form-urlencoded
Método: POST

Solicitar formatos de carga útil:

Entregue:
```
msg_id=MESSAGE_GUID&status=delivered
```

Visto/Lido:

msg_id=MESSAGE_GUID&status=delivered&type=seen

Não entregue/Falha:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Descrição dos Campos:

msg_id: ID de mensagem exclusivo (GUID) SMSBAT retornado na resposta SendMessage.
status: Resultado da entrega (entregue, não entregue ou status desconhecido).
type: Defina como visto quando a mensagem foi visualizada pelo destinatário.
status_extended: Razão técnica específica para status não entregue (por exemplo, VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Retorno de chamada de resposta à pesquisa

Acionado quando um usuário seleciona uma opção de resposta em uma mensagem do Viber Survey.

Tipo de conteúdo: application/x-www-form-urlencoded
Método: POST

Formato de carga útil da solicitação:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Retorno de chamada de mensagem de usuário recebida

Acionado quando um usuário envia uma resposta de texto ou mídia de volta ao seu serviço Viber Business.

Tipo de conteúdo: application/json
Método: POST

Formato de carga útil da solicitação:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Descrição dos Campos:

msg_id: O ID exclusivo da mensagem gerado para a resposta de entrada.
text: Conteúdo de texto enviado pelo usuário (pode ser nulo se ele enviou apenas mídia).
media: URL direto para baixar quaisquer anexos de mídia enviados pelo usuário (pode ser null se for apenas texto).
phone: Número de telefone do remetente em formato internacional.
sender_bm_id: o ID do remetente do Viber Business.