EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Protocolo de transferência do Messenger: compartilhando a caixa de entrada de uma Página entre um agente de IA e pessoas

A Meta substituiu o protocolo de transferência do Messenger pelo recurso Conversation Routing, que mantém as chamadas de controle de conversa: pass_thread_control passa uma conversa a outro app, como a caixa de entrada da Página com app ID 263902037430900, take_thread_control a assume, request_thread_control a solicita e release_thread_control a devolve ao estado inativo. Com o recurso Conversation Routing ativado, o app que controla uma conversa recebe as mensagens dela, e os demais as recebem pelo canal standby.

O easyCoexistence dá ao seu agente de IA as conversas do Messenger de uma Página por meio de um único conector MCP: send_social_dm responde dentro da janela de 24 horas e novas mensagens são encaminhadas ao seu endpoint conforme chegam.

263902037430900

O target_app_id que a Meta fornece para passar o controle de uma conversa à caixa de entrada da Página.

2018300

Subcódigo, sob o erro 10, para uma mensagem que falhou porque outro app controla a conversa.

24 hours

Sem mensagem da pessoa por este tempo, a conversa fica inativa, e só o app padrão pode enviar.

Up to 7 days

Até onde o extend_thread_control pode estender o controle de um app além da janela de tempo de resposta de 24 horas.

Off by default

Assuma o controle das conversas com seu Business AI; com a opção desligada, envios sem tag para uma conversa do Business AI falham com 10, 2018300.

O que aconteceu com o protocolo de transferência?

A Meta o incorporou ao Conversation Routing. O guia diz que a Meta não oferece mais suporte ao protocolo de transferência do Messenger, que as empresas foram migradas para o Conversation Routing e que o recurso é compatível com versões anteriores da maioria das chamadas do protocolo, então pass_thread_control, take_thread_control e o webhook messaging_handovers devem continuar funcionando. O que mudou foi quem decide: a empresa define um app padrão e regras de roteamento nas configurações da Página, na seção Conversation Routing.

Quem controla uma conversa?

Um app de cada vez, que a Meta chama de dono da conversa. Uma conversa fica ativa enquanto a pessoa e o app dono conversam, e inativa quando a pessoa não escreve há 24 horas ou o dono libera o controle; em uma conversa inativa, só o app padrão pode enviar, dentro da janela de atendimento. As regras de roteamento decidem quem assume uma conversa:

  • App padrão: o que responde quando nenhum outro app está configurado ou respondendo.
  • Roteamento social: o app que assume o controle quando a pessoa abre uma conversa inativa ou toca em Get Started.
  • Roteamento por link: um app atribuído a cada link m.me.
  • Roteamento por campanha: o app escolhido para um anúncio Click-to-Messenger, que controla a conversa durante a janela de atendimento dela, de até 7 dias.

Quais chamadas movem o controle entre apps?

Cada uma é um POST para um edge da Página com recipient definido como o PSID da pessoa, e cada uma responde success true; a maioria também aceita uma string metadata que o próximo app recebe:

  • pass_thread_control: passa a conversa ao app em target_app_id, que recebe um evento messaging_handovers.
  • release_thread_control: encerra o controle do app e devolve a conversa ao estado inativo.
  • take_thread_control: torna o app que chama o dono, para os apps que a empresa permite assumir o controle.
  • request_thread_control: pede o controle da conversa.
  • extend_thread_control: mantém o controle além da janela de tempo de resposta de 24 horas, de até 7 dias, com duration em segundos.
  • A Send API pode passar ou liberar o controle junto com a própria mensagem, por meio de um objeto thread_control.
Handing a conversation to the Page Inbox
POST /{page-id}/pass_thread_control
  ?recipient={id:<PSID>}
  &target_app_id=263902037430900
  &metadata=Customer asked for a person

{ "success": true }

Como as pessoas entram pela caixa de entrada da Página?

Respondendo. O Conversation Routing trata a caixa de entrada do Meta Business Suite como mais um app conectado, que a empresa pode até tornar o padrão; quando alguém responde ali em uma conversa que a caixa de entrada não controla, ou a move para a pasta Principal, a caixa de entrada assume o controle. Um app entrega uma conversa às pessoas com pass_thread_control e target_app_id 263902037430900, e um app que repassa a resposta de uma pessoa depois da janela de 24 horas a envia com a tag HUMAN_AGENT, em até 7 dias após a última mensagem da pessoa.

1AI agentThe app that owns the thread replies to the person
2Hand overpass_thread_control to 263902037430900
3Page inboxPeople answer; a reply there also takes control
4IdleReleased, or 24 hours without a message from the person

O que acontece quando o Business AI da Meta controla uma conversa?

Os outros apps recebem as mensagens da pessoa pelo canal standby e não devem respondê-las. O guia da Meta diz para começar a responder após um evento messaging_handovers com pass_thread_control; uma notificação de messages pode trazer admin_text e um handoff_reason, como human_requested ou purchase_intent, mas não transfere o controle. Com a opção Assumir o controle de conversas com seu Business AI desligada, que é o padrão, um envio sem tag para essa conversa falha com código 10, subcódigo 2018300.

Como um app verifica quem controla uma conversa?

GET /{page-id}/thread_owner com recipient definido como o PSID retorna o app_id do app dono e quando o controle dele expira, para o próprio dono ou para o app padrão da Página. O campo is_owner da Conversations API responde a mesma pergunta por conversa quando o roteamento está ativo, e GET /{page-id}?fields=messaging_feature_status mostra o status do Conversation Routing da Página em campos como msgr_multi_app.

O que acontece sem o Conversation Routing?

A Meta chama isso de comportamento padrão, pensado para uma Página com um app conectado que recebe e responde mensagens sozinho. Todos os apps conectados recebem os webhooks de mensagens e podem responder a mesma mensagem, take_thread_control fica bloqueado até que um app padrão seja definido, e só o roteamento por campanha está disponível. O conselho da Meta para esse cenário é coordenar o app e a caixa de entrada da Página para que ninguém responda a mesma mensagem duas vezes.

O que o easyCoexistence faz em uma caixa de entrada compartilhada?

Ele assina cada Página para feed, messages e mention, e não para messaging_handovers, standby ou message_echoes; assim encaminha as mensagens da pessoa enquanto seu app as recebe, e não vê eventos de transferência nem respostas enviadas pela caixa de entrada da Página. send_social_dm envia uma RESPONSE sem thread_control, e quando a Meta recusa um envio porque outro app controla a conversa, a ferramenta devolve ao seu agente de IA o código 10 e a mensagem da Meta. As chamadas de controle de conversa, thread_owner e is_owner não estão entre as suas ferramentas.

Erros comuns

  • Responder mensagens em standby. Elas chegam a um app que não é dono da conversa; espere o pass_thread_control antes de responder.
  • Tratar admin_text como transferência. Uma notificação de messages com contexto de transferência não transfere o controle; quem faz isso é o evento messaging_handovers.
  • Rodar uma IA e a caixa de entrada lado a lado sem roteamento. No comportamento padrão, ambos recebem a mensagem, e a Meta pede coordenação para evitar duas respostas.
  • Manter uma conversa depois que o fluxo termina. A Meta recomenda liberar o controle assim que o app terminar, em vez de esperar o tempo de resposta expirar.
Fazendo isso com o EasyCoexistence

As chamadas de controle de conversa da Meta não estão entre as suas ferramentas; uma pessoa assume a conversa respondendo na caixa de entrada da Página. De US$ 9 a US$ 0.75 por conexão por mês, com o valor caindo conforme você adiciona conexões, e 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

Dois apps numa mesma Página precisam do Conversation Routing?

A Meta recomenda quando vários apps de mensagens estão conectados e cada um deve responder a certas conversas. Com um só app recebendo e respondendo, o comportamento padrão basta.

Por quanto tempo um app mantém o controle de uma conversa?

Até que ele libere o controle ou a conversa fique inativa, 24 horas após a última mensagem da pessoa. O extend_thread_control adiciona tempo, de até 7 dias.

A resposta feita pela caixa de entrada da Página chega a outros apps?

Os apps inscritos em message_echoes a recebem como um echo cujo app_id é o da caixa de entrada da Página, 263902037430900, como descreve o changelog da Meta para a Graph API v12.0 e versões posteriores.

O que acontece com as respostas do easyCoexistence quando uma pessoa responde pela caixa de entrada?

Com o Conversation Routing ativado, a caixa de entrada assume o controle, e até o controle voltar, as mensagens da pessoa chegam ao app do easyCoexistence só pelo standby, canal que ele não assina. Sem roteamento, os dois continuam recebendo.

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