BR
Tutorial

Enviar mensagem com a API do Facebook Messenger: tutorial em Node.js, Python e PHP

As regras da Send API da Meta em 2026 e, depois, uma única chamada REST para enviar a partir das próprias contas dos seus usuários.

Seu app Ao vivo
FacebookAnna LeePessoal FacebookNorthwind BakeryPágina
Chat pessoal
Tom BeckerDe Anna Lee
Podemos remarcar a demo?
Quinta às 10h fica bom para mim.
Visto
Chat da Página
Maya RossPara Northwind Bakery
Vocês entregam aos domingos?
Sim, das 9h ao meio-dia.
Entregue
GETchats POSTmessages/send POSTchats/send 200 OK
Resposta curta

Há duas formas de enviar uma mensagem do Facebook Messenger via API. A Send API da Meta envia a partir de uma Página do Facebook, com um Page access token, e só para pessoas que mandaram mensagem para a Página nas últimas 24 horas. Uma API unificada como a Unipile envia a partir da conta conectada do seu usuário (uma conta pessoal ou uma Página que ele gerencia) com uma única chamada REST: POST /v2/{account_id}/chats/{chat_id}/messages/send.

POST/{PAGE-ID}/messagesMeta: responder como Página
POST/v2/{account_id}/chats/{chat_id}/messages/sendUnipile: responder em um chat existente
POST/v2/{account_id}/chats/sendUnipile: escrever primeiro
Com a Unipile

Envie uma mensagem do Messenger em três etapas

  1. 1

    Conecte. O seu usuário conecta a conta do Facebook ou a Página pelo Hosted Auth. Sem app da Meta, sem App Review.

  2. 2

    Envie. Chame POST /v2/{account_id}/chats/{chat_id}/messages/send com a sua X-API-KEY e um text.

  3. 3

    Escute. O webhook message.new confirma o envio e traz as respostas.

Escolha um caminho

Duas formas de enviar uma mensagem do Messenger via API

A Send API da Meta age em nome de uma Página que o seu app gerencia. A Unipile age em nome da conta que o seu usuário final conectou.

CritérioSend API da MetaAPI da Unipile
RemetenteUma Página do FacebookA conta pessoal do usuário ou uma Página que ele gerencia
ConfiguraçãoApp da Meta, token de Página com pages_messaging, App Review para atender Páginas de outras empresasChave de API e um account_id do Hosted Auth, sem app da Meta
Quem escreve primeiroSempre a pessoaUma conta pessoal pode; uma Página só responde
Janela24 horas, até 7 dias após um anúncio Click-to-MessengerSem a janela da Send API; o Facebook pode recusar um destinatário
Remetente
Send API da MetaUma Página do Facebook
API da UnipileA conta pessoal do usuário ou uma Página que ele gerencia
Configuração
Send API da MetaApp da Meta, token de Página com pages_messaging, App Review para atender Páginas de outras empresas
API da UnipileChave de API e um account_id do Hosted Auth, sem app da Meta
Quem escreve primeiro
Send API da MetaSempre a pessoa
API da UnipileUma conta pessoal pode; uma Página só responde
Janela
Send API da Meta24 horas, até 7 dias após um anúncio Click-to-Messenger
API da UnipileSem a janela da Send API; o Facebook pode recusar um destinatário

Um bot para a sua própria Página combina com o caminho da Meta; um CRM, helpdesk ou agente de IA nas conversas dos seus clientes precisa de uma conta conectada. Para o mapa completo, veja como as APIs do Facebook se encaixam.

Send API da Meta

Como enviar uma mensagem com a Graph API do Facebook (Send API)

O caminho oficial da Meta é a Send API da Messenger Platform: POST https://graph.facebook.com/v27.0/{PAGE-ID}/messages com um Page access token que tenha pages_messaging, um recipient.id, um messaging_type e um objeto message. Ela só responde pessoas que escreveram para a sua Página.

1

Criar um app da Meta e vincular uma Página

Adicione o Messenger e conecte a Página.

2

Obter um Page access token

Com pages_messaging; App Review para atender outras empresas. Veja o nosso guia sobre o token de acesso da API do Facebook.

3

Enviar a requisição

Identifique a pessoa pelo PSID dela (Page-scoped ID), lido no webhook messages.

Facebook Requisição da Send API
access_tokenPage access token
recipient.idO PSID da pessoa
messaging_typeRESPONSE, UPDATE ou MESSAGE_TAG
message.text"Olá, mundo!"
responserecipient_id, message_id
POST graph.facebook.com/v27.0/{PAGE-ID}/messages 200 OK
  • RESPONSE: uma resposta, dentro da janela.
  • UPDATE: uma mensagem que você inicia, dentro da janela.
  • MESSAGE_TAG: fora da janela, com uma tag e conteúdo não promocional.

De onde vem o PSID

1Entrada

Uma pessoa escreve para a sua Página

Messenger
2POST

A Meta chama o seu webhook

evento messages
3PSID

Ler o ID do remetente

messaging[0].sender.id
4POST

Responder com a Send API

recipient.id = PSID

No evento messages, sender.id é o PSID da pessoa e recipient.id é o ID da sua Página. Copie a requisição nas abas Meta cURL, Node.js, Python e PHP do bloco de código abaixo.

Fontes: documentação Send a Message e evento de webhook messages da Meta. Última verificação: 17 de novembro de 2026.

Regras

A janela de 24 horas do Messenger e as message tags em 2026

A Send API só escreve para pessoas que escreveram para a Página, durante 24 horas após a última mensagem delas, ou até 7 dias após um anúncio Click-to-Messenger. Depois disso, HUMAN_AGENT cobre uma resposta humana em até 7 dias, e três tags de atualização falham com o erro 100 desde 27 de abril de 2026.

Início

A pessoa escreve

Isso abre a janela padrão.

0 a 24 h

Janela aberta

Envie com RESPONSE ou UPDATE.

Até 7 dias

Agente humano

HUMAN_AGENT, para uma resposta escrita por uma pessoa.

Depois

Janela fechada

Aguarde uma nova mensagem.

Retiradas em 27 de abril de 2026

As requisições com as tags CONFIRMED_EVENT_UPDATE, ACCOUNT_UPDATE ou POST_PURCHASE_UPDATE agora falham com o código de erro 100.

Fontes da Meta: referência da Send API e Send a Message. Última verificação: novembro de 2026.

Tutorial

Enviar uma mensagem do Facebook Messenger a partir de uma conta conectada (Node.js, Python, PHP, cURL)

O seu usuário conecta a conta do Facebook uma única vez e você recebe um account_id. Liste os chats dele e envie em um chat_id. As requisições vão para https://api.unipile.com com a sua chave no cabeçalho X-API-KEY, pela API do Facebook Messenger da Unipile. As abas Meta enviam a mesma resposta com a Send API da Meta, a partir de uma Página que você gerencia.

1

Conectar a conta

O usuário faz login em uma página do Hosted Auth. Detalhes no nosso guia da API do Messenger para contas pessoais.

2

Listar os chats

GET /v2/{account_id}/chats retorna até 100 chats por página.

3

Enviar a mensagem

Um POST com um campo text.

# 1. List chats
curl --request GET \
     --url 'https://api.unipile.com/v2/acc_123456789/chats?limit=20' \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json'

# 2. Send a message
curl --request POST \
     --url https://api.unipile.com/v2/acc_123456789/chats/CHAT_ID/messages/send \
     --header 'X-API-KEY: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{ "text": "Thanks, your order ships today." }'
// npm i @unipile/sdk
import { UnipileMessaging } from '@unipile/sdk';

const request_options = {
  baseUrl: 'https://api.unipile.com',
  headers: { 'X-API-KEY': 'YOUR_API_KEY' },
  throwOnError: true,
};
const messagingApi = new UnipileMessaging();

// 1. List chats
const chats = await messagingApi.getChatsList({
  ...request_options,
  path: { account_id: 'acc_123456789' },
  query: { limit: 20 },
});

// 2. Send a message
await messagingApi.sendMessage({
  ...request_options,
  path: { account_id: 'acc_123456789', chat_id: 'CHAT_ID' },
  body: { text: 'Thanks, your order ships today.' },
});
import unipile

configuration = unipile.Configuration()
configuration.api_key["apiKey"] = "YOUR_API_KEY"
api_client = unipile.ApiClient(configuration)
messaging_api = unipile.MessagingApi(api_client)

# 1. List chats
chats = messaging_api.get_chats_list("acc_123456789", limit=20)

# 2. Send a message
messaging_api.send_message(
    "CHAT_ID",
    "acc_123456789",
    {"text": "Thanks, your order ships today."},
)
<?php
$base = 'https://api.unipile.com/v2/acc_123456789';
$headers = ['X-API-KEY: YOUR_API_KEY', 'accept: application/json'];

// 1. List chats
$ch = curl_init("$base/chats?limit=20");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);
$chats = json_decode(curl_exec($ch), true);
curl_close($ch);

// 2. Send a message
$ch = curl_init("$base/chats/CHAT_ID/messages/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => array_merge($headers, ['content-type: application/json']),
    CURLOPT_POSTFIELDS => json_encode(['text' => 'Thanks, your order ships today.']),
    CURLOPT_RETURNTRANSFER => true,
]);
$sent = json_decode(curl_exec($ch), true);
curl_close($ch);
# Meta Send API: reply to a person who messaged your Page
curl -X POST \
     "https://graph.facebook.com/v27.0/PAGE_ID/messages?access_token=PAGE_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "recipient": { "id": "PSID" },
       "messaging_type": "RESPONSE",
       "message": { "text": "Thanks, your order ships today." }
     }'
// Node.js 18+: built-in fetch, no SDK
const url = 'https://graph.facebook.com/v27.0/PAGE_ID/messages'
  + '?access_token=' + process.env.PAGE_ACCESS_TOKEN;

const res = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recipient: { id: 'PSID' },
    messaging_type: 'RESPONSE',
    message: { text: 'Thanks, your order ships today.' },
  }),
});
const data = await res.json(); // { recipient_id, message_id }
# pip install requests
import requests

resp = requests.post(
    "https://graph.facebook.com/v27.0/PAGE_ID/messages",
    params={"access_token": "PAGE_ACCESS_TOKEN"},
    json={
        "recipient": {"id": "PSID"},
        "messaging_type": "RESPONSE",
        "message": {"text": "Thanks, your order ships today."},
    },
)
print(resp.json())  # {"recipient_id": "...", "message_id": "..."}
<?php
$url = 'https://graph.facebook.com/v27.0/PAGE_ID/messages?access_token=PAGE_ACCESS_TOKEN';
$payload = [
    'recipient' => ['id' => 'PSID'],
    'messaging_type' => 'RESPONSE',
    'message' => ['text' => 'Thanks, your order ships today.'],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
]);
$sent = json_decode(curl_exec($ch), true); // recipient_id, message_id
curl_close($ch);
200 OK · { "object": "MessageSent", "message_id": "..." }
200 OK · { "recipient_id": "PAGE-SCOPED-ID", "message_id": "AG5Hz2U..." }

As quatro primeiras abas chamam a Unipile para uma conta conectada; a mesma requisição funciona para LinkedIn, WhatsApp, Instagram e Telegram. As abas Meta chamam a Send API da Meta para a sua própria Página, com um Page access token e o PSID da pessoa (como obter o PSID). Referências: Unipile Facebook, Send messages e Meta Send a Message (v27.0, verificado em 17 de novembro de 2026).

Primeira mensagem

Como iniciar uma nova conversa no Messenger por API

Quando ainda não existe um chat, chame POST /v2/{account_id}/chats/send com o ID da pessoa em users_ids e o seu text. A Send API da Meta não faz isso.

URL base https://api.unipile.com
POST/v2/{account_id}/chats/sendStart a Chat
users_idsID de uma pessoa ou de uma Página
text"Oi Tom, uma pergunta rápida"
attachmentsArquivos opcionais
SDK: startChat (Node.js), start_chat (Python) 200 OK

A resposta traz o novo chat_id e o message_id.

Se o Facebook não permitir que a conta envie mensagem a essa pessoa, a requisição falha com provider/access_restricted.

Limitações da caixa de entrada da Página

Uma Página não pode iniciar uma conversa (501 api/not_implemented) nem excluir as próprias mensagens.

Páginas

Como responder como Página do Facebook por API

Uma Página que o usuário gerencia responde pelo mesmo account_id: liste as caixas de entrada, abra a caixa da Página e envie com um chat ID da Página. Como as Páginas e os tokens delas funcionam do lado da Meta é explicado no nosso guia da API de Páginas do Facebook.

Facebook Caixa pessoal · INBOX
Tom BeckerQuinta às 10h fica bom para mim.Pessoal
chat_id: {chat_id}
Facebook Caixa da Página · PAGE_<page_id>_INBOX
Maya RossVocês entregam aos domingos?Página
chat_id: PAGE_<page_id>_<thread_key>
GET/v2/{account_id}/inboxesLista as caixas de entrada das Páginas
GET/v2/{account_id}/inboxes/{inbox_id}/chatsLista os chats da Página
POST/v2/{account_id}/chats/PAGE_1357020157484056_100001234567890/messages/sendResponde como a Página

A lista geral de chats só retorna os chats pessoais. O prefixo PAGE_ faz a Unipile agir como a Página. Detalhes na documentação Facebook Pages.

Anexos

Enviar imagens e arquivos em um chat do Messenger

Adicione um array attachments ao mesmo endpoint de envio. Para arquivos grandes, use multipart.

POST/v2/{account_id}/chats/{chat_id}/messages/sendSend a Message
textLegenda opcional, pode ser ""
contentO arquivo codificado em base64
content_type"image/png"
filename"image.png"
Arquivo grande: multipart/form-data 200 OK

Chats criptografados. Nos chats pessoais com criptografia de ponta a ponta, cada arquivo é enviado como uma mensagem separada.

Equivalente na Meta. A Send API recebe um objeto attachment com um type e uma url, com até 30 imagens por envio.

Tempo real

Confirmar a entrega e receber respostas com webhooks

Um 200 significa que o Facebook aceitou a mensagem, não que ela foi entregue. A entrega é confirmada pelo evento de webhook message.new, que também traz as respostas.

1POST

O seu app envia

messages/send
2Aceita

A Unipile responde

200 MessageSent
3Confirmada

Webhook: enviada

message.new
4Confirmações

Entregue e depois lida

message.receipt.delivery message.receipt.read
Facebook Evento message.new
type"message.new"
account_idA conta conectada
payloadUm objeto Message: id, chat_id, sender_id, text, timestamp, is_sender

Ele é disparado para mensagens enviadas e recebidas; veja is_sender.

Encaminhe os eventos de Página pelo prefixo PAGE_<page_id>_ do chat_id, que pode ser diferente do retornado pela API. Configuração em Configure a webhook.

Do lado da Meta, um bot de Página construído sobre a Send API precisa do próprio webhook do Messenger. É também nele que você lê o PSID antes de responder.

Fonte: webhooks do Messenger da Meta. Última verificação: 17 de novembro de 2026.

Facebook Webhook do Messenger da Meta
VerificaçãoGET com hub.mode=subscribe e o seu hub.verify_token: retorne hub.challenge
AssinaturaX-Hub-Signature-256: SHA256 do payload com o seu App Secret
Camposmessages, message_deliveries
Resposta200 OK em até 5 segundos
Erros

Erros ao enviar mensagens do Messenger

A maioria dos erros de envio vem de uma regra: uma nova tentativa falha de novo. Um token sem pages_messaging bloqueia todas as chamadas da Send API.

ErroSignificadoSolução
Meta 100Parâmetro inválido ou tag retirada em 27 de abril de 2026Verifique o PSID e remova a tag
Meta 10 / 2018278Mensagem enviada fora da janela permitidaAguarde uma nova mensagem ou envie uma resposta HUMAN_AGENT
Meta 200 / 2018028Não é possível enviar mensagens para quem não é admin, desenvolvedor ou testador do app: pages_messaging ainda não aprovadoConclua o App Review e, enquanto isso, teste com as funções do app
Meta 551Esta pessoa não está recebendo mensagens suas no momentoNão tente de novo
Meta 613Rate limit excedidoEnvie com menos frequência
Unipile provider/access_restrictedO Facebook recusa esse destinatário para a contaNão tente de novo
Unipile 403 api/insufficient_permissionsPágina não ativada na contaAtive-a na reconexão
Unipile 501 api/not_implementedUma Página iniciou um chat ou excluiu uma mensagemResponda em um chat existente
Meta 100
SignificadoParâmetro inválido ou tag retirada em 27 de abril de 2026
SoluçãoVerifique o PSID e remova a tag
Meta 10 / 2018278
SignificadoMensagem enviada fora da janela permitida
SoluçãoAguarde uma nova mensagem ou envie uma resposta HUMAN_AGENT
Meta 200 / 2018028
SignificadoNão é possível enviar mensagens para quem não é admin, desenvolvedor ou testador do app: pages_messaging ainda não aprovado
SoluçãoConclua o App Review e, enquanto isso, teste com as funções do app
Meta 551
SignificadoEsta pessoa não está recebendo mensagens suas no momento
SoluçãoNão tente de novo
Meta 613
SignificadoRate limit excedido
SoluçãoEnvie com menos frequência
Unipile provider/access_restricted
SignificadoO Facebook recusa esse destinatário para a conta
SoluçãoNão tente de novo
Unipile 403 api/insufficient_permissions
SignificadoPágina não ativada na conta
SoluçãoAtive-a na reconexão
Unipile 501 api/not_implemented
SignificadoUma Página iniciou um chat ou excluiu uma mensagem
SoluçãoResponda em um chat existente

Fontes: códigos de erro do Messenger da Meta e respostas de erro da Unipile. Última verificação: 17 de novembro de 2026.

Conformidade

Cada usuário envia a partir da própria conta

A Unipile é uma empresa independente, não é um app oficial da Meta nem um Meta Partner. Ela age em nome de usuários autenticados, que continuam sujeitos aos termos da Meta. Use-a para atendimento ao cliente, CRM e conversas diretas.

Envie a sua primeira mensagem

A Send API da Meta serve para um bot na sua própria Página. Para enviar mensagens com a API do Facebook Messenger a partir das próprias contas dos seus usuários, conecte essas contas pela Unipile.

Comissão Europeia
Regulamentado pela UE Digital Markets Act (DMA)

Cada usuário conecta a própria conta, sem armazenamento de perfis. A Unipile não é Meta Partner. A nossa abordagem do Digital Markets Act

Todos os endpoints da API do Facebook em um só lugar

As mensagens são só uma parte. Veja todos os endpoints do Facebook disponíveis com a Unipile, de posts e comentários a perfis e webhooks, ou leia o guia completo da API do Facebook.

Perguntas frequentes sobre enviar mensagens com a API do Facebook Messenger

Respostas rápidas sobre o envio de mensagens do Messenger por API.

Não. A Send API só alcança pessoas que mandaram mensagem para a sua Página, dentro da janela de mensagens, e uma Página nunca escreve primeiro. Uma nova conversa precisa começar a partir de uma conta pessoal conectada, por exemplo com o POST /v2/{account_id}/chats/send da Unipile.

A Meta não lista nenhum SDK oficial em Python para a Send API: faça um POST em /{PAGE-ID}/messages com requests, como na aba Meta Python acima. A Unipile oferece um SDK em Python, importado como unipile, com get_chats_list e send_message.

Envie um POST HTTP com cURL ou Guzzle: para /{PAGE-ID}/messages na Graph API com um Page access token (aba Meta PHP), ou para /v2/{account_id}/chats/{chat_id}/messages/send na Unipile com a sua X-API-KEY (aba PHP).

Instale @unipile/sdk e chame sendMessage com account_id, chat_id e text, como na aba Node.js acima. Para a Send API da Meta, faça um POST em /{PAGE-ID}/messages com fetch, como na aba Meta Node.js.

Com a Send API: uma janela fechada (erro 10, subcódigo 2018278), uma tag retirada em 27 de abril de 2026 (erro 100), um token sem pages_messaging aprovado (erro 200, subcódigo 2018028) ou uma pessoa que bloqueia as suas mensagens (erro 551). Com a Unipile: provider/access_restricted quando o Facebook recusa o destinatário, ou uma Página tentando iniciar uma conversa.

Para um bot de Página na plataforma da Meta, o seu endpoint responde à verificação GET retornando hub.challenge, confere a assinatura X-Hub-Signature-256 com o seu App Secret e se inscreve em messages; o sender.id de cada evento é o PSID ao qual você responde. Com a Unipile, você registra uma única URL e recebe eventos message.new para todas as contas conectadas.

Não. A Unipile é uma empresa independente: ela não é um Meta Partner e não é endossada, patrocinada nem aprovada pela Meta. As abas Meta desta página chamam a Send API pública da própria Meta; as outras abas chamam a API da Unipile. Facebook e Messenger são marcas registradas da Meta Platforms, Inc.

Não. O app da Meta, o token de Página e o App Review pertencem apenas ao caminho da Send API. Com a Unipile, os seus usuários conectam a própria conta do Facebook, ou as Páginas que gerenciam, pela autenticação hospedada, e você envia com um account_id e a sua chave de API.

A Unipile foi projetada no espírito do Digital Markets Act: cada usuário conecta a própria conta e as mensagens saem em nome dele, nas próprias conversas, sem que a Unipile armazene perfis de usuários. Detalhes na nossa página sobre o Digital Markets Act.

Sim. Cada conta conectada continua sujeita aos Termos de Serviço da Meta. Envie mensagens para necessidades legítimas, como respostas de suporte, acompanhamentos de CRM e conversas que as pessoas esperam; mensagens em massa não solicitadas e spam podem levar à restrição da conta.

Ainda tem dúvidas? Nossa equipe está aqui para ajudar.

Fale com um especialista