Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

10 per 10 min

Chamadas à API de perfil Messenger permitidas por Página em cada intervalo de 10 minutos.

4 questions

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.

20 items

Número máximo de itens de topo num menu persistente; o título de cada item está limitado a 30 caracteres.

24 hours

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.

Deprecated

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:

get_startedThe payload sent as a messaging_postbacks event when someone taps Get Started
greetingLocale-specific welcome screen text, which Meta marks deprecated as of November 2026
ice_breakersUp to 4 questions a person can tap to start the conversation
persistent_menuUp to 20 buttons kept in the conversation, per locale
commandsKeywords a person can tap or type, each with a description
whitelisted_domainsUp to 50 HTTPS domains for the Messenger Extensions SDK and the checkbox plugin
account_linking_urlThe HTTPS callback for linking a person's account with the business
subject_to_new_eu_privacy_rulesRead-only flag for Pages affected by Meta's Messenger API updates for Europe

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:

Get Started and a persistent menu in one POST
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_settings com 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.
Fazer isto com a EasyCoexistence

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