💡 Envio de Notificações Por API: toda a documentação

Antes de começar quero dizer que estou escrevendo esse documento faz muito tempo, e quase que não sai,… Se não fosse o empurrãozinho do grande @Sergio nunca ia sair! Deu um bom trabalho mas espero ajudar muita gente explicando como funciona o envio de notificações dentro do Blip :robot:.

Fala Pessoal! hoje eu vim trazer um projeto um tanto quanto diferente, vim trazer um código que fiz. Ele serce para dizer o que é uma notificação que eu considero “bem sucedida” e, para isso, precisamos entender que esse processo não se baseia em uma única requisição e sim em algumas requisições feitas que se complementam. Mas vem cá, vamos logo por a mão na massa?

Primeiro vamos entender que o primeiro passo não é enviar a notificação, mas sim ajustar o número (hahaha). Para conseguirmos enviar, precisamos que o número esteja no padrão, logo, vamos começar pelo ajuste do número.

Como ajustar o número

O padrão que precisamos é CÓDIGO NACIONAL - CÓDIGO ESTADUAL - NÚMERO COM O 9 (por mais que a sua conta não tenha). Antes de surtar pera aí que já explico. Para isso, vamos usar um script que fiz em python, lembrando que estamos montando o que futuramente será uma API então a função ficou mais ou menos assim ó:

def regex_num (phone):

phone=phone.replace(' ','',)

phone=phone.replace('(','')

phone=phone.replace(')','')

phone=phone.replace('-','')

phone=phone.replace('.','')

tam_phone= len (phone)

if (tam_phone > 2):

ddd=phone[0]+phone[1]

if (ddd == "+5") :

phone = phone

elif (ddd == "55"):

phone = "+"+phone

else:

phone = "+55" + phone

return phone

Podemos ver aqui que ele só espera a entrada da variável “phone”, portanto nesse caso só serve pra números brasileiros e não vai funcionar pra nada na gringa, mas só fazer isso na linguagem que esteja usando que ele trata o número e aumenta chance de seu envio ser bem sucedido em uns 50% (hahaha)

Agora temos que buscar o Identity que identifica o seu número no WhatsApp para podermos mandar a notificação, o que abre nosso próximo passo.

Obtendo o Identity do Usuário.

Para obtermos o Identity, vamos fazer uma requisição dentro do WhatsApp buscando essa informação. Os dados seriam esses aqui:

Método: POST

EndPoint: https://msging.net/commands

Headers:

Authorization: Chave do seu bot

Content-Type: application/json

Body:

{

"id": “randomguid”,

"to": "[email protected]",

"method": "get",

"uri": "lime://wa.gw.msging.net/accounts/{{número de telfone}}"

}

ele vai retornar um JSON assim caso de certo,

{

"type": "application/vnd.lime.account+json",

"resource": {

"alternativeAccount": "Número de [email protected]",

"identity": "Número de [email protected]",

"phoneNumber": "Número de Telefone",

"source": "WhatsApp"

},

"method": "get",

"status": "success",

"id": "a456-42665544000-0123e4567-e89b-12d3",

"from": "[email protected]/#iris-hosted-1",

"to": "[email protected]/!iris-hosted-1-6t1bi02u",

"metadata": {

"#command.uri": "lime://wa.gw.msging.net/accounts/+Número de Telefone",

"uber-trace-id": "62ae55ed065e0187%3Aa50b2a8919c26987%3A62ae55ed065e0187%3A1"

}

}

Dele, vamos extrair o AlternativeAccount e com ele vamos fazer algumas configurações. Dentro do python a função ficou mais ou menos assim:

def verification_phone (phone, URLBLIP, KEYBLIP):

name = "Erro"

id = str(uuid.uuid4())

id = "send-notification-api-" + id

payBlip = json.dumps({

"id": id,

"to": "[email protected]",

"method": "get",

"uri": "lime://wa.gw.msging.net/accounts/"+phone

}).encode('utf-8')

BlipReq = request.Request(URLBLIP[0],data = payBlip, headers={'content-type': 'application/json', 'Authorization': KEYBLIP})

BlipResp = request.urlopen(BlipReq).read().decode()

data = json.loads(BlipResp)

status = data['status']

if ("fullName" in BlipResp):

name = data ['resource']['fullName']

return BlipResp

:exclamation: OBS: caso queria ver exemplos em outras linguagens ou entender melhor essa requisição, está aqui na documentação ddo Blip..
A primeira req dessa sessão também consegue trazer o nome do contato no WhatsApp. Contudo, o que precisamos é o Identity que está dento do AlternativeAccount,

Agora que temos o número e temos o Identity, vamos finalmente enviar, de fato, a mensagem.

Enviando a Notificação

Neste passo, vamos dividir em duas opções: com e sem variáveis. Você pode conectar essa estrutura no seu sistema e querer puxar algumas informações, por isso, vamos ter dois modelos: um para envio simples (sem variáveis ou conteúdos) e um para envios com variáveis (com links e tudo mais). Vamos lá! :eyes:

Envio Simples :speech_balloon:

Para um envio simples, ou seja, sem variáveis, links, mídias e etc, vamos chamar a API Send Notification, que irá enviar o template. Vamos usar o Identity, que obtivemos na requisição anterior, para definir para quem será enviado.

Aqui você encontra a requisição em questão, que ficará mais ou menos assim:

Método: POST

EndPoint: https://http.msging.net/messages

Headers:

Authorization: Chave do seu bot

Content-Type: application/json

Body:

{

"id":"id",

"to":"identity",

"type":"application/json",

"content":{

"type":"template",

"template":{

"namespace":"namespace",

"name":"template_name",

"language":{

"code":"pt_BR",

"policy":"deterministic"

}

}

}

}

:exclamation: OBS: Indentity, é o AlternativeAccount da requisição anterior e “name space” e “template name” são dados vinculados ao seu contato inteligente, lembrando que ambos estarão na aba conteúdos do bot ou router que tem o WhatsApp conectado.

Ai é só escolher o template, no qual “Nome do Modelo” é o “template name” e “namespace” é “namespace”.

:exclamation: OBS: Essa API não nos retornará nada além do status igual a “201”. Caso dê certo, quer dizer que a tentativa foi feita, e que ele enviará ao WhatsApp para que sejam feitas suas próprias validações e tentativa de envio da mensagem.

:eyes: A minha função em python que chama essa API ficou assim:

def send_notification(URLBLIP ,KEYBLIP, namespace, template_name, identity):

id = str(uuid.uuid4())

id = "send-notification-api-" + id

print("Monta Body")

payBlip = json.dumps({

"id":id,

"to":identity,

"type":"application/json",

"content":{

"type":"template",

"template":{

"namespace":namespace,

"name":template_name,

"language":{

"code":"pt_BR",

"policy":"deterministic"

}}}

}).encode('utf-8')

print("Monta Requisição")

BlipReq = request.Request(URLBLIP[1],data = payBlip, headers={'content-type': 'application/json', 'Authorization': KEYBLIP})

print("Faz Requisição")

BlipResp = request.urlopen(BlipReq).read().decode()

return BlipResp

Envio Avançado :speech_balloon::speech_balloon:

Neste tipo de envio, faremos quase a mesma coisa, porém adicionando algumas coisas no content. Seguiremos o mesmo padrão só que alterando o que estará dentro do campo “components”.

Então, para enviar 1 variável ficaria assim:

Método: POST

EndPoint: https://msging.net/commands

Headers:

Authorization: Chave do seu bot

Content-Type: application/json

Body:

{

"id":"id",

"to":"identity",

"type":"application/json",

"content":{

"type":"template",

"template":{

"namespace":"namespace",

"name":"template_name",

"language":{

"code":"pt_BR",

"policy":"deterministic",

"components":[{

"type": "body",

"parameters": [

{

"type": "text",

"text": "parâmetro1"

}

]

}]

}

}

}

}

:exclamation: OBS: Para enviar imagens, vídeos e tudo mais, tem tudo explicadinho aqui como fazer cada umas das ações. Basta replicar junto ao que passei até agora.

Até aqui tudo certo? Hora de começar a entender o porque trouxe vocês até aqui. Agora vamos fazer o que realmente faz diferença, ou seja, as personalizações de acordo com a necessidade daquele envio em específico.

Trocando Usuário de Bot

Legal a notificação enviada, mas e quando o usuário responder? Ele estará no bloco início do bot principal? E se ele já tiverinteragido com o bot? Como lidar com uma resposta esperada?

Primeira coisa, vamos colocar o cliente dentro do bot que desejamos que ele caia. Para isso, vamos usar uma requisição que trocará ele de bot. Infelizmente essa API não se encontra hoje na documentação da Take, mas segue aqui para vocês meus lindos:

Método: POST

EndPoint: https://msging.net/commands

Headers:

Authorization: Chave do seu bot

Content-Type: application/json

Body:

{

"id": id,

"to": "[email protected]",

"method": "set",

"uri":"/contexts/"+identity+"/master-state",

"type": "text/plain",

"resource": id_bot + "@msging.net"

}

Aqui vemos que vamos usar nosso velho amigo “Identity” novamente e vamos precisar da ID do bot, que pode ser consultada na home do seu bot.

Assim, como indicado, acrescentando “@msging.net” no final, ficará “[email protected]”. Feito isso, vamos ter levado o usuário para o bot desejado.

:eyes: Aqui está o método em python que criei para chamar essa API:

def change_bot(URLBLIP, KEYBLIP, identity, id_bot):

uri = "/contexts/"+identity+"/master-state"

id = str(uuid.uuid4())

id = "send-notification-api-" + id

id_bot = id_bot + "@msging.net"

payBlip = json.dumps({

"id": id,

"to": "[email protected]",

"method": "set",

"uri": uri,

"type": "text/plain",

"resource": id_bot

}).encode('utf-8')

BlipReq = request.Request(URLBLIP[0],data = payBlip, headers={'content-type': 'application/json', 'Authorization': KEYBLIP})

BlipResp = request.urlopen(BlipReq).read().decode()

data = json.loads(BlipResp)

status = data['status']

return BlipResp

Pronto! O usuário já está no bot correto, mas e se eu quiser levá-lo para um bloco específico desse bot? Às vezes queremos criar tratativas específicas pros disparos, sem ter que criar um bot para cada vez que fizermos uma campanha. Para isso vamos usar uma outra API de Take Blip.

Colocando o usuário no bloco desejado

Bom, essa API tem documentação e você pode encontrá-la aqui

:eyes: Agora bora fazer a requisição seguindo este exemplo:

Método: POST

EndPoint: https://msging.net/commands

Headers:

Authorization: Chave do seu bot

Content-Type: application/json

Body:

{

"id": id,

"to": "[email protected]",

"method": "set",

"uri": "/contexts/"+identity+"/[email protected]"+flow_id ,

"type": "text/plain",

"resource": state_id

}

:exclamation: OBS: E cá está o nosso “Indentity” novamente. Isso é super importante para vermos como o processo de definir o identity corretamente é essencial, certo?

:eyes: Vimos que teríamos que pegar o id do bloco e do fluxo, o que conseguiremos seguindo as seguintes instruções:

Obtendo flow_id

Primeiramente precisaremos entrar no bot desejado, selecionar “Builder”, seguir até na chave na lateral esquerda e clicar na opção “Identificador do Fluxo”, como na imagem abaixo:

:white_check_mark: Esse será nosso flow_id. :white_check_mark:

Obtendo state_id

Para obter o state_id é necessário escolher o bloco para qual vamos direcionar a resposta da notificação, colocar o cursor do mouse sobre ele e clicar com o botão direito. Em seguida, selecione a opção copiar id, como na imagem abaixo:

:speech_balloon: Agora, vou disponibilizar aqui a função que criei em python que faz essa chamada API:

def change_state(URLBLIP, KEYBLIP, identity, flow_id, state_id):

uri = "/contexts/"+identity+"/[email protected]"+flow_id

id = str(uuid.uuid4())

id = "send-notification-api-" + id

payBlip = json.dumps({

"id": id,

"to": "[email protected]",

"method": "set",

"uri": uri,

"type": "text/plain",

"resource": state_id

}).encode('utf-8')

BlipReq = request.Request(URLBLIP[0],data = payBlip, headers={'content-type': 'application/json', 'Authorization': KEYBLIP})

BlipResp = request.urlopen(BlipReq).read().decode()

data = json.loads(BlipResp)

status = data['status']

return BlipResp

Pronto! Disparamos a mensagem, enviamos o usuário para onde queríamos, ele já está no bot e no bloco certo. :white_check_mark:

Mas se eu estou disparando, de acordo com uma ação vinda do meu sistema CRM, ou até landpage, não seria mais interessante já enviar alguma informações sobre o cliente no extras contatos? Assim consigo apresentar para o atendente e também usar essa info para tomar ações dentro do fluxo, ou até mesmo para fazermos a distribuição no atendimento humano, correto?

:eyes: Para isso, vamos usar uma requisição que vai atualizar o contato do usuário com as informações que queremos.

Atualizando contato

Essa requisição é muito interessante para guardarmos quem está disparando, por exemplo, para que quando o cliente entrar para ser atendido, ser o mesmo atendente que enviou a mensagem. Portanto, vamos usar uma requisição que atualiza o contato na nossa base,

Método: POST

EndPoint: https://msging.net/commands

Headers:

Authorization: Chave do seu bot

Content-Type: application/json

Body:

{

"id": id,

"method": "merge",

"type": "application/vnd.lime.contact+json",

"uri": "/contacts",

"resource": {

"identity":identity,

"name": name,

"extras": {

"SeusExtras":"Extras",

"SeusExtras2":"Extras"

}

}

}

:exclamation: OBS: Lembrando que você pode colocar quantos campos extras desejar, e tem mais informações sobre como fazer essa requisição aqui.

Inclusive, olha nosso amigo Identity comparecendo mais uma vez hahahaha

:eyes: Você pode atualizar outros dados além dos que apresento ali, como email e telefone. Segue abaixo como ficou a função dentro do python:

def cria_att_ctt (URLBLIP, KEYBLIP, identity, name, jsonExtras):

id = str(uuid.uuid4())

id = "send-notification-api-" + id

payBlip = json.dumps({

"id": id,

"method": "merge",

"type": "application/vnd.lime.contact+json",

"uri": "/contacts",

"resource": {

"identity":identity,

"name": name,

"extras": jsonExtras

}

}).encode('utf-8')

BlipReq = request.Request(URLBLIP[0],data = payBlip, headers={'content-type': 'application/json', 'Authorization': KEYBLIP})

BlipResp = request.urlopen(BlipReq).read().decode()

try:

BlipResp = request.urlopen(BlipReq).read().decode()

print('Lead no Blip aceito')

return BlipResp

except HTTPError as e:

print('Notificação no Blip rejeitada - StatusCode: ', e.code, ' Resposta: ', e.read(), ' Payload: ', payBlip)

Imagino vocês exatamente assim olhando esse post. E a resposta é: não, não acabou. Mas está quase!!! :rofl::rofl::rofl:

Para encerrar, pergunto a vocês: COMO EU VOU SABER QUANTAS MENSAGENS ENVIEI?
Boa! Vamos fazer um registro de evento para conseguir metrificar quantas mensagens foram disparadas pela nossa API,

Registrando o disparo

Vi fazerem o registro de disparo de muitas formas, como usar o nome do template, ou a data de envio. Eu sempre recomendo fazer no bloco que recebe um segundo registro marcando que a pessoa respondeu, trazendo uma noção de impacto. Mas vamos ao que interessa, a documentação da requisição que vamos usar pode ser acessada aqui.

:eyes: No meu exemplo ficou mais ou menos assim:

Método: POST

EndPoint: https://msging.net/commands

Headers:

Authorization: Chave do seu bot

Content-Type: application/json

Body:

{

"id": id,

"to": "[email protected]",

"method": "set",

"type": "application/vnd.iris.eventTrack+json",

"uri": "/event-track",

"resource": {

"category": "notifications",

"action": "send"

}

:exclamation: OBS: Lembrando que uso a categoria como “notifications” e a action como “sent” para poder fazer o registro no bot e ter um gráfico com quantas foram enviadas e quantas foram respondidas. Como disse acima nessa parte fiquem à vontade e personalizem do jeito que mais faz sentido para vocês.

:eyes: Aqui está a forma que ficou a minha função em python:

def create_event (URLBLIP, KEYBLIP):

print("Evento Criado")

id = str(uuid.uuid4())

id = "send-notification-api-" + id

print("Monta Body")

payBlip = json.dumps({

"id": id,

"to": "[email protected]",

"method": "set",

"type": "application/vnd.iris.eventTrack+json",

"uri": "/event-track",

"resource": {

"category": "notifications",

"action": "send"

}

}).encode('utf-8')

print("Monta Requisição")

BlipReq = request.Request(URLBLIP[0],data = payBlip, headers={'content-type': 'application/json', 'Authorization': KEYBLIP})

print("Faz Requisição")

BlipResp = request.urlopen(BlipReq).read().decode()

return BlipResp

:tada:AGORA ACABOU:tada: É só pegar tudo isso aí bater no liquidificador até pegar consistência, levar na geladeira por 1 hora e sua API intermediária tá pronta HEHEHEHE

A verdade é que é só chamar isso tudo de preferência na mesma ordem que eu apresentei e sua notificação será um sucesso!

:rocket: Vou deixar aqui o meu Github onde eu fiz uma API em Flask que faz isso tudo aí: github.com/ZumbiDoPython/send_notification/blob/master/

:rocket: E também a de um brother, meu GRANDE @Breno_Andrade , que para quem tem AWS deixou no esquema pra quem quiser subir em lambda: github.com/brenooandrade/lbdaBlipNotification

Caso fiquem com dúvidas, só comentar aqui, que eu venho responder.

Um abraço do seu amigo cabeça de teia,

29 curtidas

The Office Pam GIF

6 curtidas

E finalmente chegou o conteúdo do @Pedro_Lucas :sparkles::raised_hands::joy:

4 curtidas

TOP DEMAIS Pedro Lucas!!!
É impressionante como você domina bem as integrações com o Blip por meio de funções do Python e foi um prazer converter mais essa pra Lambda!

Vamos que vamos pois foguete não tem ré!!!

Abraços!!!

6 curtidas

mano pior que tenho mais uns 8 guardado na metade

5 curtidas

@Pedro_Lucas você tem um total de zero defeitos! Tá incrível essa doc <3

5 curtidas

Não sei nem o que dizer, apenas sentir …

3 curtidas

:fire: @Pedro_Lucas meu amado miranha, feliz demais com essa doc diretamente do forninho! :fire:

Você mandou bem demais e tomei a liberdade de deixar a navegação do tópico mais fluida. Dei uma editadazinha, mas mantendo o conteúdo sensacional que você fez! Valeu demaisss!!!

3 curtidas

amo so banho de loja que você da nos meus posts

2 curtidas

Essa dupla ( @Pedro_Lucas e @Breno_Andrade ) me deixa muito feliz e orgulhoso!
Parabéns demais pelo tutorial, já vou aproveitar uma parte pq tinha alguém precisando de um help em alguma dessas partes <3

4 curtidas

Que isso mestre!!! não é atoa que tu é um blip Hero!!! Parabéns por esse step by step! :rocket: :rocket:

3 curtidas