Tutorial de Integração PYTHON

2

Sumário

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

3

Tutorial de Integração - Python 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.

4

Configurando Envio

1º Passo Faç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º 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 *

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

Exemplo:

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

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

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

5

Enviando Múltiplos SMS 1º Passo Crie uma instância de objeto da classe MultipleMessageService.

Exemplo:

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

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

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

4º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

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

Exemplo:

6

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

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

7

Enviando Múltiplos SMS a partir de um arquivo CSV

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

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

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

4º 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);

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

8

Enviando SMS Individuais 1º Passo Crie uma instância de objeto da classe SimpleMessageService.

Exemplo:

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

2º Passo Vamos 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º 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.

Exemplo:

to= “551199554455”

4º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.

Exemplo:

from = “555181183663”

5º 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.

Exemplo:

id = “002”

9

6º Passo 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º 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

8º Passo Agora basta chamar o método sendSimpleMsg.

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

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

10

Cancelamento de envio de SMS

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

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

Exemplo:

responses = send.cancelSMS(“002”)

11

Consulta de SMS recebidos 1º 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')

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

Exemplo:

responses = send.listReceivedSMS()

12

Consulta de status de SMS

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

Exemplo:

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

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

3º 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”)

13

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()

14

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