Integración por Inbound Webhooks
TimelinesAI le permite automatizar el envío de mensajes de WhatsApp, en respuesta a eventos o acciones en herramientas que ya esté utilizando: CRM, sistemas de Soporte y Reclutamiento, etc.
Es posible indicar a TimelinesAI que envíe un mensaje (con o sin archivo adjunto) a un contacto específico (o un chat grupal). Si hay varias cuentas de WhatsApp conectadas en su espacio de trabajo, también es posible especificar una cuenta de WhatsApp en particular, para enviar el mensaje.
Para configurar la integración, el dueño de un espacio de trabajo debe navegar a Webhooks → Inbound webhook y generar una nueva URL. El sistema externo debe publicar un mensaje en un formato específico (ver detalles a continuación) en esa URL.
El tamaño máximo del archivo adjunto es de 2 MB.
No hay validación inmediata del formato del número de teléfono del destinatario, ni conexión a WhatsApp. Navegue a la interfaz de TimelinesAI para verificar el estado de "envío/lectura" de los mensajes.
Es imperativo enviar archivos mediante enlaces de descarga directa. Esto permite que el destinatario reciba el archivo inmediatamente.
Un servicio de alojamiento de archivos se debe utilizar solamente para que pueda proporcionar un enlace de descarga directa. Tal enlace se prueba mejor a través de navegación en incógnito/privada; pegando el enlace en la barra de búsqueda. Si la descarga del archivo comienza de inmediato, el enlace es aceptable. Si en cambio, se muestra cualquier tipo de página web, entonces, el enlace no se puede utilizar para enviar archivos.
El caso de los enlaces de Servicios de Alojamiento de Archivos, es que los archivos no se pueden descargar. Lo que se descarga y envía en su lugar, es una página web compartida, lo que puede conducir a un archivo «dañado».
Esto, a su vez, afectará su mensaje, ya que los destinatarios no pueden acceder a los archivos que les envía, lo que hace que los mismos queden inutilizables. Por lo tanto, es crucial que se asegure de enviar enlaces de descarga directa, ya que esto les permitirá acceder al archivo sin ningún problema.
También puede ejecutar esta prueba, enviando un mensaje de webhook a uno de sus números de prueba. Podrá determinar cómo se comportará el archivo en función de lo que hemos revisado aquí; si recibe un mensaje de error como «El archivo está dañado», «Archivo incompatible», o «Error al cargar el documento X», después de hacer clic en el archivo adjunto, entonces este es un enlace de servicio de alojamiento de archivos y debe reemplazarse con un enlace de descarga directa.
El envío de un mensaje consume 1 unidad de cuota de envío masivo (o cuota de mensajería masiva).
Enviar un mensaje con texto no vacío y archivo adjunto consume 2 unidades de cuota de envío masivo.
Si no se puede enviar un mensaje (número no válido o no conectado a WhatsApp, error del servidor de WhatsApp), se restaurará la cuota de envío masivo (normalmente en un par de horas).
Los mensajes se enviarán con un retraso aleatorio de unos 2 segundos entre cada dos mensajes (para evitar los mecanismos de detección de spam de WhatsApp).
Si habilita webhooks con una frecuencia de menos de 2 segundos, los mensajes se pondrán en cola y se enviarán con retraso. Cada mensaje en cola consumirá una unidad de envío masivo, por lo que la cantidad de mensajes en cola no puede exceder la cuota de envío masivo disponible.
"Webhook enabled": Permite deshabilitar el webhook sin eliminarlo por completo
“Generate new URL”: Creará una nueva URL única, que aceptará notificaciones. La URL anterior ya no estará disponible
“Last sending attempts”: Estado de los últimos intentos de activación del webhook
"Download log": Un registro detallado de los últimos 100 intentos de activación, útil para solucionar problemas de formato.
El Webhook acepta datos en formato JSON, mediante solicitud POST.
"action" (obligatorio): De momento, solo se admite un valor posible «send» (enviar)
"text" (obligatorio): Se puede enviar un mensaje de texto sin formato codificado en UTF-8 (no se admite formato «markdown», excepto el separador de línea «\n»), se puede dejar vacío, si se especifica el archivo.
"file_url" (opcional): URL de acceso público (enlace de descarga directa) de un archivo que se descargará y enviará como archivo adjunto.
"file_name" (opcional): Un nombre para el archivo adjunto (debe proporcionarse, si se especifica la URL).
El destinatario se puede especificar proporcionando uno de los siguientes parámetros:
"chat_id": Una identificación del chat tal como aparece en TimelinesAI (se puede encontrar en la URL de la página de chat o en la «payload» del outbound webhook). Esto admite el envío de mensajes a un grupo.
"jid": Un JID de WhatsApp que especifica contacto o grupo
"teléfono": Un número de teléfono, formateado de acuerdo con el estándar internacional de números de teléfono, es decir: [+][código de país][código de área][número de teléfono local] (por ejemplo: +14151231234)
"chat_name": Un nombre exacto del chat como aparece en TimelinesAI
Si hay varias cuentas de WhatsApp conectadas en el espacio de trabajo, utilice el siguiente parámetro adicional para especificar la cuenta de WhatsApp que se utilizará:
"teléfono de la cuenta de whatsapp" (opcional): Especifica (como un número de teléfono, en formato internacional) la cuenta de WhatsApp que se usará para enviar. Si se omite, se utilizará para el envío la cuenta de WhatsApp activa conectada más recientemente en el espacio de trabajo.
Nota: Si se especifica el parámetro «chat_id», se ignorará el «whatsapp account phone»(teléfono de la cuenta de WhatsApp), porque cada chat ya está conectado a una cuenta de WhatsApp específica.
En caso de éxito (la solicitud fue validada y aceptada para envío), el Webhook responderá con estado HTTP 200 y JSON, conteniendo el «message_id» del mensaje creado:
{
"status": "success",
"data": {
"message_id": "wa_backend:3EB09FCC85FE99662E46"
}
}
En caso de error, el Webhook responderá con estado HTTP 40X y JSON con detalles del erro, como por ejemplo:
{
"status": 40X,
"data": {},
"message": "Webhook not found"
}
Ejemplo 1: Enviar un mensaje a través de una cuenta de WhatsApp específica hacia un número específico:
{
"action": "send",
"whatsapp account phone" : "+15105566777",
"phone": "+14151231234",
"text": "lorem ipsum"
}
Ejemplo 2: Enviar un mensaje con texto y archivo adjunto a un chat (directo o grupal) especificado por la ID:
{
"action": "send",
"chat_id": "77234",
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}
Evento «Send message» (Enviar Mensaje)
Es posible indicar a TimelinesAI que envíe un mensaje (con o sin archivo adjunto) a un contacto específico (o un chat grupal). Si hay varias cuentas de WhatsApp conectadas en su espacio de trabajo, también es posible especificar una cuenta de WhatsApp en particular, para enviar el mensaje.
Para configurar la integración, el dueño de un espacio de trabajo debe navegar a Webhooks → Inbound webhook y generar una nueva URL. El sistema externo debe publicar un mensaje en un formato específico (ver detalles a continuación) en esa URL.
Limitaciones
El tamaño máximo del archivo adjunto es de 2 MB.
No hay validación inmediata del formato del número de teléfono del destinatario, ni conexión a WhatsApp. Navegue a la interfaz de TimelinesAI para verificar el estado de "envío/lectura" de los mensajes.
Envío de Archivos a través de Inbound Webhooks
Envío de un Archivo: Descarga Directa VS Servicios de Alojamiento de Archivos
Es imperativo enviar archivos mediante enlaces de descarga directa. Esto permite que el destinatario reciba el archivo inmediatamente.
Un servicio de alojamiento de archivos se debe utilizar solamente para que pueda proporcionar un enlace de descarga directa. Tal enlace se prueba mejor a través de navegación en incógnito/privada; pegando el enlace en la barra de búsqueda. Si la descarga del archivo comienza de inmediato, el enlace es aceptable. Si en cambio, se muestra cualquier tipo de página web, entonces, el enlace no se puede utilizar para enviar archivos.
El caso de los enlaces de Servicios de Alojamiento de Archivos, es que los archivos no se pueden descargar. Lo que se descarga y envía en su lugar, es una página web compartida, lo que puede conducir a un archivo «dañado».
Esto, a su vez, afectará su mensaje, ya que los destinatarios no pueden acceder a los archivos que les envía, lo que hace que los mismos queden inutilizables. Por lo tanto, es crucial que se asegure de enviar enlaces de descarga directa, ya que esto les permitirá acceder al archivo sin ningún problema.
También puede ejecutar esta prueba, enviando un mensaje de webhook a uno de sus números de prueba. Podrá determinar cómo se comportará el archivo en función de lo que hemos revisado aquí; si recibe un mensaje de error como «El archivo está dañado», «Archivo incompatible», o «Error al cargar el documento X», después de hacer clic en el archivo adjunto, entonces este es un enlace de servicio de alojamiento de archivos y debe reemplazarse con un enlace de descarga directa.
Utilización de Crédito o Cuota
El envío de un mensaje consume 1 unidad de cuota de envío masivo (o cuota de mensajería masiva).
Enviar un mensaje con texto no vacío y archivo adjunto consume 2 unidades de cuota de envío masivo.
Si no se puede enviar un mensaje (número no válido o no conectado a WhatsApp, error del servidor de WhatsApp), se restaurará la cuota de envío masivo (normalmente en un par de horas).
Tasa de Envío de Mensajes
Los mensajes se enviarán con un retraso aleatorio de unos 2 segundos entre cada dos mensajes (para evitar los mecanismos de detección de spam de WhatsApp).
Si habilita webhooks con una frecuencia de menos de 2 segundos, los mensajes se pondrán en cola y se enviarán con retraso. Cada mensaje en cola consumirá una unidad de envío masivo, por lo que la cantidad de mensajes en cola no puede exceder la cuota de envío masivo disponible.
Configuración y Acciones de Webhook
"Webhook enabled": Permite deshabilitar el webhook sin eliminarlo por completo
“Generate new URL”: Creará una nueva URL única, que aceptará notificaciones. La URL anterior ya no estará disponible
“Last sending attempts”: Estado de los últimos intentos de activación del webhook
"Download log": Un registro detallado de los últimos 100 intentos de activación, útil para solucionar problemas de formato.
Formato de Solicitud de Webhook
El Webhook acepta datos en formato JSON, mediante solicitud POST.
"action" (obligatorio): De momento, solo se admite un valor posible «send» (enviar)
"text" (obligatorio): Se puede enviar un mensaje de texto sin formato codificado en UTF-8 (no se admite formato «markdown», excepto el separador de línea «\n»), se puede dejar vacío, si se especifica el archivo.
"file_url" (opcional): URL de acceso público (enlace de descarga directa) de un archivo que se descargará y enviará como archivo adjunto.
"file_name" (opcional): Un nombre para el archivo adjunto (debe proporcionarse, si se especifica la URL).
El destinatario se puede especificar proporcionando uno de los siguientes parámetros:
"chat_id": Una identificación del chat tal como aparece en TimelinesAI (se puede encontrar en la URL de la página de chat o en la «payload» del outbound webhook). Esto admite el envío de mensajes a un grupo.
"jid": Un JID de WhatsApp que especifica contacto o grupo
"teléfono": Un número de teléfono, formateado de acuerdo con el estándar internacional de números de teléfono, es decir: [+][código de país][código de área][número de teléfono local] (por ejemplo: +14151231234)
"chat_name": Un nombre exacto del chat como aparece en TimelinesAI
Si hay varias cuentas de WhatsApp conectadas en el espacio de trabajo, utilice el siguiente parámetro adicional para especificar la cuenta de WhatsApp que se utilizará:
"teléfono de la cuenta de whatsapp" (opcional): Especifica (como un número de teléfono, en formato internacional) la cuenta de WhatsApp que se usará para enviar. Si se omite, se utilizará para el envío la cuenta de WhatsApp activa conectada más recientemente en el espacio de trabajo.
Nota: Si se especifica el parámetro «chat_id», se ignorará el «whatsapp account phone»(teléfono de la cuenta de WhatsApp), porque cada chat ya está conectado a una cuenta de WhatsApp específica.
Respuesta del Webhook
En caso de éxito (la solicitud fue validada y aceptada para envío), el Webhook responderá con estado HTTP 200 y JSON, conteniendo el «message_id» del mensaje creado:
{
"status": "success",
"data": {
"message_id": "wa_backend:3EB09FCC85FE99662E46"
}
}
En caso de error, el Webhook responderá con estado HTTP 40X y JSON con detalles del erro, como por ejemplo:
{
"status": 40X,
"data": {},
"message": "Webhook not found"
}
Ejemplos
Ejemplo 1: Enviar un mensaje a través de una cuenta de WhatsApp específica hacia un número específico:
{
"action": "send",
"whatsapp account phone" : "+15105566777",
"phone": "+14151231234",
"text": "lorem ipsum"
}
Ejemplo 2: Enviar un mensaje con texto y archivo adjunto a un chat (directo o grupal) especificado por la ID:
{
"action": "send",
"chat_id": "77234",
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}
Actualizado el: 18/01/2023
¡Gracias!