Help Center Compatibilidade com API GMS

Compatibilidade com API GMS

SMSBAT oferece suporte a uma camada de compatibilidade com a API GMS. Isso permite que você migre suas integrações existentes projetadas para GMS diretamente para SMSBAT sem precisar modificar seus esquemas de roteamento de mensagens, estruturas de carga útil ou ouvintes de retorno de chamada.

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/GMSMessage/send_message
Formato de solicitação: application/json
Autenticação: Autenticação básica HTTP (usa suas credenciais da API SMSBAT)

Parâmetros de solicitação

A API de compatibilidade GMS aceita um objeto JSON com os seguintes parâmetros de nível superior:

Parâmetro	Tipo	Obrigatório	Descrição
`número_telefone`	corda	Sim	Número de telefone do destinatário em formato internacional (por exemplo, `380501234567`).
`etiqueta`	corda	Sim	Nome do remetente registrado/nome alfa.
`canais`	matriz	Sim	Lista de canais para experimentar, em ordem de prioridade. Valores suportados: `viber`, `sms`, `push`. Por exemplo, `["viber", "sms"]`.
`canal_opções`	objeto	Sim	Mapa contendo opções para cada canal ativo (veja abaixo).
`id_extra`	corda	Não	Seu ID de mensagem interno do cliente.
`url_de retorno`	corda	Não	URL do endpoint em seu sistema para receber retornos de chamada de status de entrega.
`divisão_código`	corda	Não	Identificador de código de divisão opcional (o padrão é `main`).

Configurações de opções de canal

O objeto channel_options contém configurações específicas do canal.

Usado quando viber está listado na matriz channels.

Parâmetro	Tipo	Obrigatório	Descrição
`texto`	corda	Sim	Texto do corpo da mensagem.
`ttl`	inteiro	Sim	Tempo de vida em segundos.
`img`	corda	Não	URL HTTPS público da imagem a ser exibida.
`legenda`	corda	Não	Etiqueta de texto do botão.
`ação`	corda	Não	URL de destino quando o botão é clicado.
`opções_de_pesquisa`	matriz	Não	Matriz de strings (2 a 5 itens) para exibir como opções de pesquisa.
`carousel_items`	matriz	Não	Matriz de objetos de slide para exibir como um carrossel do Viber (veja a estrutura na aba).

Exemplo de solicitação do Viber:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Permite mensagens do Viber com um substituto automático de SMS se a entrega do Viber falhar dentro do TTL.

Exemplo de solicitação de substituto:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Usado quando sms está listado na matriz channels.

Parâmetro	Tipo	Obrigatório	Descrição
`texto`	corda	Sim	Texto do corpo da mensagem.
`nome_alfa`	corda	Sim	Nome alfa do remetente.
`ttl`	inteiro	Sim	Tempo de vida em segundos.
`ctr`	booleano	Não	Ative o rastreamento de cliques CTR em links em texto (`true`/`false`).

Exemplo de solicitação de SMS:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Usado para criar enquetes e pesquisas Viber.

Warning

A configuração da pesquisa Viber deve ter entre 2 e 5 opções dentro de survey_options.

Exemplo de solicitação de pesquisa:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Usado para enviar cartões deslizantes com imagens deslizantes. Cada slide suporta imagem, título e botões.

Exemplo de solicitação de carrossel:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}

Usado quando push está listado no array channels.

Parâmetro	Tipo	Obrigatório	Descrição
`título`	corda	Sim	Texto do título da notificação push.
`texto`	corda	Sim	Texto do corpo da mensagem.
`ttl`	inteiro	Sim	Tempo de vida em segundos.
`img`	corda	Não	URL HTTPS público da imagem a ser exibida.
`legenda`	corda	Não	Etiqueta de texto do botão.
`ação`	corda	Não	URL de destino quando o botão é clicado.
`ctr`	booleano	Não	Ative o rastreamento de cliques.

Exemplo de solicitação push:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Formato de resposta

O endpoint retorna respostas em formato JSON com um código de status HTTP 200 OK.

Resposta bem-sucedida

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Respostas de erro

Se a validação ou o processamento falhar, uma resposta de erro com um ErrorCode não nulo e um ErrorText detalhado será retornada.

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Formato de entrega de retorno de chamada

Se callback_url foi especificado na solicitação, o SMSBAT envia atualizações de status de entrega como uma carga JSON POST para seu endpoint.

Exemplo de solicitação de retorno de chamada

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Descrição dos campos de retorno de chamada

Campo	Tipo	Descrição
`número`	corda	Número de telefone do destinatário.
`tempo`	número	Carimbo de data/hora do evento em milissegundos Unix.
`estado`	número	Identificador de status simplificado (consulte a tabela de códigos de status).
`substatus`	número	Identificador de status detalhado (consulte a tabela de códigos de substatus).
`hyber_status`	número	Código de status interno SMSBAT detalhado (consulte a tabela Hyber Status).
`id_da_mensagem`	corda	ID da mensagem SMSBAT (GUID) gerado no envio.
`id_extra`	corda	ID do cliente fornecido na solicitação original.
`enviado_via`	corda	Canal que processou a mensagem: `viber`, `sms` ou `rcs`.
`matching_template_id`	número	Status de correspondência do modelo Viber (quando aplicável).

Mapeamentos de status

1. Status simplificado (`status`)

Código	Significado
`1`	Mensagem aceita ou sendo entregue.
`2`	Mensagem entregue.
`3`	Erro de processamento ou entrega.

2. Status detalhado (`substatus`)

Código	Significado
`12`	Aceito para processamento.
`23`	Entregue.
`24`	Visto/lido.
`35`	Não entregue dentro do TTL (Expirado).
`36`	Erro de entrega.

3. Tipo de canal (`enviado_via`)

Canal	Descrição
`viber`	Status produzido pelo canal Viber.
`sm`	Status produzido pelo canal SMS.
`rcs`	Status produzido pelo canal RCS.

4. Status detalhado do SMSBAT (`hyber_status`)

Código	Canal	Estado	Substatus	Significado
23033	`viber`	`2`	`23`	Mensagem Viber entregue.
24013	`viber`	`2`	`24`	Mensagem do Viber lida pelo destinatário (vista).
36013	`viber`	`3`	`36`	Erro interno do Viber.
36023	`viber`	`3`	`36`	ID de serviço Viber inválido ou indisponível.
36033	`viber`	`3`	`36`	Dados de carga útil do Viber inválidos.
36037	`viber`	`3`	`36`	URL da imagem do Viber muito longo.
36038	`viber`	`3`	`36`	URL de imagem Viber inválido.
36039	`viber`	`3`	`36`	Texto do Viber muito longo.
36044	`viber`	`3`	`36`	Texto vazio do Viber.
36053	`viber`	`3`	`36`	Tipo de mensagem Viber não compatível.
36063	`viber`	`3`	`36`	Parâmetros Viber inválidos.
36073	`viber`	`3`	`36`	Tempo limite do provedor Viber.
36083	`viber`	`3`	`36`	Remetente Viber bloqueado pelo destinatário.
36093	`viber`	`3`	`36`	O destinatário não está registrado como usuário Viber.
36103	`viber`	`3`	`36`	Nenhum dispositivo Android/iOS com suporte Viber encontrado.
36113	`viber`	`3`	`36`	Endereço IP não autorizado para envio do Viber.
36123	`viber`	`3`	`36`	Mensagem duplicada do Viber detectada.
36143	`viber`	`3`	`36`	Erro de faturamento do Viber.
36153	`viber`	`3`	`36`	Mensagem bloqueada pela lista negra da plataforma.
36163	`viber`	`3`	`36`	Erro de processamento interno da plataforma Viber.
36173	`viber`	`3`	`36`	Rótulo Viber errado ou ausente.
36183	`viber`	`3`	`36`	Valor Viber TTL inválido.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS aceitos.
36011	`sms` / `rcs`	`1`	`12`	Rota SMS/RCS.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS entregues.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS expirado (não entregue dentro do TTL).
36021	`sms` / `rcs`	`3`	`36`	Mensagem SMS/RCS excluída.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS não podem ser entregues.
36041	`sms` / `rcs`	`3`	`36`	Status de entrega de SMS/RCS desconhecido.
36051	`sms` / `rcs`	`3`	`36`	Mensagem SMS/RCS rejeitada.

Search Results

Compatibilidade com API GMS

Configurações de conexão

Parâmetros de solicitação

Configurações de opções de canal

Formato de resposta

Resposta bem-sucedida

Respostas de erro

Formato de entrega de retorno de chamada

Exemplo de solicitação de retorno de chamada

Descrição dos campos de retorno de chamada

Mapeamentos de status

1. Status simplificado (status)

2. Status detalhado (substatus)

3. Tipo de canal (enviado_via)

4. Status detalhado do SMSBAT (hyber_status)

1. Status simplificado (`status`)

2. Status detalhado (`substatus`)

3. Tipo de canal (`enviado_via`)

4. Status detalhado do SMSBAT (`hyber_status`)