Conceptos básicos
Los objetivos y las palabras clave son cosas distintas
Un objetivo es una cuenta que vigilas; recibes todo lo que hace, o solo los tipos de evento que elijas. Una palabra clave es una consulta que vigilas en todo X; recibes las publicaciones de cualquiera que coincidan con ella, como eventos search.match. Los objetivos se identifican por el nombre de usuario, las palabras clave por el texto de la consulta, y una clave puede tener cualquier número de ambos hasta los límites de su plan.
Una cuenta es su id, no su nombre de usuario
Monitorizas una cuenta, identificada por su id numérico de X (id en un Target). Una cuenta puede cambiar su nombre de usuario (screen_name) o su nombre visible en cualquier momento: sigues recibiendo sus eventos, los siguientes llevan el nuevo nombre en target.screen_name y un evento profile.screen_name o profile.name te indica qué cambió. Indexa tus datos por id. Donde la API pide una cuenta, puedes indicarla por su user_id, su nombre actual o uno que tuvo antes.
Entrega en dos fases: crear y luego actualizar
Algunos eventos de publicación se entregan en dos tramas. La primera, op: "create", lleva lo esencial — el id de la publicación, el autor y el texto — para que puedas actuar de inmediato. Un momento después llega otra vez el mismo id de evento con op: "update", ahora con los medios, el original citado o respondido, los recuentos y el resto. Los eventos que ya están completos la primera vez que se ven no tienen segunda trama; GET /v1/meta/event-types indica qué tipos pueden tenerla.
create. Si necesitas la publicación entera, espera al update del mismo id. En cualquier caso, indexa tu almacenamiento por id y deja que un update posterior sobrescriba lo que guardaste. El tipo solo cambia entre las dos tramas de una manera: un primer tweet.create con kind_final: false puede convertirse en tweet.quote. Si tratas de forma distinta las publicaciones originales y las citas, clasifica esa trama cuando llegue su update.Al menos una vez, nunca exactamente una
Cada cuenta monitorizada está vigilada por varias vías independientes a la vez, para que una vía que falle no te cueste nada. La primera que informa de un cambio dado gana y se convierte en el evento; las demás se registran como corroboración en lugar de entregarse otra vez. Tras una reconexión, sin embargo, puedes ver un evento que ya tenías. Deduplica por id.
Posición y repetición
Cada evento lleva un sid — su posición en nuestro registro. Persiste el último que hayas procesado; al reconectar, pásalo como ?last_id= y te enviamos todo lo posterior antes de reanudar en directo. El registro conserva 24 horas, y una sola reconexión repite como máximo 5000 eventos. Los objetivos o palabras clave que añadas con un socket abierto empiezan a fluir por él en menos de 30 segundos; no necesitas reconectar.