Como enviar e receber mensagens via API?
Com esse artigo você será capaz de enviar e receber mensagens por meio de uma API e escutar as mensagens vindas de um Webhook padrão da plataforma.
Com esse artigo você será capaz de enviar e receber mensagens por meio de uma API e escutar as mensagens vindas de um Webhook padrão da plataforma.
Leitura estimada: 08 minutos
A plataforma da Botmaker oferece uma extensa documentação de APIs que podem ser utilizadas para diversos fins. Este artigo se concentra no envio e recebimento exclusivamente via API. Para isso, você precisará utilizar a API de Envio de Mensagens e ativar um Webhook para que o servidor paralelo receba as mensagens do cliente final.
Abaixo está um fluxograma do modelo de comunicação:
Como obter credenciais para acessar a API?
Para acessar a API, você precisa obter um token de acesso. Para isso, siga estas etapas:
- Uma vez logado(a) na plataforma Botmaker, acesse Botmaker API dentro do menu
- Configurações, selecione a opção Integrações e por último selecione API Botmaker.
- Gere um token através do botão Gerar credenciais ou use um já gerado.
- Esse token será usado no cabeçalho das suas chamadas à nossa API.
Como enviar uma mensagem?
As mensagens são enviadas através do endpoint message, especificamente Send messages. Você pode testar a API através da aba Documentação. Para isso, selecione o endpoint em Chat Actions e depois a API Send messages.
Para teste, siga os seguintes passos:
- Insira o seu token no campo access-token no tópico Auth.
- Em Body, substitua o channelID pelo ID do canal que você deseja. O ID pode ser encontrado no endpoint List Channels em Channels.
- Substitua o ContactID pelo ID do contato, no caso da conversa ser realizada pelo Whatsapp esse ID será o número do cliente, em Webchat é um ID que é gerado.
- Defina qual mensagem você deseja enviar com os exemplos que estão na documentação como: Mensagem de texto, menu com botões, media, localização e contato.
- No campo webhookPayload você pode definir variáveis extras que serão enviados via Webhook Notification para o servidor.
Aplicar formatação às mensagens
É possível aplicar formatos simples à textos de mensagens que serão enviadas aos usuários.
- Itálico
Para escrever sua mensagem em itálico, insira o sinal de sublinhado antes e depois do texto.
- Negrito
Para escrever sua mensagem em negrito, insira um asterisco antes e depois do texto.
- Tachado
Para tachar sua mensagem, insira um til antes e depois do texto.
- Monoespaçado
Para escrever sua mensagem monoespaçada, insira três sinais graves antes e depois do texto.
Respostas da API
Existem 3 tipos de respostas padrões da API, sendo elas: 200( Enviado com sucesso ), 400 ( Erro em algum parâmetro do Body ou ID do Chat ), 429 ( Limite de requisições por segundo excedido ).
Os exemplos de JSON gerados você pode acompanhar diretamente na aba de Documentação da API.
Como receber mensagens?
Assim que um usuário enviar uma mensagem ao seu WhatsApp, encaminhamos essa mensagem ao seu webhook. Dessa forma, você receberá, no seu sistema, todas as mensagens de todos os seus usuários.
Para obter informações detalhadas sobre como gerenciar os seus webhooks, consulte o artigo: Como integrar webhooks?
Formato de notificações de webhook
Existem 3 tipos de webhooks disponíveis na plataforma:
- Mensagem e Status
- Gerenciamento do Whatsapp
- Resultados da API assíncrona
Notificações de mensagem
Para o recebimento de mensagens iremos utilizar o tipo Mensagem e Status. As informações que você irá receber dependem de quais dados são necessários para sua operação.
Na tela de configuração você deve poder configurar as seguintes informações:
- Insira o url para o qual o webhook enviará as mensagens: Essa URL é o EndPoint Público para comunicação com o seu Webhook. Será onde enviaremos os eventos.
- Token de segurança: você pode adicionar um, usar o sugerido ou deixar o espaço em branco: Caso necessário podemos adicionar um token para ser enviado como autenticação para o seu Endpoint. Será adicionado ao cabeçalho com a chave “auth-bm-token”
- Adicione ou remova os canais conectados a este webhook (pelo menos 1 é necessário): Aqui configuramos o canal de entrada do usuário que iremos monitorar e enviar os eventos para seu servidor. É exigido pelo menos um canal e pode ser configurado vários canais(Ex.: Whatsapp, Webchat, Instagram)
- Inclua os tipos de mensagens que você deseja enviar para o seu webhook: Aqui iremos informar qual origem do evento/mensagem será enviado para o seu Webhook. Sendo eles:
- Mensagens do Bot: São todas as mensagens geradas pelo chatbot.
- Mensagens dos usuários: Todas as mensagens recebidas na plataforma que o usuário envio no canal(Whatsapp, webchat, instagram).
- Mensagens dos agentes: As mensagens geradas por um atendente humano.
- Status das Mensagens: Registra os eventos das mensagens enviadas(Entregue, lido, recebido, erro).
- Apenas o status de HSM: Registra os eventos de status das mensagens relacionadas ao template(Entregue, lido, recebido, erro).
- Mensagens de Eventos: Envia os eventos gerais da plataforma como, usuário desbloqueado, usuário bloqueado, mudança de bot, etc.
- Deseja incluir variáveis de alteração na mensagem?: Ao habilitar essa opção, será enviado as variáveis que foi declarado algum valor durante o fluxo do bot. Apenas iremos enviar a variável no momento da declaração.
Exemplos de Notificações de mensagem
- Exemplo de mensagem de texto enviado pelo usuário:
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"contactId": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"type": "message",
"whatsappNumber": "551144444444",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"v": "1.1",
"customerId": "2S1WE8VVOZD5RCR3WI33",
"messages": [
{
"date": "2024-02-14T13:04:00.610Z",
"fromName": "Usuário Teste",
"_id_": "NDZGKUNNRC5PSHLRFZYJ",
"from": "user",
"clientPayload": "",
"message": "Oi",
"operatorId": null,
"fromCustomer": true,
"queue": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Exemplo de mensagem de texto enviada pelo Bot:
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"variables": {
"clienteIniciouAConversa": "true"
},
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"contactId": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"type": "message",
"whatsappNumber": "551144444444",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"v": "1.1",
"customerId": "2S1WE8VVOZD5RCR3WI33",
"messages": [
{
"date": "2024-02-14T13:04:00.667Z",
"intentName": "Mensagem inicial",
"fromName": "Bot",
"_id_": "MYQAVYSR5H6HGA1KEFGQ",
"from": "bot",
"clientPayload": "",
"message": "Bem-vindo(a), Usuário a Botmaker! 👋",
"operatorId": null,
"queue": "_default_"
}
],
"_id_": "NJZX2WDAFF0IKHLF6JQ6",
"from": "bot",
"clientPayload": "",
"message": "Em que posso ajudar?",
"operatorId": null,
"queue": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Exemplo de lista de botões enviada pelo Bot:
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"variables": {
"clienteIniciouAConversa": "true"
},
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"contactId": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"type": "message",
"whatsappNumber": "551144444444",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"v": "1.1",
"customerId": "2S1WE8VVOZD5RCR3WI33",
"messages": [
{
"date": "2024-02-14T13:04:00.671Z",
"intentName": "Mensagem inicial",
"fromName": "Bot",
"options": [
{
"type": "postback",
"value": "Tipos de Respostas📲"
},
{
"type": "postback",
"value": "Ecommerce no Chat🛍"
},
{
"type": "postback",
"value": "Geolocalização 🌍📍"
},
{
"type": "postback",
"value": "2FA - Email 🏷️"
},
{
"type": "postback",
"value": "Integrações🔄"
},
{
"type": "postback",
"value": "Falar com uma pessoa"
},
{
"type": "postback",
"value": "Sugestões 📚"
}
],
"_id_": "NJZX2WDAFF0IKHLF6JQ6",
"from": "bot",
"clientPayload": "",
"message": "Em que posso ajudar?",
"operatorId": null,
"queue": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Exemplo de mensagem de áudio:
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"contactId": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"type": "message",
"whatsappNumber": "551144444444",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"v": "1.1",
"customerId": "2S1WE8VVOZD5RCR3WI33",
"messages": [
{
"date": "2024-02-14T13:08:59.687Z",
"hasAttachment": true,
"fromName": "Usuário Teste",
"_id_": "4OKNABQ06A68IJ7PHT5K",
"from": "user",
"audio": "https://storage.googleapis.com/storage.botmaker.com/public/res/botmakerparaeventos/users/1c2e/be71/8c29/6005/59a0/d437/0d7d/1ef2/1c2ebe718c29600559a0d4370d7d1ef2.ogg",
"clientPayload": "",
"operatorId": null,
"fromCustomer": true,
"queue": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Exemplo de envio de documento:
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"contactId": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"type": "message",
"whatsappNumber": "551144444444",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"v": "1.1",
"customerId": "2S1WE8VVOZD5RCR3WI33",
"messages": [
{
"date": "2024-02-14T13:10:06.592Z",
"hasAttachment": true,
"file": "https://storage.googleapis.com/storage.botmaker.com/public/res/botmakerparaeventos/users/23da/b4b0/46c6/94bf/a7e0/ad49/9c25/0a90/23dab4b046c694bfa7e0ad499c250a90.pdf",
"fromName": "Usuário Teste",
"_id_": "0EQR1JLFQLCS3TLEFP2A",
"caption": "EBOOK_FESTA-JUNINA_1306 (1).pdf",
"from": "user",
"clientPayload": "",
"operatorId": null,
"fromCustomer": true,
"queue": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Exemplo de envio de imagem:
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2022-11-08T18:18:03.476Z",
"contactId": "559999999999",
"sessionId": "2S1WE8VVOZD5RCR3WI33_2024-02-14T13:02:55.244Z",
"type": "message",
"whatsappNumber": "551144444444",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:02:55.244Z",
"v": "1.1",
"customerId": "2S1WE8VVOZD5RCR3WI33",
"messages": [
{
"date": "2024-02-14T13:11:53.996Z",
"image": "https://storage.googleapis.com/storage.botmaker.com/public/res/botmakerparaeventos/users/c330/28cd/10c1/ce5f/4574/0209/07fc/8006/c33028cd10c1ce5f4574020907fc8006.jpeg",
"hasAttachment": true,
"fromName": "Usuário Teste",
"_id_": "DT5ZUX4QAVL86400KG5N",
"from": "user",
"clientPayload": "",
"operatorId": null,
"fromCustomer": true,
"queue": "_default_"
}
],
"chatChannelId": "botmaker-whatsapp-551144444444"
}
- Exemplo de envio de flow( este modelo de envio pois o flows ainda está em Beta pela meta):
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2024-01-26T01:13:58.455Z",
"contactId": "558393846412",
"sessionId": "31JAOCZKUCK6HPH0NVKT_2024-02-14T13:18:45.730Z",
"type": "message",
"whatsappNumber": "5511123123123",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:18:45.730Z",
"v": "1.1",
"customerId": "31JAOCZKUCK6HPH0NVKT",
"messages": [
{
"date": "2024-02-14T13:22:45.401Z",
"image": "https://storage.googleapis.com/storage.botmaker.com/public/res/testegrupomacro/20240201-QISCSaluLphxOommBBkjNPt0bgt1-YJ00Y-.jpeg",
"hasAttachment": true,
"intentName": "Flows 2",
"fromName": "Bot",
"_id_": "JMYH3A443IGDV3VKH6LG",
"from": "bot",
"clientPayload": "",
"message": "Escolha agora as datas do seu agendamento 📅🌎",
"operatorId": null
}
],
"chatChannelId": "whatsapp-channel-test-5511123123123"
}
- Exemplo de envio de uma mensagem pelo operador:
{
"lastName": "Teste",
"chatPlatform": "whatsapp",
"whatsappNickName": "Usuário Teste",
"customerCreationTime": "2024-01-26T01:13:58.455Z",
"contactId": "558393846412",
"sessionId": "31JAOCZKUCK6HPH0NVKT_2024-02-14T13:18:45.730Z",
"type": "message",
"whatsappNumber": "5511123123123",
"firstName": "Usuário",
"sessionCreationTime": "2024-02-14T13:18:45.730Z",
"v": "1.1",
"customerId": "31JAOCZKUCK6HPH0NVKT",
"messages": [
{
"date": "2024-02-14T13:26:21.287Z",
"operatorEmail": "Usuário@botmaker.io",
"fromName": "Usuário Almeida",
"_id_": "SYWT2YP7TXWOF23LVU6N",
"from": "operator",
"clientPayload": "",
"message": "Oi\n",
"operatorId": "QISCSaluLphxOommBBkjNPt0bgt1",
"operatorName": "Usuário Almeida",
"queue": "_default_",
"operatorRole": "ADMIN"
}
],
"chatChannelId": "whatsapp-channel-test-5511123123123"
}
Lembre de visitar nossa Central de Ajuda para mais informações.
Escrito por: Equipe Botmaker
Atualizado: 08/02/2024