EntrarComeçar teste grátis
easyCoexistence APIs oficiais

API de perfil do Messenger: saudação, botão Get Started, ice breakers e menu persistente

O perfil do Messenger de uma Página do Facebook é definido em /{page-id}/messenger_profile com um token de acesso da Página e a permissão pages_messaging: POST grava propriedades como get_started, greeting, ice_breakers, persistent_menu e commands, GET lê essas propriedades com fields, e DELETE remove as que forem indicadas em um array fields. A Meta permite 10 chamadas a cada 10 minutos por Página, e somente as propriedades enviadas são sobrescritas.

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 encaminhadas ao seu endpoint conforme chegam.

10 per 10 min

Chamadas da API de Perfil do Messenger permitidas por Página em cada intervalo de 10 minutos.

4 questions

Número máximo de ice breakers que a API pode definir; quando ambos estão definidos, os ice breakers da API têm precedência sobre o botão Get Started.

20 items

Número máximo de itens de nível superior em um menu persistente; o título de cada item é limitado a 30 caracteres.

24 hours

Tempo que pode levar uma atualização do menu persistente no nível da Página; um menu definido para uma pessoa é atualizado em tempo real.

Deprecated

Texto de saudação, que a referência de saudação da Meta indica que não funciona mais no Messenger para Android e iOS.

O que o perfil do Messenger contém?

As configurações a partir das quais a experiência do Messenger de uma Página começa. A API de Perfil do Messenger da Meta lista essas propriedades, cada uma definida e lida no mesmo endpoint; em um app no Modo de Desenvolvimento, as configurações ficam visíveis apenas para pessoas com um papel no app:

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 as propriedades são lidas, definidas e excluídas?

Com três métodos em um mesmo endpoint, chamados com o token da Página. POST recebe um corpo JSON de propriedades e sobrescreve apenas as que nomeia, GET recebe fields como uma 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. Definindo um botão Get Started e um menu em uma única 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?

Ele fica na tela de boas-vindas, que mostra o nome da Página, a foto de perfil, a foto de capa e o tempo que a empresa costuma levar para responder. Um toque publica Get Started na conversa, envia get_started.payload ao app como um evento messaging_postbacks e abre a janela de mensagens padrão. A Meta observa que o botão não é compatível quando o Messenger roda no navegador interno do app do Facebook, e um menu persistente exige que ele esteja definido antes.

O texto de saudação ainda funciona?

Não nos celulares. A referência da Meta agora se chama [Deprecated] Greeting Text: o recurso não funciona mais no Messenger para Android e iOS e, embora a API ainda possa aceitar a propriedade greeting, as pessoas não a verão, por isso a Meta pede que os desenvolvedores a evitem. Conforme documentado, greeting tem um texto por locale, com default obrigatório, de até 160 caracteres, personalizável com {{user_first_name}}, {{user_last_name}} ou {{user_full_name}}, e definir o texto exige o papel de Administrador na Página.

Como funcionam os ice breakers?

Eles listam até 4 perguntas que a pessoa pode tocar para abrir uma conversa; a pergunta é publicada no chat como se a pessoa a tivesse feito, e seu payload volta como um evento de postback. Desde abril de 2022 eles são localizados: cada objeto em ice_breakers contém call_to_actions e um locale, um locale default é obrigatório, e um DELETE em ice_breakers remove todos eles. A Meta classifica os elementos que disputam uma nova conversa:

  • Os ice breakers da API têm precedência 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 os ice breakers da API estiverem definidos.

Como o menu persistente é montado?

Como um array de menus, um por locale com 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 as únicas formas de interação. Os requisitos da Meta antes de ele aparecer:

  • Um botão Get Started já definido e a permissão pages_messaging.
  • Uma Página publicada e o app configurado como público.
  • O papel de Administrador na Página para quem o define.
  • Messenger v106 ou superior no iOS ou Android, fora do navegador interno do app do Facebook.
  • Alterações no nível da Página podem levar até 24 horas; um menu para uma pessoa, definido por custom_user_settings com um PSID, é atualizado em tempo real.

O que são comandos?

Palavras-chave que a pessoa pode invocar a qualquer momento, em um menu de comandos ao lado do campo de mensagem, digitando uma barra ou um arroba, ou em um pop-up quando ela digita uma palavra correspondente. Cada locale tem de 1 a 100 comandos, com nome de 1 a 32 caracteres e sem barra inicial, e descrição de 1 a 64; quando comandos são definidos, eles têm prioridade sobre o menu persistente. Os comandos invocados chegam ao app dentro do evento messages, em message.commands.

O que fazem whitelisted_domains e account_linking_url?

Ambos atendem 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 checkbox, cada um servido por HTTPS sob um nome totalmente qualificado, nunca um endereço IP ou localhost, e definir a lista exige o papel de Administrador na Página. account_linking_url é o callback HTTPS que vincula a conta do Messenger de uma pessoa à conta dela na empresa.

Como o easyCoexistence define o perfil do Messenger de uma Página?

Não pode: nenhuma ferramenta chama {page-id}/messenger_profile, e os tokens da Página não são entregues, então definir o perfil fica fora desta conexão. Os comandos que as pessoas invocam chegam no evento messages que o easyCoexistence encaminha e que as automações leem; os toques que a Meta informa como eventos messaging_postbacks, vindos de Get Started, itens de menu com postback e ice breakers, não são encaminhados, já que as Páginas estão inscritas em feed, messages e mention.

Erros comuns

  • Definir um menu persistente antes do Get Started. Os requisitos da Meta incluem um botão Get Started, então defina get_started primeiro.
  • Esquecer o locale padrão. Ice breakers, menus e comandos precisam de um objeto com locale definido como default, que serve de fallback.
  • Chamar a API de perfil em um loop. A Meta permite 10 chamadas a cada 10 minutos por Página, então coloque várias propriedades em um único POST.
  • Esperar que uma alteração do menu valha de imediato. Uma atualização do menu no nível da Página pode levar até 24 horas para chegar às pessoas.
Fazendo isso com o EasyCoexistence

Definir o perfil do Messenger não está entre as suas ferramentas. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Um menu persistente pode ser diferente para cada pessoa?

Sim. custom_user_settings com o PSID da pessoa substitui o menu da Página para essa pessoa, é atualizado em tempo real e permite 10 chamadas por pessoa a cada 10 minutos.

Quais locales o perfil do Messenger suporta?

Os que constam na lista de locales compatíveis da Meta, como en_GB, pt_BR ou ja_JP, além de default, o fallback usado quando nenhum locale corresponde ao da pessoa.

Quem pode alterar o perfil do Messenger de uma Página?

Um app com token de Página que tenha a permissão pages_messaging. O menu persistente, a saudação e a lista de domínios também exigem o papel de Administrador na Página.

Quanto custa o easyCoexistence para uma Página do Facebook?

Cada Página é uma conexão: de US$ 9 a US$ 0.75 por conexão por mês, com o preço caindo conforme o número de conexões aumenta, e os primeiros 3 dias são grátis.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em