A sdk that allows Moorse customers to write some simplified calls to the Moorse resources.
Project description
Moorse Python SDK
O moorse sdk surge como solução ao problema que muitos desenvolvedores enfrentam ao necessitar criar suas próprias requisições http aos serviços web da Moorse, com ele, torna-se possível enviar requests à nossa API de forma simplificada, sem a necessidade de configurar todos os requests do início ao fim.
Todos os métodos e rotas aqui citados podem ser encontrados com maiores detalhes na documentação da Moorse, bem como maiores detalhes sobre nossos produtos.
Sumário
- Início rápido
- Objeto Moorse
- Autorização
- Mensagens
- Integrações
- Webhooks
- Templates
- Relatórios
- Faturamento
1. Início Rápido
Antes de tudo, inicie um projeto em python e instale o sdk da Moorse utilizando o comando:
pip install moorse
Após instalada a dependência, crie um objeto Moorse e faça login para estar apto a enviar mensagens utilizando suas integrações.
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'seu-email@email.com',
'sua-senha-da-moorse-aqui',
CommunicationChannel.WHATSAPP # <--- Tipo do canal de comunicação
)
moorse.auth.login()
moorse.send_text(
'5583916233664', # <--- Número do destinatário
'sua-mensagem',
'id-da-sua-integração-moorse'
)
2. Objeto Moorse
A classe Moorse é o ponto chave de todo o SDK, criando uma instância dela é possível gerenciar integrações, criar templates, configurar webhooks, enviar mensagens e muito mais!
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'seu-email@email.com',
'sua-senha-da-moorse-aqui',
CommunicationChannel.WHATSAPP # <--- Tipo do canal de comunicação
)
Acima é criada uma instância Moorse que configura e-mail e senha de uma conta bem como o canal de comunicação desejado para enviar mensagens, essas informações serão úteis para que posteriormente seja possível gerar um token de acesso e consigamos realizar chamadas à API.
3. Autorização
Para que seja possível acessar todos os recursos da sua conta é necessário obter seu token de acesso. Desse modo, o objeto Moorse provê um atributo público nomeado auth, com ele é possível chamar a rota de login da Moorse que possibilita receber o token em troca do e-mail e senha da conta.
3.1. login
Após seu email e senha serem configurados, é possível fazer login e obter seu token de acesso.
Definição:
def login(self) -> LoginResponse:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
Aqui, a linha moorse.auth.login(), configura o token de acesso da conta no objeto moorse. Posteriormente isso será importante para que sejamos capazes de executar outros métodos que operam sobre informações pessoais da conta do usuário.
3.2 set_token
Método setter padrão, serve para definir o token que se deseja usar diretamente e não precisar fazer chamadas à API da Moorse.
Definição:
def set_token(self, token: str) -> None:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.set_token('seu-token-secreto')
3.3 get_token
Método getter padrão, serve para resgatar o token salvo no SDK.
Definição:
def get_token(self) -> str:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
meu_email: str = moorse.auth.get_token()
3.4 set_email
Método setter padrão, serve para definir o email que se deseja configurar no SDK para realizar o login.
Definição:
def set_email(self, email: str) -> None:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.set_email('seu-email-moorse')
3.5 get_email
Método getter padrão, serve para resgatar o email salvo no SDK.
Definição:
def get_email(self) -> str:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
meu_email: str = moorse.auth.get_email()
3.6. set_password
Método setter padrão, serve para definir a senha que se deseja configurar no SDK para realizar o login.
Definição:
def set_password(self, password: str) -> None:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.set_password('sua-senha-moorse')
3.7. get_password
Método getter padrão, serve para resgatar a senha salva no SDK.
Definição:
def get_password(self) -> str:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
minha_senha: str = moorse.auth.get_password()
4. Mensagens
4.1. send_text
Método que serve para enviar uma mensagem de texto utilizando o canal de comunicação(WHATSAPP, INSTAGRAM OU SMS) selecionado na instanciação do objeto Moorse.
Definição:
def send_text(
self,
to: str,
body: str,
integration_id: str
) -> MessageSentResponse:
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
moorse.send_text(
'551175839219', # <-- destinatário
'mensagem-teste', # <-- corpo da mensagem
'a7eb547b-9bfc-4307-bac0-92bad46da00f' # <-- integração
)
4.2. send_file
Método que serve para enviar um arquivo utilizando o canal de comunicação WHATSAPP.
Esse método não tem implementação para INSTAGRAM nem SMS.
Definição:
def send_file(
self,
to: str,
body: str,
filename: str,
integration_id: str,
caption: str = None
) -> MessageSentResponse
Exemplo:
from moorse import Moorse, CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
moorse.send_file(
'551175839219', # <-- destinatário
'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', # <-- conteudo do arquivo (url ou base64)
'dummy.pdf', # <-- nome do arquivo
'a7eb547b-9bfc-4307-bac0-92bad46da00f' # <-- integração
)
4.3. send_template
Método que serve para enviar um template utilizando o canal de comunicação WHATSAPP.
Esse método não tem implementação para INSTAGRAM nem SMS.
Definição:
def send_template(
self,
template: TemplateMessageRequest,
integration_id: str
) -> MessageSentResponse:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
from moorse import TemplateMessageRequest
from moorse import Component
from moorse import ImageParameter
from moorse import TextParameter
from moorse import DocumentParameter
from moorse import VideoParameter
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
template = TemplateMessageRequest(
'5511999999999',
'nome-do-template',
[
Component(
'header',
[ TextParameter('texto-do-parametro') ]
),
Component(
'body',
[
ImageParameter('https://picsum.photos/200'),
DocumentParameter('https://www.africau.edu/images/default/sample.pdf'),
VideoParameter('http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/Sintel.mp4')
]
),
Component(
'footer',
[ TextParameter('texto-do-parametro') ]
)
]
)
moorse.send_template(
template,
'id-integracao'
)
4.4. send_list_menu
Método que serve para enviar um menu utilizando o canal de comunicação WHATSAPP.
Esse método não tem implementação para INSTAGRAM nem SMS.
Definição:
def send_list_menu(
self,
menu: MenuMessageRequest,
integration_id: str
) -> MessageSentResponse:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
from moorse import MenuMessageRequest
from moorse import Action
from moorse import Section
from moorse import Row
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
menu: MenuMessageRequest = MenuMessageRequest(
'551175839219',
'titulo-do-menu',
Action([
Section('Carnes', [
Row('1', 'Carne de sol'),
Row('2', 'Carne de panela'),
Row('3', 'Carne de churrasco')
]),
Section('Bebidas', [
Row('4', 'Cerveja'),
Row('5', 'Refrigerante'),
Row('6', 'Suco')
])
])
)
moorse.send_list_menu(
menu,
'id-integracao'
)
4.5. send_buttons
Método que serve para enviar botões utilizando o canal de comunicação WHATSAPP.
Esse método não tem implementação para INSTAGRAM nem SMS.
Definição:
def send_buttons(
self,
buttons: ButtonsMessageRequest,
integration_id: str
) -> MessageSentResponse
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
from moorse import ButtonsMessageRequest
from moorse import Button
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
buttons: ButtonsMessageRequest = ButtonsMessageRequest(
'551175839219',
'Teste de botões',
[
Button('1', 'botao 1'),
Button('2', 'botao 2'),
Button('3', 'botao 3')
]
)
moorse.send_buttons(
buttons,
'id-integracao'
)
5. Integrações
Após ter passado da etapa de autorização usando o método login para obtenção do token você está apto a acessar os recursos da sua conta. O que primeiro veremos são as rotas que envolvem integrações Moorse.
5.1. get_one
Método responsável por resgatar as informações de uma integração Moorse dado seu id.
Definição:
def get_one(self, integration_id: str):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.integration.get_one(
'id-integracao'
)
5.2. get_all
Pega a informação de todas as integrações pertencentes à conta, para isso é apenas necessário a configuração do token da conta.
Definição:
def get_all(self):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.integration.get_all()
5.3. delete
Método responsável por deletar um integração dado seu id.
Definição:
def delete(self, integration_id: str):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.integration.delete(
'id-integracao'
)
5.4. get_status
Método responsável por resgatar o status de uma integração dado seu id.
Definição:
def get_status(self, integration_id: str):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.integration.get_status(
'id-integracao'
)
6. Webhooks
Assumindo que o leitor já tenha realizado o login e obtido o seu token de acesso, torna-se possível manipular os webhooks da sua conta para receber requests em uma URL específica quando houverem eventos com as suas integrações. A seguir estão listados os métodos capazes de interagir com os webhooks.
6.1. create
Método capaz de criar um webhook em uma conta Moorse, dadas as informações necessárias à sua criação.
Definição:
def create(self, webhook: WebhookRequest):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
from moorse import WebhookRequest
from moorse import WebhookMethod
from moorse import Pair
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.webhook.create(
WebhookRequest(
'nome-webhook', # <-- nome desejado ao novo webhook
'https://google.com.br', # <-- url à qual a moorse enviará o webhook
WebhookMethod.GET, # <-- método http do request do webhook
True, # <-- o webhook vai estar ativo ao ser criado? s/n
[
'integracao-1', # integrações associadas
'integracao-2' # ao webhook
],
[
Pair('src', 'moorse'), # cabeçalhos personalizados
Pair('channel', 'whatsapp') # ao webhook
],
False, # <-- o webhook notificará mensagens respondidas? s/n
True, # <-- o webhook notificará mensagens recebidas? s/n
False, # <-- o webhook notificará mensagens enviadas? s/n
1, # número de retentativas
10 # timeout (em segundos)
)
)
6.2. update
Método capaz de atualizar um webhook dado seu id, de modo semelhante ao método de cima.
Definição:
def update(self, webhook_id: str, webhook: WebhookRequest):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
from moorse import WebhookRequest
from moorse import WebhookMethod
from moorse import Pair
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.webhook.update(
'webhook-id', # <-- id do webhook que se deseja atualizar
WebhookRequest(
'nome-webhook', # <-- nome desejado ao novo webhook
'https://google.com.br', # <-- url à qual a moorse enviará o webhook
WebhookMethod.GET, # <-- método http do request do webhook
True, # <-- o webhook vai estar ativo ao ser criado? s/n
[
'integracao-1', # integrações associadas
'integracao-2' # ao webhook
],
[
Pair('src', 'moorse'), # cabeçalhos personalizados
Pair('channel', 'whatsapp') # ao webhook
],
False, # <-- o webhook notificará mensagens respondidas? s/n
True, # <-- o webhook notificará mensagens recebidas? s/n
False, # <-- o webhook notificará mensagens enviadas? s/n
1, # número de retentativas
10 # timeout (em segundos)
)
)
6.3. delete
Método capaz de deletar um webhook dado seu id.
Definição:
def delete(self, webhook_id: str):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.webhook.delete('webhook-id')
6.4. get_one
Método capaz de obter a informação de um webhook dado seu id.
Definição:
def get_one(self, webhook_id: str):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.webhook.get_one('webhook-id')
6.5. get_all
Método capaz de obter a informação de todos os webhooks de uma conta, este método não recebe informação como parâmetro, já que apenas necessita do token de acesso do dono da conta com os webhooks, e este é configurado com a utilização do método login.
Definição:
def get_all(self):
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.webhook.get_all()
7. Templates
Nesta seção são apresentados os métodos que permitem a um usuário Moorse manipular seus templates e realizar ações como criação, remoção e obtenção das informações de um template.
7.1. create
Método responsável por criar um template na sua conta.
Definição:
def create(self, webhook: TemplateRequest) -> TemplateDto:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
from moorse import TemplateRequest
from moorse import TemplateType
from moorse import TemplateCategory
from moorse import TemplateLanguage
from moorse import TemplateDocumentComponent
from moorse import TemplateComponentType
from moorse import TemplateTextComponent
from moorse import TemplateButtonComponent
from moorse import ButtonQuickReply
from moorse import ButtonUrl
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
# Acessar https://moorse.readme.io/reference/criar-um-novo-template
# Para mais informações sobre criação de templates
response = moorse.template.create(
TemplateRequest(
'nome-do-template',
'descricao-do-template',
TemplateType.STANDARD,
'id-integracao',
TemplateCategory.AUTO_REPLY,
TemplateLanguage.PORTUGUESE_BR,
[
TemplateDocumentComponent(TemplateComponentType.HEADER),
TemplateTextComponent(TemplateComponentType.BODY, "Texto do header"),
TemplateButtonComponent([
ButtonQuickReply("Texto do botão 1"),
ButtonQuickReply("Texto do botão 2"),
ButtonUrl("Texto do botão 3", "https://moorse.io")
])
]
)
)
7.2. delete
Método responsável por deletar um template da sua conta dado o id do template.
Definição:
def delete(self, template_id: str) -> TemplateDto:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
moorse.template.delete('template-id')
7.3. get_one
Método responsável por obter informação de um template específico de uma conta Moorse dado o id do template buscado.
Definição:
def get_one(self, template_id: str) -> TemplateDto:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.template.get_one('template-id')
7.4. get_all
Método responsável por obter informação de todos os templates de uma conta Moorse.
Definição:
def get_all(self) -> TemplateList:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.template.get_all()
8. Relatórios
Com os métodos aqui citados é possível receber informações sobre quantidade, canais e dias que as mensagens da conta foram enviadas. Para que seja possível acessar estes métodos é necessário apenas estar logado na sua conta Moorse e ter obtido o token de acesso com .login().
8.1. get_messages
Método que serve para obter informação da quantidade de mensagens enviadas e recebidas e do número de contatos com os quais se manteve contato com alguma integração em um dado período de tempo.
Definição:
def get_messages(self, begin: str, end: str) -> MessagesReportDto:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
moorse.report.get_messages(
'2019-01-31', # <-- data de início do relatório
'2023-01-31' # <-- data de fim do relatório
)
8.2. get_messages_by_channel
Método que serve para obter informação da quantidade de mensagens por canal (WHATSAPP, INSTAGRAM ou SMS) com alguma integração em um dado período de tempo.
Definição:
def get_messages_by_channel(self, begin: str, end: str) -> MessagesByChannelReportDto:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
moorse.report.get_messages_by_channel(
'2019-01-31', # <-- data de início do relatório
'2023-01-31' # <-- data de fim do relatório
)
8.3. get_messages_by_timeline
Método que serve para obter informação da quantidade de mensagens mês a mês com alguma integração em um dado período de tempo.
Definição:
def get_messages_by_timeline(self, begin: str, end: str) -> MessagesByTimelineReportDto:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
moorse.report.get_messages_by_timeline(
'2019-01-31', # <-- data de início do relatório
'2023-01-31' # <-- data de fim do relatório
)
9. Faturamento
Serviço que conta apenas com um método que serve para pegar todos os créditos de uma integração. É necessário que o usuário esteja logado para acessá-lo.
9.1. get_credits
Método que serve para resgatar o número de créditos de uma dada integração.
Definição:
def get_credits(self, integration_id: str) -> BillingDto:
Exemplo:
from moorse import Moorse
from moorse import CommunicationChannel
moorse = Moorse(
'email', 'senha',
CommunicationChannel.WHATSAPP
)
moorse.auth.login()
response = moorse.billing.get_credits("id-integracao")
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
