Botmaker API para WhatsApp
Aqui vamos aprender como acessar a Botmaker API para WhatsApp.

Recebendo mensagens dos usuários

As mensages enviadas pelos usuários podem ser vistas intanstaneamente no Console de Operador da Botmaker, onde é possível responder manualmente ou mediante o uso de bots. Sem dificuldade, também é possível notificar um sistema dessas mensagens: se quiser receber cada mensagem, pode configurar um webhook em seus sistemas da seguinte maneira:
    Uma vez ativado, você começará a receber mensagens segundo as políticas do Google PubSub; mensagens assinadas, preservação de mensagens por 7 dias, etc. Veja mais detalhes aqui.
    O exemplo a seguir mostra uma mensagem típica de um usuário:
1
{
2
"date": "2019-01-21T19:39:22.605Z", // ISO 8601 for message time,
3
"chatPlatform": "whatsapp",
4
"contactId": "<user_phone>", // User phone number, for instance 5511...
5
"customerId": "<user_id>", // User Id on Botmaker
6
"fromName": "<nickname_on_whatsapp>",
7
"_id_": "<unique_message_id>",
8
"message": "<optional_message_text>", // One of the following will be present
9
"audio": "<optional_audio_url>",
10
"video": "<optional_video_url>",
11
"file": "<optional_file_url>",
12
"image": "<optional_image_url>",
13
"fromCustomer": true, // Is the message from the user or from
14
"WHATSAPP_NUMBER": "<botmaker_connected_whatsapp_line>",
15
}
Copied!
    Também suportamos multimídia (mensagens de voz, áudios, documentos, imagens, etc.), por exemplo:
1
{
2
"FROM_NAME": "user_name", // name of user if possible
3
"IMAGES_URLS": [
4
"https://botmaker.com/hostedImageByUser.png"
5
],
6
...
7
}
Copied!

Enviando mensagens aos usuários

É possível enviar mensagens aos usuários utilizando o Console de Operador, gerando notificações massivamente e programando envios por diferentes estímulos. Também se pode utilizar a API da Botmaker para disparar mensagens programas a partir de um sistema.
Para isso, deve-se:
    Obter um token de acesso à API:
      Selecione Botmaker API - Credenciais;
      Gere um token ou utilize o que já está gerado. Em particular, é importante que salve o Access Token.
GerarToken
accesstoken
    Com o acesso ao token, será possível efetuar o chamado HTTP Post ao API rest com um JSON:
1
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_access_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone", "platformContactId": "user_phone","messageText": "message_to_send"}' 'https://go.botmaker.com/api/v1.0/message/v3'
2
3
# your_access_token: ey...
4
# your_phone: +55135433...
5
# user_phone: +5512324314..
6
# message_to_send: Hi!
Copied!
    A resposta será um http code 200 com um JSON indicando o ID da mensagem gerada:
1
{
2
"id": "id_del_mensaje"
3
}
Copied!
Cada vez que uma mensagem é enviada ao usuário, será efetuado um check de controle de saldo da sua conta Botmaker. Se a conta estiver prestes a ficar sem saldo, o serviço devolverá um http code 403 - Forbidden, indicando que não há saldo para enviar mensagens no JSON de resposta:
1
{
2
"error": {
3
"code": 101,
4
"message": "Insufficient credit"
5
}
6
}
Copied!
Cada vez que uma mensagem é enviada ao usuário, será efetuado um check para determinar se a mensagem será rejeitada pelo WhatsApp, já que o usuário não conversou com você na plataforma nas últimas 24 horas. Veja a seção Templates de Mensagens para mais informações:
1
{
2
"error": {
3
"code": 201,
4
"message": "User window is over 24 hours"
5
}
6
}
Copied!

Templates de mensagens

O WhatsApp permite enviar mensagens aos usuários em até 24 horas depois da última mensagem enviada por ele. Fora desse prazo, as mensagens deverão ser enviadas utilizando o endpoint intent e realizando os seguintes passos:
    Acessar a área de Templates e submeter seus templates.
    Uma vez que os mesmos estejam aprovados, uma intenção com seu nome será criada.
whatsapptemplate
    Basta efetuar a chamada ao endpoint:
1
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone_number", "platformContactId": "user_phone_number", "ruleNameOrId": "rule_name", "params": {"my_template_var":"var_value"}}' 'https://go.botmaker.com/api/v1.0/intent/v2'
2
3
# your_token: your access token
4
# your_phone_number: whatsapp number of yours
5
# user_phone_number: whatsapp number of user
6
# rule_name: botmaker rule name
Copied!

Mensagens multimídia

A Botmaker permite enviar todas os tipos de mensagens multimídia suportados pelo WhatsApp e outros canais. Para isso, deve-se criar uma mensagem em Regras seguindo a página de Como criar respostas em uma intenção.
Também se pode chamar o serviço de ativação de regras desde o seu sistema, por exemplo:
1
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone_number", "platformContactId": "user_phone_number", "ruleNameOrId": "rule_name", "params": {"param_key_1":"param_value_1"}}' 'https://go.botmaker.com/api/v1.0/intent/v2'
2
3
# your_token: your access token
4
# your_phone_number: whatsapp number of yours
5
# user_phone_number: whatsapp number of user
6
# rule_name: botmaker rule name
Copied!
Alternativamente, é possível usar o serviço comum de mensageria e especificar a URL do arquivo de mídia que você deseja enviar.
1
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_access_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone", "platformContactId": "user_phone", "messageText": "file_caption", "audioURL": "audio_to_send", "imageURL": "image_to_send", "fileURL", "file_to_send"}' 'https://go.botmaker.com/api/v1.0/message/v3'
2
3
# your_access_token: ey...
4
# your_phone: +55135433...
5
# user_phone: +5512324314..
6
# file_caption: a text description next to the file
7
# audio_to_send: https://....my_audio.mp3
8
# image_to_send: https://....my_photo.jpeg
9
# file_to_send: https://....my_file.pdf
Copied!
Escolha um ou vários formatos de mídia para enviar em uma mensagem. Aqui está uma lista com todos os formatos de arquivos suportados. No momento, o WhatsApp não tem suporte a vídeos e GIFs.

Alterações no estado das mensagens enviadas

Posteriormente ao envio de uma mensagem ao usuário, seu endpoint receberá notificações de entrega ou leitura dessa mensagem.
    1.
    Delivered indica que a mensagem foi enviada - check duplo do WApp.
    2.
    Read indica que a mensagem foi lida pelo usuário de destino - check duplo azul do WApp.
1
{
2
"CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp
3
"CREATION_TIME": "a_date", // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
4
"CUSTOMER_ID": "user_id", // unique id of user
5
"_id_": "message_id", // unique id of message
6
"FROM": "phone_number", // user phone number
7
"STATUS": "el_cambio_status" // message read or delivered
8
}
Copied!
Se a opção Confirmação de Leitura for desativada pelo usuário nas configurações de privacidade, essas mensagens não serão recebidas.

Aplicar formatos à mensagens através da API

É possível aplicar formatos simples à textos de mensagens que serão enviadas aos usuários, por exemplo “Olá, João”. Para mais informações, cheque a Documentação de Formatos do WhatsApp.
Last modified 1yr ago