ES
Tutorial

Enviar un mensaje con la API de Facebook Messenger: tutorial en Node.js, Python y PHP

Las reglas de la Send API de Meta en 2026 y, después, una sola llamada REST para enviar desde las propias cuentas de sus usuarios.

Su app En vivo
FacebookAnna LeePersonal FacebookNorthwind BakeryPágina
Chat personal
Tom BeckerDe Anna Lee
¿Podemos cambiar la demo?
El jueves a las 10 h me va bien.
Visto
Chat de Página
Maya RossA Northwind Bakery
¿Hacen entregas los domingos?
Sí, de 9 a 12 h.
Entregado
GETchats POSTmessages/send POSTchats/send 200 OK
Respuesta corta

Hay dos formas de enviar un mensaje de Facebook Messenger por API. La Send API de Meta envía desde una Página de Facebook, con un Page access token, y solo a las personas que escribieron a la Página en las últimas 24 horas. Una API unificada como Unipile envía desde la cuenta conectada de su usuario (una cuenta personal o una Página que gestiona) con una sola llamada 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 en un chat existente
POST/v2/{account_id}/chats/sendUnipile: escribir primero
Con Unipile

Envíe un mensaje de Messenger en tres pasos

  1. 1

    Conectar. Su usuario vincula su cuenta o su Página de Facebook mediante Hosted Auth. Sin app de Meta ni App Review.

  2. 2

    Enviar. Llame a POST /v2/{account_id}/chats/{chat_id}/messages/send con su X-API-KEY y un text.

  3. 3

    Escuchar. El webhook message.new confirma el envío y trae las respuestas.

Elegir una vía

Dos formas de enviar un mensaje de Messenger por API

La Send API de Meta actúa en nombre de una Página que gestiona su app. Unipile actúa en nombre de la cuenta que conectó su usuario final.

CriterioMeta Send APIUnipile API
RemitenteUna Página de FacebookLa cuenta personal del usuario o una Página que gestiona
ConfiguraciónApp de Meta, token de Página con pages_messaging, App Review para dar servicio a las Páginas de otras empresasAPI key y un account_id obtenido con Hosted Auth, sin app de Meta
Quién escribe primeroSiempre la personaUna cuenta personal puede; una Página solo responde
Ventana24 horas, hasta 7 días tras un anuncio Click-to-MessengerSin ventana de la Send API; Facebook puede rechazar a un destinatario
Remitente
Meta Send APIUna Página de Facebook
Unipile APILa cuenta personal del usuario o una Página que gestiona
Configuración
Meta Send APIApp de Meta, token de Página con pages_messaging, App Review para dar servicio a las Páginas de otras empresas
Unipile APIAPI key y un account_id obtenido con Hosted Auth, sin app de Meta
Quién escribe primero
Meta Send APISiempre la persona
Unipile APIUna cuenta personal puede; una Página solo responde
Ventana
Meta Send API24 horas, hasta 7 días tras un anuncio Click-to-Messenger
Unipile APISin ventana de la Send API; Facebook puede rechazar a un destinatario

Un bot para su propia Página encaja con la vía de Meta; un CRM, un helpdesk o un agente de IA en las conversaciones de sus clientes necesita una cuenta conectada. Para el mapa completo, consulte cómo encajan las API de Facebook.

Meta Send API

Cómo enviar un mensaje con la Graph API de Facebook (Send API)

La vía oficial de Meta es la Send API de la Messenger Platform: POST https://graph.facebook.com/v27.0/{PAGE-ID}/messages con un Page access token que tenga pages_messaging, un recipient.id, un messaging_type y un objeto message. Solo responde a las personas que escribieron a su Página.

1

Crear una app de Meta y vincular una Página

Añada Messenger y conecte la Página.

2

Obtener un Page access token

Con pages_messaging; App Review para dar servicio a otras empresas. Consulte nuestra guía sobre el token de acceso de la API de Facebook.

3

Enviar la petición

Diríjase a la persona por su PSID (ID con ámbito de Página), que se lee en el webhook messages.

Facebook Petición a la Send API
access_tokenPage access token
recipient.idEl PSID de la persona
messaging_typeRESPONSE, UPDATE o MESSAGE_TAG
message.text"¡Hola, mundo!"
responserecipient_id, message_id
POST graph.facebook.com/v27.0/{PAGE-ID}/messages 200 OK
  • RESPONSE: una respuesta, dentro de la ventana.
  • UPDATE: un mensaje que usted inicia, dentro de la ventana.
  • MESSAGE_TAG: fuera de la ventana, con un tag y contenido no promocional.

De dónde sale el PSID

1Entrante

Una persona escribe a su Página

Messenger
2POST

Meta llama a su webhook

evento messages
3PSID

Lea el ID del remitente

messaging[0].sender.id
4POST

Responda con la Send API

recipient.id = PSID

En el evento messages, sender.id es el PSID de la persona y recipient.id es el ID de su Página. Copie la petición de las pestañas Meta cURL, Node.js, Python y PHP del bloque de código de abajo.

Fuentes: documentación Send a Message y evento de webhook messages de Meta. Última verificación: 17 de noviembre de 2026.

Reglas

La ventana de 24 horas de Messenger y los message tags en 2026

La Send API solo escribe a las personas que escribieron a la Página, durante las 24 horas siguientes a su último mensaje, o hasta 7 días después de un anuncio Click-to-Messenger. Pasado ese plazo, HUMAN_AGENT cubre una respuesta humana en un plazo de 7 días, y tres tags de actualización fallan con el error 100 desde el 27 de abril de 2026.

Inicio

La persona escribe

Se abre la ventana estándar.

De 0 a 24 h

Ventana abierta

Envíe con RESPONSE o UPDATE.

Hasta 7 días

Agente humano

Tag HUMAN_AGENT , para una respuesta escrita por una persona.

Después

Ventana cerrada

Espere un nuevo mensaje.

Retirados el 27 de abril de 2026

Las peticiones con los tags CONFIRMED_EVENT_UPDATE, ACCOUNT_UPDATE o POST_PURCHASE_UPDATE fallan ahora con el código de error 100.

Fuentes: de Meta, referencia de la Send API y Send a Message. Última verificación: noviembre de 2026.

Tutorial

Enviar un mensaje de Facebook Messenger desde una cuenta conectada (Node.js, Python, PHP, cURL)

Su usuario conecta su cuenta de Facebook una sola vez y usted obtiene un account_id. Liste sus chats y envíe después en un chat_id. Las peticiones van a https://api.unipile.com con su clave en la cabecera X-API-KEY, a través de la API de Facebook Messenger de Unipile. Las pestañas de Meta envían la misma respuesta con la Send API de Meta, desde una Página que usted gestiona.

1

Conectar la cuenta

El usuario inicia sesión en una página de Hosted Auth. Detalles en nuestra guía de la API de Messenger para cuentas personales.

2

Listar los chats

GET /v2/{account_id}/chats devuelve hasta 100 chats por página.

3

Enviar el mensaje

Un POST con un 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..." }

Las cuatro primeras pestañas llaman a Unipile para una cuenta conectada; la misma petición funciona para LinkedIn, WhatsApp, Instagram y Telegram. Las pestañas Meta llaman a la Send API de Meta para su propia Página, con un Page access token y el PSID de la persona (cómo obtener el PSID). Referencias: Unipile Facebook, Send messages y Meta Send a Message (v27.0, verificado el 17 de noviembre de 2026).

Primer mensaje

Cómo iniciar una conversación nueva de Messenger por API

Cuando aún no existe ningún chat, llame a POST /v2/{account_id}/chats/send con el ID de la persona en users_ids y su text. La Send API de Meta no puede hacerlo.

URL base https://api.unipile.com
POST/v2/{account_id}/chats/sendStart a Chat
users_idsID de una persona o una Página
text"Hola Tom, una pregunta rápida"
attachmentsArchivos opcionales
SDK: startChat (Node.js), start_chat (Python) 200 OK

La respuesta devuelve el nuevo chat_id y el message_id.

Si Facebook no permite a la cuenta escribir a esta persona, la petición falla con provider/access_restricted.

Limitaciones de la bandeja de Página

Una Página no puede iniciar una conversación (501 api/not_implemented) ni eliminar sus mensajes.

Páginas

Cómo responder como Página de Facebook por API

Una Página que gestiona el usuario responde con el mismo account_id: liste las bandejas, abra la bandeja de la Página y envíe con un ID de chat de Página. Cómo funcionan las Páginas y sus tokens del lado de Meta se explica en nuestra guía de la API de Páginas de Facebook.

Facebook Bandeja personal · INBOX
Tom BeckerEl jueves a las 10 h me va bien.Personal
chat_id: {chat_id}
Facebook Bandeja de Página · PAGE_<page_id>_INBOX
Maya Ross¿Hacen entregas los domingos?Página
chat_id: PAGE_<page_id>_<thread_key>
GET/v2/{account_id}/inboxesLista las bandejas de Página
GET/v2/{account_id}/inboxes/{inbox_id}/chatsLista los chats de la Página
POST/v2/{account_id}/chats/PAGE_1357020157484056_100001234567890/messages/sendResponde como la Página

La lista general de chats solo devuelve los chats personales. El prefijo PAGE_ hace que Unipile actúe como la Página. Detalles en la documentación de Facebook Pages.

Adjuntos

Enviar imágenes y archivos en un chat de Messenger

Añada un array attachments al mismo endpoint de envío. Para los archivos grandes, use multipart.

POST/v2/{account_id}/chats/{chat_id}/messages/sendSend a Message
textTexto opcional, puede ser ""
contentEl archivo codificado en base64
content_type"image/png"
filename"image.png"
Archivo grande: multipart/form-data 200 OK

Chats cifrados. En los chats personales con cifrado de extremo a extremo, cada archivo se envía como un mensaje independiente.

Equivalente en Meta. La Send API acepta un objeto attachment con un type y una url, hasta 30 imágenes por envío.

Tiempo real

Confirmar la entrega y recibir respuestas con webhooks

Un 200 significa que Facebook aceptó el mensaje, no que se haya entregado. La entrega se confirma con el evento de webhook message.new, que también trae las respuestas.

1POST

Su app envía

messages/send
2Aceptado

Unipile responde

200 MessageSent
3Confirmado

Webhook: enviado

message.new
4Acuses

Entregado y después leído

message.receipt.delivery message.receipt.read
Facebook Evento message.new
type"message.new"
account_idLa cuenta conectada
payloadUn objeto Message: id, chat_id, sender_id, text, timestamp, is_sender

Se activa con los mensajes enviados y recibidos; consulte is_sender.

Enrute los eventos de Página según el prefijo PAGE_<page_id>_ de su chat_id, que puede diferir del de la API. Configuración en Configure a webhook.

Del lado de Meta, un bot de Página creado con la Send API necesita su propio webhook de Messenger. Es también donde se lee el PSID antes de responder.

Fuente: webhooks de Messenger de Meta. Última verificación: 17 de noviembre de 2026.

Facebook Webhook de Messenger de Meta
VerificaciónGET con hub.mode=subscribe y su hub.verify_token: devuelva hub.challenge
FirmaX-Hub-Signature-256: SHA256 del payload con su App Secret
Camposmessages, message_deliveries
Respuesta200 OK en menos de 5 segundos
Errores

Errores al enviar mensajes de Messenger

La mayoría de los errores de envío se deben a una regla: un reintento vuelve a fallar. Un token sin pages_messaging bloquea todas las llamadas a la Send API.

ErrorSignificadoSolución
Meta 100Parámetro no válido, o un tag retirado el 27 de abril de 2026Compruebe el PSID y quite el tag
Meta 10 / 2018278Mensaje enviado fuera de la ventana permitidaEspere un nuevo mensaje o envíe una respuesta HUMAN_AGENT
Meta 200 / 2018028No se puede escribir a personas que no son administradores, desarrolladores ni testers de la app: pages_messaging aún no aprobadoTermine el App Review y pruebe mientras tanto con los roles de la app
Meta 551Esta persona no está recibiendo sus mensajes en este momentoNo reintente
Meta 613Rate limit superadoEnvíe con menos frecuencia
Unipile provider/access_restrictedFacebook rechaza a este destinatario para la cuentaNo reintente
Unipile 403 api/insufficient_permissionsPágina no activada en la cuentaActívela al reconectar
Unipile 501 api/not_implementedUna Página inició un chat o eliminó un mensajeResponda en un chat existente
Meta 100
SignificadoParámetro no válido, o un tag retirado el 27 de abril de 2026
SoluciónCompruebe el PSID y quite el tag
Meta 10 / 2018278
SignificadoMensaje enviado fuera de la ventana permitida
SoluciónEspere un nuevo mensaje o envíe una respuesta HUMAN_AGENT
Meta 200 / 2018028
SignificadoNo se puede escribir a personas que no son administradores, desarrolladores ni testers de la app: pages_messaging aún no aprobado
SoluciónTermine el App Review y pruebe mientras tanto con los roles de la app
Meta 551
SignificadoEsta persona no está recibiendo sus mensajes en este momento
SoluciónNo reintente
Meta 613
SignificadoRate limit superado
SoluciónEnvíe con menos frecuencia
Unipile provider/access_restricted
SignificadoFacebook rechaza a este destinatario para la cuenta
SoluciónNo reintente
Unipile 403 api/insufficient_permissions
SignificadoPágina no activada en la cuenta
SoluciónActívela al reconectar
Unipile 501 api/not_implemented
SignificadoUna Página inició un chat o eliminó un mensaje
SoluciónResponda en un chat existente

Fuentes: códigos de error de Messenger de Meta y respuestas de error de Unipile. Última verificación: 17 de noviembre de 2026.

Cumplimiento

Cada usuario envía desde su propia cuenta

Unipile es una empresa independiente, no una app oficial de Meta ni un Meta Partner. Actúa en nombre de usuarios autenticados, que siguen sujetos a las condiciones de Meta. Úsela para atención al cliente, CRM y conversaciones directas.

Envíe su primer mensaje

La Send API de Meta es adecuada para un bot en su propia Página. Para enviar mensajes con la API de Facebook Messenger desde las propias cuentas de sus usuarios, conéctelas a través de Unipile.

Comisión Europea
Regulado por la UE Digital Markets Act (DMA)

Cada usuario conecta su propia cuenta, sin almacenamiento de perfiles. Unipile no es Meta Partner. Nuestro enfoque de la Digital Markets Act

Todos los endpoints de la API de Facebook en un solo lugar

Los mensajes son solo una parte. Consulte todos los endpoints de Facebook disponibles con Unipile, de las publicaciones y los comentarios a los perfiles y los webhooks, o lea la guía completa de la API de Facebook.

Preguntas frecuentes sobre el envío de mensajes con la API de Facebook Messenger

Respuestas rápidas sobre el envío de mensajes de Messenger por API.

No. La Send API solo llega a las personas que escribieron a su Página, dentro de la ventana de mensajería, y una Página nunca escribe primero. Una conversación nueva tiene que empezar desde una cuenta personal conectada, por ejemplo con POST /v2/{account_id}/chats/send de Unipile.

Meta no ofrece ningún SDK oficial de Python para la Send API: haga un POST a /{PAGE-ID}/messages con requests, como en la pestaña Meta Python de arriba. Unipile proporciona un SDK de Python, que se importa como unipile, con get_chats_list y send_message.

Envíe un POST HTTP con cURL o Guzzle: a /{PAGE-ID}/messages en la Graph API con un Page access token (pestaña Meta PHP), o a /v2/{account_id}/chats/{chat_id}/messages/send en Unipile con su X-API-KEY (pestaña PHP).

Instale @unipile/sdk y llame a sendMessage con el account_id, el chat_id y el text, como en la pestaña Node.js de arriba. Para la Send API de Meta, haga un POST a /{PAGE-ID}/messages con fetch, como en la pestaña Meta Node.js.

Con la Send API: una ventana cerrada (error 10, subcódigo 2018278), un tag retirado el 27 de abril de 2026 (error 100), un token sin pages_messaging aprobado (error 200, subcódigo 2018028) o una persona que bloquea sus mensajes (error 551). Con Unipile: provider/access_restricted cuando Facebook rechaza al destinatario, o una Página que intenta iniciar una conversación.

Para un bot de Página en la plataforma de Meta, su endpoint responde a la verificación GET devolviendo hub.challenge, comprueba la firma X-Hub-Signature-256 con su App Secret y se suscribe a messages; el sender.id de cada evento es el PSID al que responde. Con Unipile, registra una sola URL y recibe los eventos message.new de todas las cuentas conectadas.

No. Unipile es una empresa independiente: no es un Meta Partner y no cuenta con el respaldo, el patrocinio ni la aprobación de Meta. Las pestañas Meta de esta página llaman a la Send API pública de Meta; las demás pestañas llaman a la API de Unipile. Facebook y Messenger son marcas comerciales de Meta Platforms, Inc.

No. La app de Meta, el token de Página y el App Review solo corresponden a la vía de la Send API. Con Unipile, sus usuarios conectan su propia cuenta de Facebook, o las Páginas que gestionan, mediante la autenticación alojada, y usted envía con un account_id y su clave de API.

Unipile se ha diseñado en el espíritu de la Digital Markets Act (Ley de Mercados Digitales): cada usuario conecta su propia cuenta y los mensajes salen en su nombre, en sus propias conversaciones, sin que Unipile almacene perfiles de usuario. Más detalles en nuestra página sobre la Digital Markets Act.

Sí. Cada cuenta conectada sigue sujeta a las Condiciones de servicio de Meta. Envíe mensajes para necesidades legítimas como respuestas de soporte, seguimientos de CRM y conversaciones que las personas esperan; los envíos masivos no solicitados y el spam pueden provocar la restricción de la cuenta.

¿Aún tiene preguntas? Nuestro equipo está aquí para ayudarle.

Hable con un experto