Question 1

¿Qué campos son comunes a todas las plataformas?

Accepted Answer

Cada payload de SocialHook incluye: platform (facebook/instagram/whatsapp), event (message.received/conversation.started/status.update), timestamp, webhook_id, conversation_id y un objeto message.

Question 2

¿Cómo verifico la autenticidad del payload?

Accepted Answer

Comprueba el encabezado X-SocialHook-Signature, que contiene sha256=<hex>, un HMAC-SHA256 del cuerpo crudo de la solicitud firmado con tu clave secreta. Calcula el mismo hash en el servidor y compara usando una función a tiempo constante.

Question 3

¿Son consistentes los formatos de payload entre plataformas?

Accepted Answer

Sí. Los campos comunes usan la misma estructura en Facebook, Instagram y WhatsApp. Los campos específicos de cada plataforma (como el número de teléfono de WhatsApp o el @usuario de Instagram) están anidados en la sección específica de la plataforma del payload.

Question 4

¿Qué es el campo conversation_id?

Accepted Answer

conversation_id es un identificador estable del hilo entre un usuario específico y tu cuenta de plataforma conectada. Úsalo para agrupar mensajes del mismo usuario a lo largo de múltiples interacciones.

Campo	Tipo	Descripción
`platform`	`string`	"facebook" \| "instagram" \| "whatsapp"
`event`	`string`	"message.received" \| "conversation.started" \| "status.update"
`timestamp`	`number`	Marca de tiempo Unix (en segundos) de cuándo ocurrió el evento
`webhook_id`	`string`	El ID de configuración de tu webhook de SocialHook
`conversation_id`	`string`	ID estable del hilo de la conversación
`message`	`object`	Objeto con el contenido del mensaje (varía según la plataforma y el tipo)

Campo	Tipo	Descripción
`from`	`string`	Número de teléfono del remitente en formato E.164 (+15550001234)
`profile.name`	`string`	Nombre que se muestra en WhatsApp del remitente
`message.type`	`string`	"text" \| "image" \| "audio" \| "video" \| "document" \| "location" \| "sticker"
`message.body`	`string`	Texto del mensaje (para type="text")
`message.media_url`	`string`	URL para descargar el archivo (para image/audio/video/document)

Campo	Tipo	Descripción
`from.id`	`string`	ID de usuario de Facebook del remitente (PSID)
`from.name`	`string`	Nombre que se muestra en Facebook del remitente
`page_id`	`string`	ID de la página de Facebook que recibió el mensaje
`message.text`	`string`	Contenido de texto del mensaje
`message.attachments`	`array`	Arreglo de objetos de adjuntos para imágenes, videos, etc.

Campo	Tipo	Descripción
`from.id`	`string`	ID de usuario de Instagram del remitente
`from.username`	`string`	@usuario del remitente
`account_id`	`string`	ID de la cuenta de Instagram Business
`message.text`	`string`	Contenido de texto del DM
`story_id`	`string`	ID de historia cuando el mensaje es una respuesta a una historia (opcional)

Referencia del payload

Campos comunes (todas las plataformas)

WhatsApp: campos específicos

Facebook: campos específicos

Instagram: campos específicos