Como usar a Solicitação Externa / Conteúdo Dinâmico?

Contato

Cadastre-se

Contato

Cadastre-se

Busca...

Avançado

Como usar a Solicitação Externa / Conteúdo Dinâmico?

A Solicitação Externa permite que você integre seu bot a qualquer sistema que tenha uma API. Você pode usar solicitações externas para obter dados de qualquer outro sistema e exibir os dados para o usuário dentro do seu chatbot.

Neste artigo:

Como usar a solicitação externa?
Como salvar dados em um campo personalizado?
Como obter o código de status HTTP ou todo o corpo da resposta?
Conteúdo dinâmico
Envie mensagens suportadas apenas pelo WhatsApp

Como usar a solicitação externa?

No construtor de fluxo, adicione Ações > Solicitação de API externa.

Como salvar dados em um campo personalizado?

Você pode usar o Mapeamento de resposta para salvar dados da API em um campo personalizado se a API retornar dados no formato JSON. Muitas vezes, você pode querer obter dados de uma API e mostrar os dados ao usuário.

Por exemplo, usaremos uma API de câmbio para mostrar como você pode 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 quisermos mostrar o valor em USD, você precisará usar taxas. USD, aconselhamos que você teste sua solicitação, copie a resposta e use este serviço para obter o JSONPath correto. Além disso, você pode usar este serviço para verificar se o seu JSONPath está correto. Não há necessidade de iniciar seu JSONPath por x.

Há duas maneiras de exibir os dados retornados de uma API para o usuário dentro do bot. Você pode salvar os dados em um campo personalizado usando o Mapeamento de resposta e usar o campo personalizado em seu fluxo para mostrar os dados ao usuário. Além disso, sua API pode retornar mensagens prontas para serem exibidas ao usuário final dentro do seu bot (Conteúdo Dinâmico). Os conteúdos dinâmicos são explicados abaixo neste artigo.

Como obter o código de status HTTP ou todo o corpo da resposta?

No mapeamento de resposta, use http_status_code para obter o código de resposta e use http_response_body para obter todo o corpo da resposta. Depois de salvar o código de status HTTP em um campo personalizado, você pode usar condições para fazer qualquer lógica que desejar. Para baixar um arquivo, use http_download_EXTENSION. Por exemplo, para baixar áudio, você pode usar http_download_mp3.

Conteúdo dinâmico

Os conteúdos dinâmicos permitem que você gere conteúdo do seu servidor e o exiba para o usuário dentro do seu Chatbot. O conteúdo dinâmico é compatível com todos os canais. Você usa um único formato que funciona em todos os canais. Nossa plataforma converte automaticamente sua mensagem em tempo real e a entrega ao usuário.

Você não pode usar o recurso Conteúdo dinâmico se não for o proprietário da API que está recebendo dados. Nesse caso, você pode salvar dados da API em um campo personalizado usando o mapeamento de resposta e exibir os dados usando o campo personalizado no construtor de fluxo.

O formato da resposta está abaixo.

{
    "messages": [],
    "actions": []
}

Mensagens: contém mensagens que são enviadas aos contatos. Você pode enviar qualquer mensagem suportada pelos Messenger Bots. Este artigo mostra alguns exemplos de formato, mas você pode ler a documentação do Facebook se precisar de mais recursos.

O ChatBot360 envia um cabeçalho 'X-USER-ID' em cada solicitação.

quick_replies é sempre opcional.

Envie uma mensagem de texto

{
    "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":[]
            }
        }
    ]
}

Enviando uma mensagem de texto com botões

A mensagem de texto pode conter até 3 botões. O título de cada botão pode conter até 20 caracteres. Para enviar um fluxo quando um usuário clica em um botão, use uma ID de fluxo como uma carga útil 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_county_code>"
                            }
                        ],
                        "template_type": "button",
                        "text": "Hello world"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }            
        }
    ]
}

Carga: você pode usar qualquer ID de fluxo/etapa como uma carga. Por exemplo, se você quiser redirecionar para um fluxo depois que o usuário clicar no botão, poderá usar o ID do fluxo como uma carga. Neste artigo, mostramos como usar ações como cargas também.

Enviando uma mensagem com respostas rápidas

As respostas rápidas podem ser adicionadas a qualquer tipo de mensagem (texto, arquivo, galeria, arquivo, ...). O Facebook permite que você anexe no máximo 11 respostas rápidas a uma mensagem. A carga útil para respostas rápidas é a mesma que a carga útil para botões.

{
   "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"
                  }
               ]
           }
           
       }
   ]
}

As cargas úteis em respostas rápidas e botões têm a mesma estrutura

Envie uma imagem, vídeo, áudio, arquivo

Você pode usar a mesma estrutura abaixo para enviar uma imagem, vídeo, áudio e arquivo. Basta alterar o media_type para vídeo, áudio ou arquivo. "URL" será o link para sua imagem, áudio, vídeo ou arquivo.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "type": "image",
                    "payload": {
                        "url": "<ASSET_URL>"
                    }
                },
                "quick_replies":[]
            }
        }
    ]
}

Enviar um único cartão

O título e o subtítulo do cartão podem ter até 80 caracteres.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Card Title",
                                "subtitle": "Card Subtitle",
                                "image_url": "image_url"
                            }
                        ],
                        "template_type": "generic",
                        "image_aspect_ratio":"horizontal"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }
        }
    ]
}

Valores possíveis para image_aspect_ratio: horizontal ou quadrado

Enviar um único cartão com botões

Um cartão pode conter 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",
                        "image_aspect_ratio":"horizontal"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }
        }
    ]
}

Envie uma galeria

Basicamente, uma galeria é um conjunto de cartas. Uma galeria pode conter até 10 cartas. O código abaixo mostra uma galeria com 2 cartas. Você também pode adicionar um botão a cada cartã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",
                        "image_aspect_ratio":"horizontal"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }
        }
    ]
}

Envie mensagens suportadas apenas pelo WhatsApp

O WhatsApp oferece suporte a muitos tipos de mensagens que não são compatíveis com bots do Messenger, como Lista, Contatos, Locais ou Mensagens de Catálogos. O ChatBot360 permite que você envie qualquer mensagem suportada pelo WhatsApp. Você só precisa fornecer a mesma estrutura de mensagem descrita na documentação do WhatsApp. O ChatBot360 definirá automaticamente o parâmetro "to".

{   
    "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: é opcional incluir este campo. Você pode usar ações para adicionar/remover etiquetas, definir/desconfigurar campos personalizados e enviar um fluxo...

Adicionar etiqueta

{
    "messages": [],
    "actions": [
        {
            "action": "add_tag",
            "tag_name": "..."
        }
    ]
}

Remover etiqueta

{
    "messages": [],
    "actions": [
        {
            "action": "remove_tag",
            "tag_name": "..."
        }
    ]
}

Definir campo personalizado

Além de aceitar qualquer nome de campo personalizado, esta ação também permite alterar campos do sistema como phone, e-mail, full_name, first_name, last_name

{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "...",
            "value": ""
        }
    ]
}

Campo personalizado não definido

{
    "messages": [],
    "actions": [
        {
            "action": "unset_field_value",
            "field_name": "..."
        }
    ]
}

Enviar fluxo

Para obter o ID do fluxo, você precisa ir para a lista de fluxos, clicar nos 3 pontos e clicar em Obter link. O flow-id é o número incluído no seu link. O ID do fluxo é sempre numérico. Você pode combinar um número ilimitado de ações.

{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "...",
            "value": ""
        }
    ]
}

Transferir conversa para humano/bot

{
    "messages": [],
    "actions": [
        {
            "action": "transfer_conversation_to",
            "value": "human"
        }
    ]
}

Atribuir uma conversa ao administrador

{
    "messages": [],
    "actions": [
        {
            "action": "assign_conversation",
            "admin_id": "..."
        }
    ]
}

Cancelar a atribuição de uma conversa do administrador

{
    "messages": [],
    "actions": [
        {
            "action": "unassign_conversation"
        }
    ]
}

Combine várias ações

Você pode combinar várias ações em uma única solicitação para permitir que você execute várias simultaneamente. Por exemplo, talvez você queira definir um campo personalizado e enviar um fluxo em uma única solicitação.

{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "...",
            "value": ""
        },
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

Use ações como uma carga útil de botões e quick_replies

Abaixo está o formato para usar uma ação como carga útil nos botões. Mas como uma carga é uma string, você precisa converter seu objeto actions em uma string JSON. Se você estiver usando PHP, use json_encode para obter uma representação de string do seu objeto.

{   
    "actions": [
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

Abaixo, a ação acima é usada como uma carga útil do botão.

{
    "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":[]
            }            
        }
    ]
}