Integração Python – 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 Python enviarem SMS por meio da biblioteca de integração que disponibilizamos para facilitar os envios.

 

Pré-requisitos
Para executar a biblioteca de integração Python, basta ter instalada a versão 2.0 ou superior do Python. Visite http://www.python.org/.

 

Entendendo a biblioteca Python
A biblioteca Python é 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 Python, descompacte o conteúdo do arquivo dentro da pasta onde se encontrão os códigos-fontes de sua aplicação (p. ex., dentro da pasta src).

 

Segundo passo

Para manipulação de mensagens (envios e consultas), importe em seu código Python a biblioteca HumanClientMain do package HUMANSMS.

Exemplo:

from humansms.HumanClientMain import *

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 MultipleMessageService para envio múltiplo de SMS; com a instância da classe SimpleMessageService para envio de mensagens simples; e com a instância da classe QueryService para consultas de status de SMS, sempre passando por parâmetros de seus construtores a sua conta e o código de acesso. Tais dados são cedidos pela Zenvia juntamente com a negociação do contrato firmado com a empresa.

Exemplos:

send = SimpleMessageService('human.fake.hc', 'ABC132')	
send = MultipleMessageService('human.fake.hc', 'ABC132')
send = QueryService('human.fake.hc', 'ABC132')

Enviando múltiplos SMS

 

Primeiro passo

Crie uma instância de objeto da classe MultipleMessageService.

Exemplo:

send = MultipleMessageService('human.fake.hc', 'ABC132')

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 segundo parâmetro, podendo ser uma constante da classe MultipleMessage. Esse parâmetro é opcional, pois por padrão será estabelecido o tipo C.

Exemplo:

tipo = MultipleMessage.TYPE_C

Terceiro passo

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

Exemplo:

msg_list  = "550099999999;teste0;004n"
msg_list  = "550099999998;teste1;005n"
msg_list  = "550099999997;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 Message.

Exemplo:

callBack = Message. CALLBACK_INACTIVE
ou
callBack = Message. CALLBACK_FINAL_STATUS
ou
callBack = Message. CALLBACK_INTERMEDIARY_STATUS

Quinto passo

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

Exemplo:

responses = send.sendMultipleListMsg(msg_list, tipo, 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

Crie uma instância de objeto da classe MultipleMessageService.

 

Segundo passo

O envio de múltiplos SMS 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:

550092167288;teste0;004
550095650122;teste1;005
550097745821;teste2;005

Exemplo:

path = "C:arquivo.csv";
tipo = MultipleMessage.TYPE_C

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 Message.

Exemplo:

callBack = Message. CALLBACK_INACTIVE
ou
callBack = Message. CALLBACK_FINAL_STATUS
ou
callBack = Message. CALLBACK_INTERMEDIARY_STATUS

Quarto passo

Basta chamar o método sendMultipleFileCSV da classe MultipleMessageService e passar os parâmetros que acabamos de definir.

Exemplo:

responses = send.sendMultipleFileCSV(path, tipo, callBack);

Quinto 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

Crie uma instância de objeto da classe SimpleMessageService.

send = SimpleMessageService('human.fake.hc', 'ABC132')

Segundo passo

Vamos informar qual SMS será enviado. O número de caracteres não deve ultrapassar 160 por mensagem.

msg= "Olá mundo da Mensagem de Texto!!"

Terceiro passo

Definiremos o número de celular do destinatário, sempre iniciando com o DDI 55, por se tratar de uma mensagem nacional, e seguido do DDD da localidade de destino.

to= "551199554455"

Quarto passo

Podemos também informar o número do remetente do SMS, seguindo as mesmas regras de numeração do destinatário. Esse parâmetro é opcional.

from = "555181183663"

Quinto passo

Informaremos o id do SMS a ser enviado. Esse id deve ser gerado e informado por sua aplicação. Essa informação é opcional, mas de muita importância caso você deseje cancelar ou consultar status dos SMS.

id = "002"

Sexto passo

Informaremos o id do SMS a ser enviado. Esse id deve ser gerado e informado por sua aplicação. Essa informação é opcional, mas de muita importância caso você deseje cancelar ou consultar status dos SMS.

schedule= "dd/mm/aaaa hh:mm:ss"

Sétimo 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 Message.

callBack = Message. CALLBACK_INACTIVE
ou
callBack = Message. CALLBACK_FINAL_STATUS
ou
callBack = Message. CALLBACK_INTERMEDIARY_STATUS

Oitavo passo

Agora basta chamar o método sendSimpleMsg.

responses = send.sendSimpleMsg(msg, to, from, id, schedule, callBack );

Nono passo

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

 

Cancelamento de envio de SMS

 

Primeiro passo

Para cancelarmos um SMS agendado que ainda não foi enviado, precisamos ter em mãos o id do SMS (isso ressalta a importância de termos um controle de ids de SMS enviados em nossa aplicação).

Crie uma instância de objeto da classe SimpleMessageService.

Exemplo:

send = SimpleMessageService('human.fake.hc', 'ABC132')

Segundo passo

Agora basta invocarmos o método cancelSMS, passando por parâmetro o id do SMS que queremos cancelar.

Exemplo:

responses = send.cancelSMS("002")

Consulta de SMS recebidos

 

Primeiro passo

Para consultar textos SMS enviados para a sua aplicação (por exemplo, quando um SMS é enviado por sua aplicação e você espera que seu cliente a responda), sua aplicação deve estar habilitada a receber SMS (veja mais informações na área dos desenvolvedores da Zenvia Desenvolvedores >> Consulta de SMS Recebido)
Crie uma instância de objeto da classe QueryService.

Exemplo:

send = QueryService('human.fake.hc', 'ABC132')

Segundo passo

Invoque o método listReceivedSMS, para obter a lista de SMS recebidos.

Exemplo:

responses = send.listReceivedSMS()	

Consulta de status de SMS

 

Primeiro passo

Para consultar o status dos SMS enviados, crie uma instância de objeto da classe QueryService.

Exemplo:

send = QueryService('human.fake.hc', 'ABC132')

Segundo passo

Agora basta passarmos por parâmetro uma lista com os ids dos SMS enviados.

Exemplo:

msg_list = {}
msg_list = {"001","002","003","004","005","006","007","008","009","010"}

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 = send.queryMultipleStatus(msg_list)

Podemos também fazer uma consulta individual do status de um SMS. Para isso, chamaremos o método querySimpleStatus(), passando o id do SMS.

Exemplo:

responses = send.querySimpleStatus("001")

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:

for msgResponse in response:
       print msgResponse.getCode()
       print msgResponse.getDescription()

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

It doesn’t address emotions research paper writing service directly, however.