API de perfil Messenger: saudação, botão Get Started, quebra-gelos e menu persistente
O perfil Messenger de uma Página do Facebook define-se através de /{page-id}/messenger_profile com um token de acesso da Página e pages_messaging: POST escreve propriedades como get_started, greeting, ice_breakers, persistent_menu e commands, GET lê-as com fields, e DELETE remove as indicadas num array fields. A Meta permite 10 chamadas por 10 minutos por Página, e só são substituídas as propriedades enviadas.
O easyCoexistence responde às conversas do Messenger de uma Página com send_social_dm dentro da janela de 24 horas, a partir do Claude, do ChatGPT ou do seu próprio código, com as novas mensagens reencaminhadas para o seu endpoint à medida que chegam.
Chamadas à API de perfil Messenger permitidas por Página em cada intervalo de 10 minutos.
Número máximo de quebra-gelos que a API define; quando ambos estão definidos, os da API têm precedência sobre o botão Get Started.
Número máximo de itens de topo num menu persistente; o título de cada item está limitado a 30 caracteres.
Tempo máximo que uma atualização do menu persistente ao nível da Página pode demorar; um menu definido para uma pessoa atualiza em tempo real.
Texto de saudação, que a referência de saudação da Meta indica já não funcionar no Messenger para Android e iOS.
O que contém o perfil Messenger?
As definições a partir das quais parte a experiência Messenger de uma Página. A API de perfil Messenger da Meta lista estas propriedades, cada uma definida e lida no mesmo endpoint; numa aplicação em Modo de desenvolvimento, as definições só são visíveis para pessoas com uma função na aplicação:
Como se leem, definem e eliminam as propriedades?
Com três métodos num único endpoint, chamados com o token da Página. POST recebe um corpo JSON de propriedades e substitui apenas as que nomeia, GET recebe fields como lista separada por vírgulas, e DELETE recebe um corpo JSON cujo array fields indica o que remover; POST e DELETE respondem com result success. Definir um botão Get Started e um menu numa só chamada:
POST /{page-id}/messenger_profile
{
"get_started": { "payload": "GET_STARTED" },
"persistent_menu": [
{
"locale": "default",
"composer_input_disabled": false,
"call_to_actions": [
{ "type": "postback", "title": "Talk to an agent", "payload": "AGENT" },
{ "type": "web_url", "title": "Shop now", "url": "https://example.com/shop" }
]
}
]
}
{ "result": "success" }Como funciona o botão Get Started?
Aparece no ecrã de boas-vindas, que mostra o nome da Página, a foto de perfil, a imagem de capa e o tempo que a empresa costuma demorar a responder. Ao tocar, envia Get Started para a conversa, envia get_started.payload para a aplicação como evento messaging_postbacks e abre a janela de mensagens padrão. A Meta indica que o botão não é suportado quando o Messenger corre no navegador integrado da aplicação Facebook, e que um menu persistente exige que ele esteja definido primeiro.
O texto de saudação ainda funciona?
Não nos telemóveis. A referência da Meta tem agora o título [Deprecated] Greeting Text: a funcionalidade já não funciona no Messenger para Android e iOS e, embora a API possa ainda aceitar a propriedade greeting, os clientes não a verão, por isso a Meta pede aos programadores que a evitem. Tal como documentado, greeting tem um texto por idioma, com o locale default obrigatório, até 160 caracteres, personalizado com {{user_first_name}}, {{user_last_name}} ou {{user_full_name}}, e definir o texto exige a função de Administrador na Página.
Como funcionam os quebra-gelos?
Listam até 4 perguntas que a pessoa pode tocar para abrir uma conversa; a pergunta é publicada na conversa como se a pessoa a tivesse feito, e o seu payload regressa como evento postback. Desde abril de 2022 são localizados: cada objeto em ice_breakers contém call_to_actions e um locale, o locale default é obrigatório, e um DELETE de ice_breakers remove todos. A Meta ordena os elementos que disputam uma nova conversa:
- Os quebra-gelos da API têm prioridade sobre o botão Get Started quando ambos estão definidos.
- Ambos vêm antes das perguntas personalizadas definidas na caixa de entrada da Página, cuja edição fica desativada enquanto houver quebra-gelos da API definidos.
Como se constrói o menu persistente?
Como um array de menus, um por locale com o default obrigatório, cada um com até 20 call_to_actions do tipo web_url ou postback. Um título tem até 30 caracteres e um payload de postback até 1,000, e composer_input_disabled definido como true deixa o menu, os botões e as webviews como únicas formas de interação. Requisitos da Meta antes de aparecer:
- Um botão Get Started já definido e a permissão
pages_messaging. - Uma Página publicada e a aplicação definida como pública.
- A função de Administrador na Página para quem o define.
- Messenger v106 ou posterior em iOS ou Android, fora do navegador integrado da aplicação Facebook.
- As alterações ao nível da Página podem demorar até 24 horas; um menu para uma só pessoa, definido através de
custom_user_settingscom um PSID, atualiza em tempo real.
O que são comandos?
Palavras-chave que a pessoa pode invocar a qualquer momento, a partir de um menu de comandos junto ao campo de escrita, escrevendo uma barra ou uma arroba, ou a partir de um popover quando escreve uma palavra correspondente. Cada locale tem entre 1 e 100 comandos, com um nome de 1 a 32 caracteres sem barra inicial e uma descrição de 1 a 64; quando há comandos definidos, têm prioridade sobre o menu persistente. Os comandos invocados chegam à aplicação dentro do evento messages, em message.commands.
O que fazem whitelisted_domains e account_linking_url?
Ambos servem experiências fora da própria conversa. whitelisted_domains lista até 50 domínios que a webview do Messenger pode abrir para o SDK Messenger Extensions e o plugin de caixa de seleção, cada um servido em HTTPS sob um nome totalmente qualificado, nunca um endereço IP ou localhost, e definir a lista exige a função de Administrador na Página. account_linking_url é o callback HTTPS que liga a conta Messenger de uma pessoa à sua conta na empresa.
Como é que o easyCoexistence define o perfil Messenger de uma Página?
Não: nenhuma ferramenta chama {page-id}/messenger_profile, e os tokens das Páginas não são entregues, pelo que definir o perfil fica fora desta ligação. Os comandos que as pessoas invocam chegam no evento messages que o easyCoexistence reencaminha e que as automações leem; os toques que a Meta reporta como eventos messaging_postbacks, a partir do botão Get Started, dos itens de menu com postback e dos quebra-gelos, não são reencaminhados, já que as Páginas estão subscritas a feed, messages e mention.
Erros comuns
- Definir um menu persistente antes do Get Started. Os requisitos da Meta incluem um botão Get Started, por isso defina primeiro get_started.
- Deixar de fora o locale default. Quebra-gelos, menus e comandos precisam cada um de um objeto com locale definido como default, como alternativa.
- Chamar a API de perfil num ciclo. A Meta permite 10 chamadas por 10 minutos por Página, por isso junte várias propriedades num único POST.
- Esperar que uma alteração ao menu seja imediata. Uma atualização do menu ao nível da Página pode demorar até 24 horas a chegar às pessoas.
Definir o perfil Messenger não está entre as suas ferramentas. De US$ 9 até US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, e os primeiros 3 dias são gratuitos.
Perguntas frequentes
Um menu persistente pode variar por pessoa?
Sim. custom_user_settings com o PSID da pessoa substitui o menu da Página para essa pessoa, atualiza em tempo real e permite 10 chamadas por pessoa em 10 minutos.
Que locales o perfil Messenger suporta?
Os que constam da lista de locales suportados pela Meta, como en_GB, pt_BR ou ja_JP, mais default, a alternativa usada quando nenhum locale corresponde ao da pessoa.
Quem pode alterar o perfil Messenger de uma Página?
Uma aplicação com token de Página que tenha pages_messaging. O menu persistente, a saudação e a lista de domínios exigem também a função de Administrador na Página.
Quanto custa o easyCoexistence para uma Página do Facebook?
Cada Página é uma ligação: de US$ 9 até US$ 0.75 por ligação por mês, descendo à medida que aumenta o número de ligações, e os primeiros 3 dias são gratuitos.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em