O que é um Menu Persistente?

Um Menu Persistente permite exibir um menu permanente com as principais ações do seu negócio, como horário de funcionamento, localizações de lojas, produtos ou outras opções usadas com frequência. O menu fica sempre visível durante uma conversa com seu bot do Facebook Messenger.

Tipos de Botão Suportados

O Menu Persistente suporta os seguintes tipos de botão:

  • Botões de URL (web_url)
  • Botões de Callback (postback)

Criar um Menu Persistente

Use a função a seguir para criar um Menu Persistente para uma página do Facebook:

response = fb_set_persistent_menu(group_id, buttons)

Parâmetros

Parâmetro Descrição
group_id ID do Bot do Facebook. Você pode encontrá-lo na seção Canal do seu projeto MaviBot.
buttons Dicionário descrevendo os botões do menu.

Estrutura do Dicionário de Botões

buttons = {
    "default": [
        ["postback", "Botão 1", "texto_callback 1"],
        ["postback", "Botão 2", "texto_callback 2"],
        ["web_url", "Site", "https://mavibot.ai/"]
    ]
}

A chave default é obrigatória. Ela define os botões exibidos para usuários cujo idioma não possui um menu personalizado.

Cada botão é descrito por um array:

["tipo_botao", "Texto do botão", "Valor"]

Formatos de Botão Suportados

Botão de Callback

["postback", "Texto do botão", "texto_callback"]
Valor Descrição
postback Tipo do botão.
Texto do botão Texto exibido no botão.
texto_callback Texto enviado ao bot quando o botão é clicado.

Botão de URL

["web_url", "Texto do botão", "https://exemplo.com"]
Valor Descrição
web_url Tipo do botão.
Texto do botão Texto exibido no botão.
URL Site aberto quando o botão é clicado.

Localização

Você pode exibir menus diferentes dependendo do idioma do usuário.

Basta adicionar chaves adicionais ao dicionário de botões.

Exemplo:

buttons = {
    "default": [
        ["postback", "Botão 1", "texto_callback 1"],
        ["postback", "Botão 2", "texto_callback 2"],
        ["web_url", "Site", "https://mavibot.ai/"]
    ],
    "en_EN": [
        ["postback", "Button", "callback_text 1"],
        ["postback", "Button 2", "callback_text 2"],
        ["web_url", "Website", "https://mavibot.ai/"]
    ]
}

Neste exemplo, usuários com o idioma en_EN receberão um menu diferente.

Idiomas Suportados

af_ZA, ar_AR, as_IN, az_AZ, be_BY, bg_BG, bn_IN, br_FR, bs_BA, ca_ES,
cb_IQ, co_FR, cs_CZ, cx_PH, cy_GB, da_DK, de_DE, el_GR, en_GB, en_UD,
en_US, es_ES, es_LA, et_EE, eu_ES, fa_IR, ff_NG, fi_FI, fo_FO, fr_CA,
fr_FR, fy_NL, ga_IE, gl_ES, gn_PY, gu_IN, ha_NG, he_IL, hi_IN, hr_HR,
hu_HU, hy_AM, id_ID, is_IS, it_IT, ja_JP, ja_KS, jv_ID, ka_GE, kk_KZ,
km_KH, kn_IN, ko_KR, ku_TR, lt_LT, lv_LV, mg_MG, mk_MK, ml_IN, mn_MN,
mr_IN, ms_MY, mt_MT, my_MM, nb_NO, ne_NP, nl_BE, nl_NL, nn_NO, or_IN,
pa_IN, pl_PL, ps_AF, pt_BR, pt_PT, qz_MM, ro_RO, ru_RU, rw_RW, sc_IT,
si_LK, sk_SK, sl_SI, so_SO, sq_AL, sr_RS, sv_SE, sw_KE, sz_PL, ta_IN,
te_IN, tg_TJ, th_TH, tl_PH, tr_TR, tz_MA, uk_UA, ur_PK, uz_UZ, vi_VN,
zh_CN, zh_HK, zh_TW

Criar um Menu Persistente para um Usuário Específico

Para criar um menu que fique visível apenas para o usuário para o qual a função é chamada, passe 1 como terceiro parâmetro.

response = fb_set_persistent_menu(group_id, buttons, 1)

Nota

Menus Persistentes em nível de usuário são atualizados imediatamente.

Menus Persistentes em nível de página podem levar até 24 horas para serem atualizados.

O Facebook também limita as atualizações de menu em nível de usuário a 10 solicitações por usuário a cada 10 minutos.

Desabilitar o Compositor

Você pode desabilitar o compositor do Messenger para que os usuários interajam com o bot apenas através do Menu Persistente.

Isso é útil quando o bot deve permitir apenas ações predefinidas.

Desabilitar o Compositor para Todos os Usuários

response = fb_set_persistent_menu(group_id, buttons, "", 1)

Desabilitar o Compositor para um Usuário Específico

response = fb_set_persistent_menu(group_id, buttons, 1, 1)

Parâmetros

Parâmetro Descrição
group_id ID do Bot do Facebook.
buttons Dicionário de botões.
3º parâmetro Defina como 1 para aplicar o menu apenas ao usuário atual. Deixe vazio para aplicar à página.
4º parâmetro Defina como 1 para desabilitar o compositor do Messenger.

Valores de Retorno

Se a função for concluída com sucesso:

{"result":"success"}

Caso contrário, uma descrição do erro é retornada.

Exemplo:

Error parse buttons data

ou

{
  "error": {
    "message": "(#100) param persistent_menu[0][call_to_actions] must be non-empty.",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "AJtVczu7TEJJxbMfnO"
  }
}

Exemplos

Criar um Menu para Todos os Usuários

buttons = {
    "default": [
        ["postback", "Botão 1", "texto_callback 1"],
        ["postback", "Botão 2", "texto_callback 2"],
        ["web_url", "Site", "https://mavibot.ai/"]
    ],
    "en_EN": [
        ["postback", "Button", "callback_text 1"],
        ["postback", "Button 2", "callback_text 2"],
        ["web_url", "Website", "https://mavibot.ai/"]
    ]
}

response = fb_set_persistent_menu("123456789", buttons)

Criar um Menu para Todos os Usuários e Desabilitar o Compositor

buttons = {
    "default": [
        ["postback", "Botão 1", "texto_callback 1"],
        ["postback", "Botão 2", "texto_callback 2"],
        ["web_url", "Site", "https://mavibot.ai/"]
    ],
    "en_EN": [
        ["postback", "Button", "callback_text 1"],
        ["postback", "Button 2", "callback_text 2"],
        ["web_url", "Website", "https://mavibot.ai/"]
    ]
}

response = fb_set_persistent_menu("123456789", buttons, "", 1)

Criar um Menu para o Usuário Atual

buttons = {
    "default": [
        ["postback", "Botão 1", "texto_callback 1"],
        ["postback", "Botão 2", "texto_callback 2"],
        ["web_url", "Site", "https://mavibot.ai/"]
    ]
}

response = fb_set_persistent_menu("123456789", buttons, 1)

Criar um Menu de Usuário e Desabilitar o Compositor

buttons = {
    "default": [
        ["postback", "Botão 1", "texto_callback 1"],
        ["postback", "Botão 2", "texto_callback 2"],
        ["web_url", "Site", "https://mavibot.ai/"]
    ]
}

response = fb_set_persistent_menu("123456789", buttons, 1, 1)

Excluir um Menu Persistente

Excluir o Menu em Nível de Página

response = fb_delete_persistent_menu(group_id)

Resposta de sucesso:

{"result":"success"}

Possível erro:

Bot not found

Excluir um Menu em Nível de Usuário

response = fb_delete_persistent_menu(group_id, 1)

Resposta de sucesso:

{"result":"success"}

Possível erro:

Bot not found