Integração PHP – Envio de SMS na API Legada 1.0

Objetivo
O objetivo do tutorial de integração é guiar os desenvolvedores que desejam integrar suas aplicações ao gateway de SMS da Zenvia, automatizando assim seus envios de SMS conforme sua necessidade.Mostraremos em simples passos como fazer suas aplicações PHP enviarem SMS por meio da API de integração que disponibilizamos para facilitar os envios.

 

Pré-requisitos
Para executar a biblioteca de integração, basta ter instalado um servidor HTTP que interprete PHP, tal como Apache, TomCat, entre outros.Sempre utilizar o método HTTP Post para realizar os envios.
Nenhuma alteração nas configurações do PHP será necessária.

 

Entendendo a biblioteca PHP
A biblioteca PHP é um conjunto de classes que tem como principal função fazer requisições HTTP da forma mais organizada e simplificada possível, fazendo com que poucas informações sejam passadas por sua aplicação.

 

Configurando o envio

 

Primeiro passo

Faça o download da biblioteca de integração PHP, descompacte o conteúdo do arquivo dentro da pasta onde se encontrão os códigos-fontes de sua aplicação.

 

Segundo passo

Para manipulação de SMS (envios e consultas), inclua em seu código PHP o arquivo HumanClientMain.php, que se encontra na raiz do diretório da biblioteca de integração.

Exemplo:

include_once("human_gateway_client_api/HumanClientMain.php");

 

Terceiro passo

Para qualquer operação do gateway de SMS, é preciso identificar-se com sua conta e código de acesso.
Trabalharemos com a instância da classe HumanMultipleSend para manipulação múltipla de SMS (envio e consulta), passando por parâmetros de seu construtor a sua conta e o código de acesso. Tais dados são cedidos pela área de produtos da Zenvia juntamente com a negociação do contrato firmado com a empresa.

Exemplo:

$humanMultipleSend = new HumanMultipleSend("human.fake.hc", "aBc123");

 

Enviando Múltiplos SMS

 

Primeiro passo

Vamos trabalhar com a instância da classe HumanMultipleSend.

Exemplo:

$humanMultipleSend = new HumanMultipleSend("human.fake.hc", "aBc123");

 

Segundo passo

Escolheremos um layout de mensagem que será passado ao gateway, pois essa configuração influencia no formato da string que passaremos por parâmetro para o envio. Esse será passado como o primeiro parâmetro, podendo ser uma constante da classe HumanMultipleSend.

Exemplo:

$tipo = HumanMultipleSend::TYPE_C;

 

Terceiro passo

Em nosso exemplo, escolheremos o layout C, que é padrão da API, que consiste em “to;message;id“. Para adicionar mais de uma mensagem, inclua o caractere \n entre as strings.

Exemplo:

$msg_list  = "550092167288;teste0;004"."\n";
$msg_list .= "550081262695;teste1;005"."\n";
$msg_list .= "550081337773;teste2;006";

 

Quarto passo

Configuraremos o Retorno de Status por Callback , que por padrão será inativo, ou seja, igual a zero (esse parâmetro não é obrigatório). Ele pode ser passado como uma constante da classe HumanMultipleSend.

Exemplo:

$callBack = HumanMultipleSend::CALLBACK_INACTIVE
ou
$callBack = HumanMultipleSend::CALLBACK_FINAL_STATUS
ou
$callBack = HumanMultipleSend::CALLBACK_INTERMEDIARY_STATUS

 

Quinto passo

Para enviar o SMS, basta chamar o método sendMultipleList da classe HumanMultipleSend e passar os parâmetros que acabamos de definir.

Exemplo:

$responses = $humanMultipleSend->sendMultipleList($tipo, $msg_list, $callBack);

 

Sexto passo

Para obter as respostas das requisições, veja o item “Obtendo respostas das requisições“.

 

Enviando Múltiplos SMS a partir de um arquivo CSV

 

Primeiro passo

Instancie a classe MultipleMessageService, informando a sua conta e senha.

Exemplo:

$humanMultipleSend = new HumanMultipleSend("human.fake.hc", "aBc123");

 

Segundo passo

O envio de múltiplas mensagens a partir de um arquivo CSV é muito semelhante ao envio de SMS múltiplos a partir de uma string.
Passaremos por parâmetro o caminho do arquivo, respeitando os layouts de mensagens. Utilizaremos o layout C como exemplo.

Exemplo:

555199999999;teste0;004
5511999999999;teste1;005
5521999999999;teste2;005

Exemplo:

$path = "C:arquivo.csv"

 

Terceiro passo

Configuraremos o Retorno de Status por Callback, que, por padrão, será inativo, ou seja, igual a zero (esse parâmetro não é obrigatório). Ele pode ser passado como uma constante da classe HumanMultipleSend.

Exemplo: id.9hruw58bco07

$callBack = HumanMultipleSend:: CALLBACK_INACTIVE
ou
$callBack = HumanMultipleSend:: CALLBACK_FINAL_STATUS
ou
$callBack = HumanMultipleSend:: CALLBACK_INTERMEDIARY_STATUS

 

Quarto passo

Para enviar os SMS, basta chamar o método sendMultipleFileCSV da classe HumanMultipleSend e passar os parâmetros que acabamos de definir.

Exemplo:

$responses = $humanMultipleSend->;sendMultipleFileCSV($tipo, $path, $callBack);

 

Quinto passo

Para obter as respostas das requisições, veja o item “Obtendo respostas das requisições“.

 

Consultando status de SMS múltiplos

 

Primeiro passo

Vamos trabalhar com a instância da classe HumanMultipleSend.

Exemplo:

$humanMultipleSend = new HumanMultipleSend("human.fake.hc", "aBc123");

 

Segundo passo

Para consultar o status das mensagens enviadas, basta passarmos por parâmetro um array com os ids dos SMS enviados.

Exemplo:

$msg_list = array();
$msg_list[] = "001";
$msg_list[] = "002";
$msg_list[] = "003";
$msg_list[] = "004";

Obs.: Fica a cargo de sua aplicação salvar os ids dos SMS ao serem enviados com o layout C, (lembrando que nesse layout o id dos SMS é passado por sua aplicação), pois assim será possível fazer a consulta de status de cada SMS.

 

Terceiro passo

Vamos chamar o método queryMultipleStatus, passando por parâmetro a nossa lista de ids de SMS enviados.

Exemplo:

$responses = $humanMultipleSend->queryMultipleStatus($msg_list);

 

Quarto passo

Para obter as respostas das requisições, veja o item “Obtendo respostas das requisições“.

 

Obtendo respostas das requisições

Todas as requisições feitas pela API retornaram um array de objetos Response com seus respectivos códigos e descrições da mensagem de resposta.

Exemplo:

foreach ($responses as $response)  {
    echo $response->getCode();
    echo $response->getMessage();
}

 

Glossário

Item Propriedade Descrição
1 To Número de telefone do SMS no formato DDI + DDD + Telefone (Exemplo: 555199990101).
2 Message Mensagem que será enviada ao telefone. Terá no máximo 160 caracteres (sem o campo From).
3 From Identificação do remetente que será atribuído à mensagem. O campo “Message” + o campo “From” devem ter tamanho máximo de 160 caracteres.
4 Id Sua identificação do SMS para fins de consulta.
5 Schedule Data de agendamento de envio do SMS.
6 Tipos de callback
  • INACTIVE(0) (Padrão): Não será enviada mensagem de callback para a sua aplicação.
  • FINAL(1): Será enviada a mensagem de callback com somente o estado final de cada mensagem enviada.
  • FULL(2): Será enviada a mensagem de callback com os estados intermediários e o estado final de cada mensagem enviada.

Observação: Para os callbacks Final e Full, deverá ser cadastrado no atendimento da Zenvia um host ao qual serão enviadas as requisições.

7 String Conjunto de caracteres.
8 Tipos de layout
  • Tipo A: to;message
  • Tipo B: to;message;from
  • Tipo C: to;message;id
  • Tipo D: to;message;id;from
  • Tipo E: to;message;from;id;schedule
Leia o tutorial também nas versões .Docx e PDF.
icon-word icon-pdf

Remember engage thesis help where your fans are hanging out.