FB

API para envios de SMS




Integração

INTRODUCTION

Bem vindo!. Está página é exclusivamente dedicada à desenvolvedores de software e profissionais da área. Aqui você encontra todas informações necessárias para integrar seu sistema com nosso gateway, para enviar mensagens e receber status de entrega e respostas dos usuários de forma automática.


Nesta página você encontra documentação para as seguintes formas:

  • API REST

    • Seu sistema deve realizar uma chamada para a URL http://54.233.99.254/webservice-rest/, enviando os parâmetros por meio de GET ou POST. O retorno para cada chamada será um JSON cujo formato é detalhado ao longo desta documentação.

Autenticação

É recomendado que todas as requisições a API HTTP utilize para autenticação cabeçalhos Basic Authorization em vez de parâmetros query string. Neste campo deve ser informado seu usuário e senha cadastrados em nosso site. Caso haja erro na autenticação, o respectivo código de erro será retornado.

Authorization: Basic dXN1YXJpbzpzZW5oYQ=

O valor após a palavra Basic é uma chave Base64 de seu usuário e senha. Para obter o valor, utilize o comando base64 do linux:

$ echo -n conta:senha | base64 
dXN1YXJpbzpzZW5oYQ=

O site base64Encode também faz essa codificação gratuitamente.

Headers

Chamadas realizadas exclusivamente para API HTTP Envio em Lote devem incluir, além do cabeçalho de autenticação, os seguintes headers:

Content-Type:application/json
Accept:application/json

Restantes API HTTP, além do cabeçalho de autenticação devem incluir os seguintes headers:

Content-Type:application/x-www-form-urlencoded

Parâmetro campaign_id

campaign_id

Ao enviar uma requisição, recomendamos que você utilize este parâmetro. Ele serve como um identificador de sua mensagem em nossa plataforma e pode ser utilizado para consulta de status. Este parâmetro também possui a funcionalidade de proteção contra envios duplicados (habilite esta função com nosso suporte).

Parâmetro type

type

Ao enviar uma requisição, é necessário que você utilize este parâmetro. Ele serve para identificar o tipo do serviço da mensagem.

 

Veja abaixo a tabela contendo os valores aceitos para este parâmetro:

type Tipo do Serviço
0 SMS
1 SMS Interativo(Modo Flash)
2 SMS Interativo
3 Torpedo de Voz (Apenas Texto)
4 Torpedo de Voz (Áudio)
5 Whatsapp (Apenas Texto)
6 Whatsapp (Imagem)
7 Whatsapp (Áudio)
8 Whatsapp (Vídeo)

Limitações

Restringimos em 20 conexões simultâneas por usuário.

Tabela de Status

Existem dois tipos de status, um obtido através da chamada à API (Cliente->Gateway), denominado Status de Chamada e outro através da obtenção do status da mensagem em nosso servidor (Gateway->Operadora), denominado Status de Envio.

Status de Chamada

As chamadas à API irão retornar dois parâmetros de status, um numérico denominado responseCode e o outro alfanumérico denominado responseDescription, os dois correspondem a mesma informação.

A seguir, veja a lista de status suportados pela nossa API:

API de Envio
API de Consulta
Todas API
responseCode responseDescription success
000 Success queued true
001 Batch processed true
002 Scheduled true
010 User or password is invalid false
020 Empty or invalid type false
030 Empty message content false
040 Scheduling date invalid or incorrect false
050 Empty or invalid number false
060 International sending not allowed false
070 Message rejected by server false
080 Insufficient or expired balance false
090 Blocked account - Please contact support false
100 This service is currently under maintenance false
110 There was an error processing, please try again, or contact us false
120 Message array cannot exceed 5000 false
130 Message array is empty false
140 Incorrect time zone false
150 File extension not allowed false
160 Unknown method or unknown parameter false
170 Invalid search attributes false
200 Successful search true

Status de Envio

Status obtidos através da API de Consulta ou Callback podem possuir três níveis, conforme a seguir:

Status de preparação da mensagem para envio, este status e não é retornado por Callback:

Status Description
-1 Message Queued
3 Preparing message to send
6 Paused Message

Status de entrega na operadora, este é o primeiro status que retornamos por Callback:

Status Description
-9 Blocked - No Coverage
-8 Blocked - Content not allowed
-7 Number has no WhatsApp (Only for WhatsApp)
-6 Message successfully canceled
-5 Blocked - Black listed
-4 Blocked - landline Number
-3 Blocked - Invalid Number
0 Message received to operator
7 Message expired by operator
8 Message Rejected by operator

Status de entrega no aparelho, este é o segundo status que retornamos por Callback e só existe para os casos em que o primeiro status acima foi de sucesso, ou seja, a mensagem foi entregue na operadora com sucesso. Para SMS, as operadoras Oi e Sercomtel não possuem este segundo nível de status, para estas operadoras, o máximo de informação que existe, é o primeiro status, ou seja, se a operadora aceitou a mensagem ou não.:

Status Description
-2 Operator network error
1 Message received by mobile
9 Message not received by mobile
 

REFERENCE

Serviços da API

Envio Individual


Este método é indicado para clientes que realizão requisições contendo apenas um destinatário. Ele utiliza protocolos HTTP e HTTPS, aceita os métodos GET e POST com parâmetros query string.

- URL para envio individual

http://54.233.99.254/webservice-rest/send-single

- Instruções para chamada

A requisição precisa conter parâmetros Query String com as informações conforme campos abaixo:

* Campo obrigatório

Campo Detalhes Tipo
user* Nome do usuário cadastrado em nosso site, obrigatório caso não utilize cabeçalho de autenticação. string
password* Senha de acesso do usuário, obrigatório caso não utilize cabeçalho de autenticação. string
type* Tipo do serviço, consulte o menu "Parâmetro type". number
country_code DDI do país de destino. (Padrão: 55) number
number* Número do telefone do destinatário sem DDI (55). number
content* (SMS):Texto da mensagem a ser enviada. string
(WHATSAPP Texto):Texto da mensagem a ser enviada. string
(WHATSAPP Imagem):URL da imagem hospedada em seu servidor. Aceito arquivo .jpg com até 1MB e máximo 1024 pixels. string
(WHATSAPP Vídeo):URL do vídeo hospedado em seu servidor. Aceito arquivo .mp4 com até 2MB. string
caption (SMS):Parâmetro não utilizado. string
(WHATSAPP):Texto com até 490 caracteres para legenda de imagem ou vídeo. string
campaign_id Identificador da mensagem no sistema do cliente. string
schedule Data e hora em que a mensagem deve ser enviada no formato ISO 8691 (2020-11-01 15:00:00). string
timezone Fuso horário em formato UTC (-03:00). string

Clique abaixo e veja exemplos em várias linguagens de programação:

Em resposta à chamada, a API retornará um arquivo JSON com as informações necessárias para rastreio, será gerado um id e status do processo:

    {
            "success" : true,
            "responseCode" : "000",
            "responseDescription" : "Success queued",
            "credit" : "0"
            "balance" : "99984"
            "id" : "813831"
    }

Outro exemplo de retorno síncrono da chamada:

    {
            "success" : false,
            "responseCode" : "080",
            "responseDescription" : "Insufficient or expired balance",
            "credit" : "0"
            "balance" : "0"
    }
Campo Detalhes Tipo
success Este campo indica se a requisição obteve sucesso ou não. boolean
responseCode Este campo indica o código do status da requisição. string
responseDescription Este campo indica a descrição do status da requisição. string
credit Este campo indica quantos créditos foram debitados em sua conta. string
balance Este campo indica o saldo atual de créditos em sua conta. string
id Caso a mensagem seja aceita, é retornado um código id único para rastreio. string

Para receber retornos assíncronos, consulte o menu "Callbacks da API".

Envio em Lote

 

Permite o envio de mensagens em lote ou individuais passando os parâmetros por POST em um objeto JSON

- URL para envio em Lote

http://54.233.99.254/webservice-rest/send-multiple

- Instruções para chamada

O corpo da requisição precisa conter o objeto JSON com as informações conforme campos abaixo:

* Campo obrigatório

Campo Detalhes Tipo
type* Tipo do serviço, consulte o menu "Parâmetro type". number
country_code DDI do país de destino. (Padrão: 55) number
number* Número do telefone do destinatário sem DDI (55). number
content* (SMS):Texto da mensagem a ser enviada. string
(WHATSAPP Texto):Texto da mensagem a ser enviada. string
(WHATSAPP Imagem):URL da imagem hospedada em seu servidor. Aceito arquivo .jpg com até 1MB e máximo 1024 pixels. string
(WHATSAPP Vídeo):URL do vídeo hospedado em seu servidor. Aceito arquivo .mp4 com até 2MB. string
caption (SMS):Parâmetro não utilizado. string
(WHATSAPP):Texto com até 490 caracteres para legenda de imagem ou vídeo. string
campaign_id Identificador da mensagem no sistema do cliente. string
schedule Data e hora em que a mensagem deve ser enviada no formato ISO 8691 (2020-11-01 15:00:00). string
timezone Fuso horário em formato UTC (-03:00). string

Importante: Não é permitido o envio de mais de 5000 mensagens por requisição.

Clique abaixo e veja exemplos em várias linguagens de programação:

 

Testar Envio em Lote

 

Veja a seguir o exemplo da chamada acima:


    {
  "defaultValues":{
                   "type": 2,
                   "schedule": "2025-08-22 14:55:00",
                   "timezone": "-03:00"
              },
     "messages":[
                 {
                   "country_code": 55,
                   "number": 14999999999,
                   "content": "Mensagem de teste",
                   "campaign_id": "001"
                 },
                 {
                   "country_code": 55,
                   "number": 14999999999,
                   "content": "Mensagem de teste",
                   "campaign_id": "002"
                  }
              ]
    }              

Em resposta à chamada, a API retornará informações do processo conforme abaixo:


{
    "success": true,
    "responseCode": "001",
    "responseDescription": "Batch processed",
    "credit": "2",
    "balance": "87018",
    "totalProcessed": "2",
    "totalSuccess": "2",
    "messages": [
        {
            "success": true,
            "responseCode": "000",
            "responseDescription": "Success queued",
            "credit": "1"
        },
        {
            "success": true,
            "responseCode": "000",
            "responseDescription": "Success queued",
            "credit": "1"
        }
    ]
}

Outro exemplo de retorno síncrono da chamada:


{
    "success": true,
    "responseCode": "001",
    "responseDescription": "Batch processed",
    "credit": "1",
    "balance": "87018",
    "totalProcessed": "2",
    "totalSuccess": "1",
    "messages": [
        {
            "success": true,
            "responseCode": "000",
            "responseDescription": "Success queued",
            "credit": "1"
        },
        {
            "success": true,
            "responseCode": "050",
            "responseDescription": "Empty or invalid number",
            "credit": "0"
        }
    ]
}

Para receber retornos assíncronos, consulte o menu "Callbacks da API".

Consulta de Status por Identificador

Para consultar o status das mensagens enviadas é necessário fazer uma requisição GET OU POST na URL abaixo passando como parâmetro o id ou o campaign_id obtido na resposta do envio

GET http://54.233.99.254/webservice-rest/mt_id

Importante: a consulta fica disponível por até 32 dias após seu envio.

Abaixo exemplo de requisições realizando a consulta por id e por campaign_id, é possivel também realizar a consulta em lote, para isso basta separar os identificadores com vírgulas

Consulta id:

GET http://54.233.99.254/webservice-rest/mt_id?user={user}&password={password}&id=1,2

Consulta campaign_id:

GET http://54.233.99.254/webservice-rest/mt_id?user={user}&password={password}&campaign_id=abc1,abc2

Clique abaixo e veja exemplos em várias linguagens de programação:

Consulta de Status por Período

Está requisição de busca irá retornar cada mensagem enviada num determinado período de tempo. Você precisa definir os parâmetros start_date e end_date para especificar um período de tempo, deverá ser utilizado o formato ISO-8601.

GET http://54.233.99.254/webservice-rest/mt_date

Importante: a consulta fica disponível por até 32 dias após seu envio.

Abaixo exemplo de requisição de consulta por período de tempo e tipo de serviço, através do parâmetro type.

GET http://54.233.99.254/webservice-rest/mt_date?user={user}&password={password}&start_date=2016-09-12T00:00:00&end_date=2016-09-15T23:59:59&type=2

Abaixo exemplo de requisição de consulta por período de tempo, tipo de serviço e status, através do parâmetro type e status.

GET http://54.233.99.254/webservice-rest/mt_date?user={user}&password={password}&start_date=2016-09-12T00:00:00&end_date=2016-09-15T23:59:59&type=2&status=0,1

Clique abaixo e veja a documentação completa  https://integracao.docs.apiary.io