Menu persistente

Este documento mostra como adicionar o menu persistente à sua experiência de mensagem de forma programática.

Como funciona Com o menu persistente, é possível criar e enviar um menu com informações importantes (como horário de funcionamento, endereços de lojas e produtos), que fica sempre visível nas conversas do Messenger com sua empresa. Quando uma pessoa clica em um item no menu, você recebe uma notificação de webhook postback. A notificação contém informações sobre o item selecionado e o responsável. Essa ação abre a janela de mensagens padrão de 24 horas.

Requisitos

Estas são as condições para que o menu persistente apareça:

• A pessoa precisa estar executando o Messenger v106 ou superior em um dispositivo Android ou iOS.
• A Página do Facebook em que o bot do Messenger está inscrito precisa estar publicada.
• O bot do Messenger precisar estar definido como “público” nas configurações do app.
• O bot do Messenger precisa ter a permissão pages_messaging.
• O bot do Messenger precisa ter um botão começar definido.

Botões compatíveis

O menu persistente é composto por uma matriz de botões. Estes tipos de botão são compatíveis com o menu persistente:

• web_url: define o item como um botão de URL.
• postback: define o item como um botão de postback.

Como configurar o menu persistente

Para configurar o menu persistente, envie uma solicitação POST à API do Perfil do Messenger a fim de definir a propriedade persistent_menu do perfil do Messenger do seu bot.

Como forma de substituir o menu no nível aninhado que foi descontinuado, permitimos até 20 botões na matriz call_to_actions na versão 8.0 e superiores da Graph API.

{
    "persistent_menu": [
        {
            "locale": "default",
            "composer_input_disabled": false,
            "call_to_actions": [
                {
                    "type": "postback",
                    "title": "Talk to an agent",
                    "payload": "CARE_HELP"
                },
                {
                    "type": "postback",
                    "title": "Outfit suggestions",
                    "payload": "CURATION"
                },
                {
                    "type": "web_url",
                    "title": "Shop now",
                    "url": "https://www.originalcoastclothing.com/",
                    "webview_height_ratio": "full"
                }
            ]
        }
    ]
}

Menu persistente aninhado

Como desabilitar o compositor

Caso você prefira que o menu persistente seja a única forma de interagir com seu bot, desabilite o compositor. Isso será útil se o bot tiver um conjunto de opções ou um propósito muito específico.

Para isso, defina "composer_input_disabled":true ao criar o menu persistente.

Localização

É possível fornecer texto localizado e padrão para os botões do menu persistente que serão exibidos na localidade de uma pessoa.

Para isso, especifique um objeto separado na matriz persistent_menu para cada localidade. Para especificar a localidade de cada objeto, defina a propriedade locale como uma localidade compatível:

{
  "locale":"default",
  "call_to_actions":[...]
},
{
  "locale: "zh_CN",
  "call_to_actions":[...]
}

Menu do nível do usuário

É possível substituir o menu persistente no nível da Página por uma configuração no nível do usuário. Isso permite que seu app controle de maneira dinâmica:

• os botões de clique para ação no menu do usuário;
• a visibilidade do compositor para o usuário.

Para habilitar ou desabilitar a configuração no nível do usuário, é usado o ponto de extremidade custom_user_settings. Esse ponto de extremidade é compatível com chamadas POST, GET e DELETE.

As mesmas configurações disponíveis para o menu persistente no nível da Página são aplicadas no nível do usuário. A principal diferença é que, para indicar o usuário ao qual a substituição se aplica, é necessário um parâmetro psid.

Observação: a atualização do menu persistente no nível do usuário acontece em tempo real; no nível da Página, ela pode levar até 24 horas.

As configurações no nível do usuário têm um limite de taxa de 10 chamadas por usuário a cada 10 minutos.

Exemplo de solicitação POST

Esta solicitação substituirá as configurações atuais no nível da página para o usuário.

curl -X POST -H "Content-Type: application/json" -d '{
  "psid": "<PSID>",
  "persistent_menu": [
        {
            "locale": "default",
            "composer_input_disabled": false,
            "call_to_actions": [
                {
                    "type": "postback",
                    "title": "Talk to an agent",
                    "payload": "CARE_HELP"
                },
                {
                    "type": "postback",
                    "title": "Outfit suggestions",
                    "payload": "CURATION"
                },
                {
                    "type": "web_url",
                    "title": "Shop now",
                    "url": "https://www.originalcoastclothing.com/",
                    "webview_height_ratio": "full"
                }
            ]
        }
    ]
}' "https://graph.facebook.com/v19.0/me/custom_user_settings?access_token=<PAGE_ACCESS_TOKEN>"

Exemplo de solicitação GET

Esta solicitação recuperará as configurações atuais no nível da página e do usuário. Se não houver configurações no nível do usuário, apenas aquelas no nível da página serão retornadas.

curl -X GET "https://graph.facebook.com/v19.0/me/custom_user_settings?psid=<PSID>&access_token=<PAGE_ACCESS_TOKEN>"

Resultado

{
    "data": [
      {
        "user_level_persistent_menu": [
            {
              "locale": "default",
              "composer_input_disabled": false,
              "call_to_actions": [
                  {
                      "type": "postback",
                      "title": "Talk to an agent",
                      "payload": "CARE_HELP"
                  },
                  {
                      "type": "postback",
                      "title": "Outfit suggestions",
                      "payload": "CURATION"
                  },
                  {
                      "type": "web_url",
                      "title": "Shop now",
                      "url": "https://www.originalcoastclothing.com/",
                      "webview_height_ratio": "full"
                  }
              ]
            }
        ],
        "page_level_persistent_menu": [
          Original Page Menu...
        ]  
      }
  ]
}

Exemplo de solicitação DELETE

Esta solicitação removerá as configurações no nível do usuário, deixando o menu no nível da página (se configurado).

curl -X DELETE 'https://graph.facebook.com/v19.0/me/custom_user_settings?psid=<PSID>&params=[%22persistent_menu%22]&access_token=<PAGE_ACCESS_TOKEN>'

Como desabilitar o menu persistente

Em alguns casos, talvez seja melhor desabilitar o menu persistente do bot no plugin de bate-papo. Para fazer isso, adicione "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"] ao definir o menu persistente:

Exemplo de carga da API do Perfil do Messenger

{
  "persistent_menu":[
    {
      "locale":"default",
      "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"],
      "composer_input_disabled": false,      
      "call_to_actions":[
        {
          "title":"My Account",
          "type":"postback",
          "payload":"PAYBILL_PAYLOAD"
        }
      ]
    }
  ]
}

Boas práticas

Assim como os botões, os itens de menu podem gerar um webView ou postback. Vale lembrar que o menu no segundo nível não é compatível.