- Compreendendo as solicitações externas
As solicitações externas de api são o meio de comunicação do seu chatbot com outros softwares ou serviços na internet. Ele permite que seu chatbot recupere informações desses serviços ou compartilhe informações com eles de forma integrada. Essencialmente, é a maneira do seu chatbot fazer perguntas ou trocar informações com o mundo digital mais amplo.
O recurso Solicitação Externa permite a interação com serviços externos, APIs (Interfaces de Programação de Aplicativos) ou sites para recuperar dados ou executar ações. Ele permite que você busque dados de qualquer outro sistema e apresente-os ao usuário dentro do seu Chatbot.
- Tipos de solicitações externas
Existem dois tipos principais de solicitações externas: HTTP GET e HTTP POST , cada um servindo a propósitos distintos. Vamos nos aprofundar nesses tipos e entender quando empregar cada um:
- GET HTTP:
1. Propósito:
A solicitação HTTP GET é usada para recuperar dados de um recurso especificado sem alterá-lo ou modificá-lo. É usado principalmente para buscar informações.
2. Características:
– Os parâmetros são enviados na URL como parâmetros de consulta.
– As solicitações GET normalmente são armazenadas em cache pelos navegadores, tornando-as adequadas para operações idempotentes e somente leitura .
– As solicitações GET são visíveis na URL, o que significa que dados confidenciais (como senhas) não devem ser incluídos nas solicitações GET.
3. Casos de uso:
– Recuperação de dados de uma API pública, como informações meteorológicas ou manchetes de notícias.
– Buscar o perfil de um usuário passando seu nome de usuário na URL.
– Acessar páginas da web ou recursos em um navegador clicando em links.
4. Quando usar GET:
– Quando você precisa recuperar dados de um servidor ou fonte externa.
– Para operações somente leitura que não modificam o estado do servidor.
– Quando os parâmetros ou dados da solicitação podem ser incluídos na URL (por exemplo, em parâmetros de consulta).
- POST HTTP:
1. Propósito:
A solicitação HTTP POST é usada para enviar dados a serem processados para um recurso especificado. É usado principalmente para enviar dados e criar ou atualizar recursos no servidor.
2. Características :
– Parâmetros e dados são enviados no corpo da solicitação , tornando-o adequado para envio de grandes quantidades de dados.
– As solicitações POST não são armazenadas em cache por padrão e não expõem dados confidenciais na URL .
– Eles são usados para ações que podem modificar o estado do servidor e não são idempotentes (o que significa que várias solicitações idênticas podem ter resultados diferentes).
3. Casos de uso:
– Envio de um formulário em um site para criar uma nova conta de usuário.
– Carregar um arquivo para um servidor.
– Envio de dados para uma API para atualizar as preferências do usuário.
4. Quando usar POST:
– Quando precisar enviar dados para um servidor ou serviço externo.
– Para operações que criam, atualizam ou excluem recursos no servidor.
– Quando os dados são sensíveis e não devem ser expostos na URL.
c. Quando escolher entre GET e POST:
– Use GET quando quiser recuperar dados de uma fonte externa, principalmente se a operação for idempotente (solicitações repetidas têm o mesmo resultado).
– Use POST quando precisar enviar dados para uma fonte externa para criar, atualizar ou excluir recursos, ou quando os dados são confidenciais e não devem ser expostos na URL.
3. Configurando a Solicitação Externa
No Construtor de Fluxo, adicione Ações > Solicitação Externa de API.
Como salvar dados em um campo personalizado?
Você pode utilizar o Mapeamento de Resposta para salvar dados da API em um Campo Personalizado se a API retorna dados no formato JSON. Muitas vezes, você pode querer obter dados de uma API e exibi-los para o usuário.
Por exemplo, vamos utilizar uma API de câmbio para mostrar como você poderia salvar os dados retornados de uma API em um campo personalizado. Abaixo está a resposta da API.
{
"success": true,
"timestamp": 1519296206,
"base": "EUR",
"date": "2021-03-17",
"rates": {
"AUD": 1.566015,
"CAD": 1.560132,
"CHF": 1.154727,
"CNY": 7.827874,
"GBP": 0.882047,
"JPY": 132.360679,
"USD": 1.23396
}
}
Se quiser exibir o valor em reais (R$), você precisará usar taxas de câmbio para converter de outra moeda para R$.
Para fazer isso, você pode testar sua solicitação, copiar a resposta recebida e usar um serviço que ajuda a extrair os dados corretos usando JSONPath (uma forma de navegar e extrair dados do formato JSON).
Este serviço também pode verificar se o seu JSONPath está correto. Você não precisa iniciar sua expressão JSONPath com “x” ao usar este serviço. É uma ferramenta para garantir que você está obtendo as informações corretas dos dados recebidos.
Existem duas maneiras de mostrar os dados obtidos de uma API ao usuário em seu chatbot:
1. Campo personalizado e mapeamento de resposta: você pode armazenar os dados da resposta da API em um campo personalizado, atuando como um espaço de armazenamento. Depois de armazenado, você poderá usar posteriormente esse campo personalizado no fluxo de conversa do seu chatbot para exibir as informações ao usuário.
2 . Conteúdo Dinâmico: Alternativamente, a API pode ser configurada para fornecer mensagens ou conteúdo diretamente adequado para exibição em seu chatbot. Isto implica que a resposta da API inclui texto ou informação pronta para apresentação ao usuário sem processamento adicional.
Você pode selecionar o método que melhor se alinha aos requisitos do seu chatbot e à estrutura da API.
Como obter o código de status HTTP ou todo o corpo da resposta?
No mapeamento de resposta, você pode usar os seguintes elementos para trabalhar com a resposta da API:
1. http_status_code: Este elemento permite capturar o código de status HTTP da resposta da API. Ele informa se a solicitação da API foi bem-sucedida ou encontrou um erro. Você pode salvar esse código de status em um campo personalizado para processamento posterior.
2. http_response_body: Este elemento permite capturar todo o corpo da resposta da API. Ele contém os dados ou conteúdo enviado de volta pela API, que você também pode salvar em um campo personalizado se quiser usá-lo posteriormente na conversa do seu chatbot.
3. http_download_EXTENSION: Se precisar baixar um tipo específico de arquivo, você pode usar este elemento. Por exemplo, se você quiser baixar um arquivo de áudio no formato MP3, você usaria `http_download_mp3`.
4. Conteúdo Dinâmico
O conteúdo dinâmico em seu chatbot permite que você gere e exiba conteúdo diretamente do seu servidor, garantindo a compatibilidade em todos os canais de comunicação. O sistema adapta automaticamente o conteúdo ao formato apropriado para o canal do usuário em tempo real.
No entanto, existe uma limitação crucial: você só pode empregar o recurso Conteúdo Dinâmico se possuir e gerenciar a API que fornece os dados. Se você não tiver controle sobre a API, ainda poderá trabalhar com seus dados salvando-os em um Campo Personalizado usando o Mapeamento de Resposta. Posteriormente, você pode exibir esses dados para o usuário no fluxo do chatbot usando o Campo Personalizado.
O formato de resposta para Conteúdo Dinâmico normalmente tem esta aparência:
{
"messages": [ ],
"actions": [ ]
}
As mensagens contêm mensagens enviadas aos contatos. Você pode enviar qualquer mensagem suportada pelo Messenger Bots.
Para recursos adicionais, consulte a documentação do Facebook. O GBOT inclui o cabeçalho ‘X-USER-ID’ em todas as solicitações, e o uso quick_replies é opcional.
Você pode enviar uma mensagem de texto da seguinte maneira:
{
"messages": [
{
"message": {
"text": "Hello world",
"quick_replies": []
}
}
]
}Enviando mais de uma única mensagem:
{
"messages": [
{
"message": {
"text": "Hello world"
}
},
{
"message": {
"text": "This is the second Message",
"quick_replies": []
}
}
]
}Você pode enviar uma mensagem de texto com botões e pode ter até 3 botões. O nome de cada botão pode ter até 20 letras. Se você quiser que algo aconteça quando alguém clicar em um botão, use um código especial chamado “Flow ID” como gatilho do botão.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"buttons": [
{
"title": "Open Website",
"type": "web_url",
"url": "your_URL"
},
{
"title": "Send Flow",
"payload": "FLOW_OR_STEP_ID",
"type": "postback"
},
{
"title": "Call Number",
"type": "phone_number",
"payload": "<your_phone_number_with_country_code>"
}
],
"template_type": "button",
"text": "Hello world"
},
"type": "template"
},
"quick_replies": []
}
}
]
}Payload:
Você pode usar qualquer ID de fluxo ou etapa como Payload. Por exemplo, se você quiser levar alguém para uma conversa específica quando ela clicar em um botão, poderá usar o ID da conversa como Payload. Este artigo também explica como usar ações como cargas úteis.
Ao enviar uma mensagem, você pode adicionar respostas rápidas a ela. As respostas rápidas funcionam com diferentes tipos de mensagens, como texto, arquivos e galerias. O Facebook permite que você inclua até 11 respostas rápidas em uma mensagem. A Payload que você usa para respostas rápidas é semelhante à que você usa para botões.
No caso de você ter mais de 11 opções, por favor, use a opção “Múltipla escolha” da ação Obter entrada do usuário em um bloco de mensagens.
{
"messages": [
{
"message": {
"text": "Hello world",
"quick_replies": [
{
"content_type": "text",
"title": "Quick Reply 1",
"payload": "FLOW_OR_STEP_ID"
},
{
"content_type": "text",
"title": "Any Text Here",
"payload": "FLOW_OR_STEP_ID"
}
]
}
}
]
}A estrutura para cargas úteis em respostas rápidas e botões é a mesma.
Para enviar uma imagem, vídeo, áudio ou arquivo, você pode usar a estrutura a seguir. Basta alterar o “media_type” para especificar se é uma imagem, vídeo, áudio ou arquivo. O “URL” deve ser o link para a imagem, áudio, vídeo ou arquivo específico que você deseja enviar.
{
"messages": [
{
"message": {
"attachment": {
"type": "image",
"payload": {
"url": "<ASSET_URL>"
}
},
"quick_replies": []
}
}
]
}Você pode enviar um único cartão e, neste cartão, tanto o título quanto a legenda podem ter até 80 caracteres cada.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"elements": [
{
"title": "Card Title",
"subtitle": "Card Subtitle",
"image_url": "image_url"
}
],
"template_type": "generic"
},
"type": "template"
},
"quick_replies": []
}
}
]
}Você pode enviar um único cartão, e esse cartão pode ter até 3 botões.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"elements": [
{
"title": "Card Title",
"subtitle": "Card Subtitle",
"image_url": "image_url",
"buttons": [
{
"title": "Button Label",
"type": "web_url",
"url": "your_URL"
},
{
"title": "Button Label",
"payload": "FLOW_OR_STEP_ID",
"type": "postback"
},
{
"title": "Button Label",
"type": "phone_number",
"payload": "+your_phone_number"
}
]
}
],
"template_type": "generic"
},
"type": "template"
},
"quick_replies": []
}
}
]
}Enviando uma Galeria
Enviar uma galeria é como enviar uma coleção de cartões. Você pode incluir até 10 cartões em uma galeria. Para cada cartão na galeria, você também pode adicionar um botão.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"elements": [
{
"title": "Card Title 1",
"subtitle": "Card Subtitle 1",
"image_url": "image_url 1",
"buttons": []
},
{
"title": "Card Title 2",
"subtitle": "Card Subtitle 2",
"image_url": "image_url 2",
"buttons": []
}
],
"template_type": "generic"
},
"type": "template"
},
"quick_replies": []
}
}
]
}Envio de mensagens suportado apenas pelo WhatsApp
O WhatsApp suporta vários tipos de mensagens que não são compatíveis com os bots do Messenger, incluindo Mensagens de Lista, Contatos, Locais ou Catálogos. No entanto, com o GBOT, você pode enviar qualquer tipo de mensagem suportada pelo WhatsApp. Você só precisa usar a estrutura de mensagens descrita na documentação do WhatsApp, e o GBOT lidará com o parâmetro “Para” automaticamente para você.
{
"messages": [
{
"messaging_product": "WhatsApp",
"recipient_type": "individual",
"to": null,
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "ANY TEXT"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "FLOW_OR_STEP_ID",
"title": "BUTTON_TITLE_1"
}
},
{
"type": "reply",
"reply": {
"id": "FLOW_OR_STEP_ID",
"title": "BUTTON_TITLE_2"
}
}
]
}
}
}
]
}Ações
O campo “Ações” é opcional, o que significa que você não precisa incluí-lo. As ações permitem que você faça coisas como adicionar ou remover tags, definir ou redefinir campos personalizados e enviar um fluxo.
Adicionar tags
{
"messages": [],
"actions": [
{
"action": "add_tag",
"tag_name": "..."
}
]
}Remover tag
{
"messages": [],
"actions": [
{
"action": "remove_tag",
"tag_name": "..."
}
]
}Definir campo personalizado
Essa ação não só permite que você use qualquer nome de campo personalizado, mas também permite que você modifique campos do sistema, como número de telefone, e-mail, nome completo, nome e sobrenome.
{
"messages": [],
"actions": [
{
"action": "set_field_value",
"field_name": "...",
"value": ""
}
]
}Redefinir campo personalizado:
{
"messages": [],
"actions": [
{
"action": "unset_field_value",
"field_name": "..."
}
]
}Enviar fluxo Para encontrar a ID do fluxo, vá para a lista de fluxos, clique nos três pontos e selecione “Obter link”. O ID do fluxo é o valor numérico no link. É sempre um número. Você pode combinar quantas ações precisar.
{
"messages": [],
"actions": [
{
"action": "send_flow",
"flow_id": "..."
}
]
}Combinar várias ações
Você tem a flexibilidade de combinar várias ações em uma única solicitação, o que permite executar várias ações simultaneamente. Por exemplo, você pode definir um campo personalizado e acionar um fluxo com apenas uma solicitação.
{
"messages": [],
"actions": [
{
"action": "set_field_value",
"field_name": "...",
"value": ""
},
{
"action": "send_flow",
"flow_id": "..."
}
]
}Use ações como uma Payload de botões e Resposta rápidas:
Para usar uma ação como Payload em botões, você pode seguir este formato. No entanto, tenha em mente que uma Payload é normalmente uma cadeia de caracteres. Portanto, você precisará converter seu objeto de ações em uma cadeia de caracteres JSON. Se você estiver usando PHP, poderá usar a função ‘json_encode’ para transformar seu objeto de ações em uma representação de cadeia de caracteres.
{
"actions": [
{
"action": "send_flow",
"flow_id": "..."
}
]
}{
"actions": [
{
"action": "send_flow",
"flow_id": "..."
}
],
"messages": [
{
"message": {
"attachment": {
"payload": {
"buttons": [
{
"title": "Click Here",
"payload": "{\"actions\":[{\"action\":\"send_flow\",\"flow_id\":\"FLOW_OR_STEP_ID\"}]}",
"type": "postback"
}
],
"template_type": "button",
"text": "Hello world"
},
"type": "template"
},
"quick_replies": []
}
}
]
}