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:

{
"date": "2019-01-21T19:39:22.605Z", // ISO 8601 for message time,
"chatPlatform": "whatsapp",
"contactId": "<user_phone>", // User phone number, for instance 5511...
"customerId": "<user_id>", // User Id on Botmaker
"fromName": "<nickname_on_whatsapp>",
"_id_": "<unique_message_id>",
"message": "<optional_message_text>", // One of the following will be present
"audio": "<optional_audio_url>",
"video": "<optional_video_url>",
"file": "<optional_file_url>",
"image": "<optional_image_url>",
"fromCustomer": true, // Is the message from the user or from
"WHATSAPP_NUMBER": "<botmaker_connected_whatsapp_line>",
}
  • Também suportamos multimídia (mensagens de voz, áudios, documentos, imagens, etc.), por exemplo:

{
"FROM_NAME": "user_name", // name of user if possible
"IMAGES_URLS": [
"https://botmaker.com/hostedImageByUser.png"
],
...
}

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:

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'
# your_access_token: ey...
# your_phone: +55135433...
# user_phone: +5512324314..
# message_to_send: Hi!
  • A resposta será um http code 200 com um JSON indicando o ID da mensagem gerada:

{
"id": "id_del_mensaje"
}

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:

{
"error": {
"code": 101,
"message": "Insufficient credit"
}
}

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:

{
"error": {
"code": 201,
"message": "User window is over 24 hours"
}
}

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:

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'
# your_token: your access token
# your_phone_number: whatsapp number of yours
# user_phone_number: whatsapp number of user
# rule_name: botmaker rule name

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:

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'
# your_token: your access token
# your_phone_number: whatsapp number of yours
# user_phone_number: whatsapp number of user
# rule_name: botmaker rule name

Alternativamente, é possível usar o serviço comum de mensageria e especificar a URL do arquivo de mídia que você deseja enviar.

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'
# your_access_token: ey...
# your_phone: +55135433...
# user_phone: +5512324314..
# file_caption: a text description next to the file
# audio_to_send: https://....my_audio.mp3
# image_to_send: https://....my_photo.jpeg
# file_to_send: https://....my_file.pdf

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.

{
"CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp
"CREATION_TIME": "a_date", // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
"CUSTOMER_ID": "user_id", // unique id of user
"_id_": "message_id", // unique id of message
"FROM": "phone_number", // user phone number
"STATUS": "el_cambio_status" // message read or delivered
}

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.