Tutorial de IntegraçãoPYTHON

Sumário

Tutorial de Integração - Python..................................................................................3Configurando Envio.....................................................................................................4Enviando Múltiplos SMS..............................................................................................5Enviando Múltiplos SMS a partir de um arquivo CSV..................................................7Enviando SMS Individuais...........................................................................................8Cancelamento de envio de SMS...............................................................................10Consulta de SMS recebidos.......................................................................................11Consulta de status de SMS.......................................................................................12Obtendo respostas das requisições..........................................................................13Glossário...................................................................................................................14

2

Tutorial de Integração - Python

ObjetivoO 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é-requisitosPara 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 PythonA 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.

3

Configurando Envio

1º PassoFaça o download da biblioteca de integração por meio do link http://desenvolvedores.zenvia.com/bibliotecas/Python.zip 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).

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

Exemplo:from humansms.HumanClientMain import *

3º PassoPara 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.Exemplo:

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

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

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

4

Enviando Múltiplos SMS

1º PassoCrie uma instância de objeto da classe MultipleMessageService.Exemplo:send = MultipleMessageService('human.fake.hc', 'ABC132')

2ºPassoEscolheremos 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

3ºPassoEm 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;004\n"msg_list = "550099999998;teste1;005\n"msg_list = "550099999997;teste2;006"

4ºPassoConfiguraremos 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_INACTIVEoucallBack = Message. CALLBACK_FINAL_STATUSoucallBack = Message. CALLBACK_INTERMEDIARY_STATUS

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

5

Exemplo:responses = send.sendMultipleListMsg(msg_list, tipo, callBack)

6ºPasso:Para obter as respostas das requisições, veja o item “ Obtendo respostas das requisições ”.

6

Enviando Múltiplos SMS a partir de um arquivo CSV

1º PassoCrie uma instância de objeto da classe MultipleMessageService.

2ºPassoO 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;004550095650122;teste1;005550097745821;teste2;005

Exemplo:path = “C:\arquivo.csv”;tipo = MultipleMessage.TYPE_C

3º PassoConfiguraremos 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_INACTIVEoucallBack = Message. CALLBACK_FINAL_STATUSoucallBack = Message. CALLBACK_INTERMEDIARY_STATUS

4º PassoBasta chamar o método sendMultipleFileCSV da classe MultipleMessageService e passar os parâmetros que acabamos de definir.Exemplo:responses = send.sendMultipleFileCSV(path, tipo, callBack);

5ºPassoPara obter as respostas das requisições, veja o item “ Obtendo respostas das requisições ”.

7

Enviando SMS Individuais

1º PassoCrie uma instância de objeto da classe SimpleMessageService.Exemplo:send = SimpleMessageService('human.fake.hc', 'ABC132')

2º PassoVamos informar qual SMS será enviado. O número de caracteres não deve ultrapassar 150 por mensagem.Exemplo:

msg= “Olá mundo da Mensagem de Texto!!”

3º PassoDefiniremos 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.Exemplo:

to= “551199554455”

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

from = “555181183663”

5º PassoInformaremos 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.Exemplo:

id = “002”

6º Passo

8

Para agendarmos o envio de um SMS passaremos por parâmetro a data em que queremos que o SMS seja enviado. Esse parâmetro é opcional; se não for informado, o SMS será enviado imediatamente.Exemplo:

schedule= “dd/mm/aaaa hh:mm:ss”

7º PassoConfiguraremos 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_INACTIVEoucallBack = Message. CALLBACK_FINAL_STATUSoucallBack = Message. CALLBACK_INTERMEDIARY_STATUS

8º PassoAgora basta chamar o método sendSimpleMsg.

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

9º PassoPara obter as respostas das requisições, veja o item “ Obtendo respostas das requisições ”.

9

Cancelamento de envio de SMS

1º PassoPara 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')

2ºPassoAgora basta invocarmos o método cancelSMS, passando por parâmetro o id do SMS que queremos cancelar.Exemplo:responses = send.cancelSMS(“002”)

10

Consulta de SMS recebidos

1º PassoPara 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')

2º PassoInvoque o método listReceivedSMS, para obter a lista de SMS recebidos.Exemplo:

responses = send.listReceivedSMS()

Consulta de status de SMS

11

1º PassoPara consultar o status dos SMS enviados, crie uma instância de objeto da classe QueryService.Exemplo:send = QueryService('human.fake.hc', 'ABC132')

2º PassoAgora 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.

3º PassoVamos 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

12

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

Ite Proprieda Descrição

13

m de

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 150 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 150 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

14