Plataforma de Messenger

Referencia de la API de envío

La API de envío es la principal API que se usa para enviar mensajes a los usuarios e incluye texto, archivos adjuntos, plantillas, acciones del remitente y mucho más.

Creación

Crea y envía mensajes a tus clientes o a las personas con interés en tu página de Facebook.

Antes de empezar

Necesitarás lo siguiente:

  • Un token de acceso a la página que deberá solicitar la persona que puede realizar la tarea MESSAGE en la página.
  • El permiso pages_messaging.
  • El destinatario del mensaje debe haber enviado un mensaje a tu página en las últimas 24 horas o haber aceptado recibir mensajes de ella fuera del intervalo de 24 horas admitido.

Limitaciones

  • No se pueden usar etiquetas de mensaje para enviar contenido promocional.

Ten en cuenta que la API de envío no incluye recipient_id en la respuesta de los mensajes que se envían con recipient.user_ref o recipient.phone_number para identificar al destinatario del mensaje.

Solicitud de ejemplo

Para enviarle un mensaje a una persona, envía una solicitud POST al extremo /PAGE-ID/messsages con los parámetros messaging_type y recipient configurados, y el contenido del mensaje.

El formato se modificó para fines de legibilidad.

El siguiente ejemplo constituye la respuesta solo de texto al mensaje que una persona envió a tu página.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
    ?recipient={'id':'PSID'}
    &messaging_type=RESPONSE
    &message={'text':'hello,world'}
    &access_token=PAGE-ACCESS-TOKEN

Si se envía correctamente, la app recibirá la siguiente respuesta en formato JSON:

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
}

Parámetros

ParámetroDescripción

message

object

El tipo de mensaje que envía tu página. Se debe configurar text o attachement al usar este parámetro.

  • El objeto attachment muestra una vista previa de la URL. Se usa para enviar mensajes con elementos multimedia o mensajes estructurados. Se debe configurar text o attachment.

  • metadata es una cadena de datos adicionales que debes transmitir en el webhook message_echo. No debe superar los 1.000 caracteres.

  • quick_replies es una variedad de respuestas rápidas que se envían en un mensaje.
  • text es un mensaje que contiene solo texto. Debe usar la codificación UTF-8 y no debe superar los 2.000 caracteres.

messaging_type

enum

Obligatorio

El tipo mensaje que se envía

notification_type

enum

Tipo de notificación push que una persona recibe

  • NO_PUSH: ninguna notificación.
  • REGULAR (predeterminada): sonido o vibración cuando una persona recibe el mensaje.
  • SILENT_PUSH: solo notificaciones en pantalla.

recipient

objeto

Obligatorio

La persona que recibirá el mensaje que envía tu página

  • id: identificador específico de la página de la persona, que se utiliza para enviar un mensaje en respuesta a otro que recibió tu página en las últimas 24 horas, o de la persona que aceptó recibir mensajes de tu página fuera del intervalo de 24 horas de mensajes estándar.
  • user_ref: referencia de la persona que se utiliza para enviar un mensaje en respuesta al plugin Checkbox o de chat con clientes.
  • comment_id: identificador del comentario que se utiliza para enviar un mensaje como respuesta privada al comentario de un visitante en la publicación de la página.
  • post_id: identificador de la publicación de la página que se utiliza para enviar un mensaje como respuesta privada a la publicación de un visitante en tu página.

sender_action

enum

El icono de acción que se muestra en la ventana de mensajes y que representa la acción que realiza la página respecto del mensaje que una persona le envió.

  • typing_on: muestra el cuadro de escritura cuando la página está preparando una respuesta.
  • typing_off: no muestra el cuadro de escritura.
  • mark_seen: muestra el icono de mensaje visto en los mensajes que la página ya leyó.

Solo se puede enviar con el parámetro recipient. No se puede enviar con el parámetro message, pero se debe enviar como una solicitud independiente.

tag

enum

Etiqueta que permite a la página enviar un mensaje a una persona fuera del intervalo de 24 horas de mensajes estándar.

  • ACCOUNT_UPDATE: etiqueta el mensaje que le envías al cliente como actualización no recurrente a su app o cuenta. Consulta los usos admitidos.

    No disponible para la API de mensajes de Instagram.

  • CONFIRMED_EVENT_UPDATE: etiqueta el mensaje que le envías al cliente como recordatorio de un evento próximo o como actualización de un evento en curso al que se registró. Consulta los usos admitidos.

    No disponible para la API de mensajes de Instagram.

  • CUSTOMER_FEEDBACK: etiqueta el mensaje que le envías al cliente como encuesta de comentarios para clientes . Los mensajes con comentarios del cliente se deben enviar en un plazo de siete días desde el último mensaje que este envió. Consulta los usos admitidos.

    No disponible para la API de mensajes de Instagram.

  • HUMAN_AGENT: obligatorio para la API de mensajes de Instagram. Cuando se agrega esta etiqueta a un mensaje que se le envía a una persona, un agente humano puede responder al mensaje de dicha persona. Los mensajes se pueden enviar en un plazo de siete días a partir del mensaje que envío la persona. La asistencia mediante agente humano es para resolver problemas que no se pueden solucionar en el intervalo de mensajes estándar. Consulta los usos admitidos.
    • Las apps deberán solicitar el permiso Human Agent por medio del panel de apps para desarrolladores. Ve a Panel de apps -> Revisión de la app -> Permisos y funciones -> Agente humano. Las apps que anteriormente se aprobaron para acceso en fase beta al permiso para agentes humanos no deben volver a solicitar acceso.

    El permiso Human Agent no está disponible en modo de desarrollo o acceso estándar. Deberás completar el proceso de revisión de la app para poder usar la etiqueta de agente humano. Durante el envío de la app al proceso de revisión, proporciona instrucciones claras y una demostración de cómo intentas usar la etiqueta de agente humano en tus experiencias.

  • POST_PURCHASE_UPDATE: etiqueta el mensaje que le envías al cliente como una actualización de una compra reciente que este realizó. Consulta los usos admitidos.

    No disponible para la API de mensajes de Instagram.

Uso de etiquetas de mensaje

La siguiente tabla enumera los tipos de mensajes que corresponden a cada etiqueta de mensaje.

Uso deetiquetas de mensaje

ACCOUNT_UPDATE

Usos permitidos

  • Notificación de cambio de estado de una app, por ejemplo, una solicitud de tarjeta de crédito o de empleo
  • Notificación de actividad sospechosa, como alertas por fraude

Usos no admitidos (lista no exhaustiva)

  • Contenido promocional, incluidos, entre otros, ofertas, promociones, cupones y descuentos; contenido recurrente, como avisos de extractos listos, facturas adeudadas, nuevos anuncios de empleo
  • Invitaciones para completar una encuesta o dejar una opinión que no guarda relación con la interacción anterior en Messenger

No disponible para la API de mensajes de Instagram.

CONFIRMED_EVENT_UPDATE

Usos permitidos

  • Recordatorio de una clase, una cita o un evento próximos que un usuario programó
  • Confirmación de la reserva de un usuario o la asistencia a un evento o una cita aceptados
  • Notificación sobre el transporte o el viaje programado de un usuario, como horario de llegada, cancelación, equipaje demorado o cambios en el estado del viaje

Usos no admitidos (lista no exhaustiva)

  • Contenido promocional, incluidos, entre otros, ofertas, cupones y descuentos
  • Contenido relacionado con un evento al que el usuario no se registró (por ejemplo, recordatorios de compra de boletos para un evento, venta cruzada de otros eventos, itinerarios de recorridos, etc.)
  • Mensajes relacionados con eventos anteriores
  • Invitaciones para completar una encuesta o dejar una opinión que no guarda relación con la interacción anterior en Messenger

No disponible para la API de mensajes de Instagram.

CUSTOMER_FEEDBACK

Usos permitidos

  • Encuesta de comentarios sobre el servicio de atención de compras
  • Encuesta de comentarios sobre un evento
  • Opiniones del producto

Usos no admitidos (lista no exhaustiva)

  • La etiqueta solo se puede usar con la plantilla de comentarios de clientes. Todos los demás usos no se admiten y presentarán fallas.

No disponible para la API de mensajes de Instagram.

HUMAN_AGENT

Usos permitidos

  • Asistencia mediante agente humano para resolver problemas que no se pueden solucionar en el intervalo de 24 horas de mensajes estándar, por ejemplo, problemas fuera del horario laboral o cuya resolución requiere más de 24 horas

Usos no admitidos (lista no exhaustiva)

  • Mensajes automáticos
  • Contenido no relacionado con la consulta del usuario

Obligatorio para la API de mensajes de Instagram.

POST_PURCHASE_UPDATE

Usos permitidos

  • Confirmación de una transacción, como facturas o recibos
  • Actualización de estado de un envío, como producto en tránsito, enviado, entregado o demorado
  • Actualización de estado que requiere que un usuario realice una acción respecto de un pedido que realizó, como una tarjeta de crédito rechazada, artículos en demora por falta de stock u otras actualizaciones relativas a un pedido que requieren que el usuario tome medidas

Usos no admitidos (lista no exhaustiva)

  • Contenido promocional, incluidos, entre otros, ofertas, promociones, cupones y descuentos
  • Mensajes que realizan ventas cruzadas o dirigidas de productos o servicios
  • Invitaciones para completar una encuesta o dejar una opinión que no guarda relación con la interacción anterior en Messenger

No disponible para la API de mensajes de Instagram.

Lectura

No puedes realizar esta operación en este extremo.

Para obtener información sobre las conversaciones de las que forma parte tu página, visita la referencia de conversaciones de la página.

Actualización

No puedes realizar esta operación en este extremo.

Eliminación

No puedes realizar esta operación en este extremo.

Más información

Ayuda para desarrolladores