
Guias de integração
Guia da API do LinkedIn
Guia da API de e-mail
Guia da API do WhatsApp
Fale com vendas
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.
chats
POSTmessages/send
POSTchats/send
200 OK
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.
Envie uma mensagem do Messenger em três etapas
Conecte. O seu usuário conecta a conta do Facebook ou a Página pelo Hosted Auth. Sem app da Meta, sem App Review.
Envie. Chame POST /v2/{account_id}/chats/{chat_id}/messages/send com a sua X-API-KEY e um text.
Escute. O webhook message.new confirma o envio e traz as respostas.
Código em quatro linguagens: enviar a partir de uma conta conectada. Referência: documentação Send messages da Unipile V2.
Comece agoraA 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ério | Send API da Meta | API da Unipile |
|---|---|---|
| Remetente | Uma Página do Facebook | A conta pessoal do usuário ou uma Página que ele gerencia |
| Configuração | App da Meta, token de Página com pages_messaging, App Review para atender Páginas de outras empresas | Chave de API e um account_id do Hosted Auth, sem app da Meta |
| Quem escreve primeiro | Sempre a pessoa | Uma conta pessoal pode; uma Página só responde |
| Janela | 24 horas, até 7 dias após um anúncio Click-to-Messenger | Sem a janela da Send API; o Facebook pode recusar um destinatário |
pages_messaging, App Review para atender Páginas de outras empresasaccount_id do Hosted Auth, sem app da MetaUm 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.
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.
Adicione o Messenger e conecte a Página.
Com pages_messaging; App Review para atender outras empresas. Veja o nosso guia sobre o token de acesso da API do Facebook.
Identifique a pessoa pelo PSID dela (Page-scoped ID), lido no webhook messages.
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
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.
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.
Isso abre a janela padrão.
Envie com RESPONSE ou UPDATE.
HUMAN_AGENT, para uma resposta escrita por uma pessoa.
Aguarde uma nova mensagem.
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.
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.
O usuário faz login em uma página do Hosted Auth. Detalhes no nosso guia da API do Messenger para contas pessoais.
GET /v2/{account_id}/chats retorna até 100 chats por página.
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);
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).
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.
https://api.unipile.comSDK: 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.
Uma Página não pode iniciar uma conversa (501 api/not_implemented) nem excluir as próprias mensagens.
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.
{chat_id}PAGE_<page_id>_<thread_key>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.
Adicione um array attachments ao mesmo endpoint de envio. Para arquivos grandes, use multipart.
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.
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.
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.
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.
| Erro | Significado | Solução |
|---|---|---|
| Meta 100 | Parâmetro inválido ou tag retirada em 27 de abril de 2026 | Verifique o PSID e remova a tag |
| Meta 10 / 2018278 | Mensagem enviada fora da janela permitida | Aguarde uma nova mensagem ou envie uma resposta HUMAN_AGENT |
| Meta 200 / 2018028 | Não é possível enviar mensagens para quem não é admin, desenvolvedor ou testador do app: pages_messaging ainda não aprovado | Conclua o App Review e, enquanto isso, teste com as funções do app |
| Meta 551 | Esta pessoa não está recebendo mensagens suas no momento | Não tente de novo |
| Meta 613 | Rate limit excedido | Envie com menos frequência |
Unipile provider/access_restricted | O Facebook recusa esse destinatário para a conta | Não tente de novo |
Unipile 403 api/insufficient_permissions | Página não ativada na conta | Ative-a na reconexão |
Unipile 501 api/not_implemented | Uma Página iniciou um chat ou excluiu uma mensagem | Responda em um chat existente |
HUMAN_AGENTpages_messaging ainda não aprovadoFontes: códigos de erro do Messenger da Meta e respostas de erro da Unipile. Última verificação: 17 de novembro de 2026.
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.
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.
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