Self-improving AI Employees for everyone
Twitter Receive (twitterReceive)
| Field | Value |
|---|---|
| Category | social / trigger |
| Backend handler | Plugin server/nodes/twitter/twitter_receive/__init__.py; execute() refuses with a NodeUserError and validate_graph refuses Start (see the status note below). Filter: server/nodes/twitter/_filters.py::build_filter. Events: server/nodes/twitter/_events.py. |
| Tests | server/tests/nodes/test_twitter.py |
| Skill (if any) | none |
| Dual-purpose tool | no (trigger only) |
Purpose
Status (2026-10-23, RFC-0005 Phase 0.8): the node refuses to run. Nothing polls Twitter for it: it is not a
PollingTriggerNode, anddispatch_twitter_event_receivedhas no caller, so a deployed one never fired and a canvas Run waited forever. Start now refuses it withTWITTER_RECEIVE_UNAVAILABLE, and a canvas Run returns aNodeUserErrorpointing to Twitter Search on a Cron Scheduler. Making it work means subclassingPollingTriggerNodewithfetch_ids/fetch_detailover the X API's mentions, search and timeline endpoints (paid and rate-limited). The rest of this card describes the intended design.
Wait for a Twitter/X event (mention, search match, or timeline update) and emit
it as the workflow trigger payload. The trigger is polling-based (X API v2 has
no push webhooks on the free tier); polling is driven by the deployment layer
(server/services/deployment/) while the execution side reuses the same
handle_trigger_node path that WhatsApp/Webhook/Telegram triggers use -
register a waiter, block on event_waiter.wait_for_event, and surface the
matching event.
Canary status: twitterReceive is the lone deferred trigger plugin —
it is NOT in the canary registry (register_canary_trigger_type is not
called). Adoption of the controlled Temporal path requires the node to subclass
PollingTriggerNode and declare the four hooks (the GmailReceiveNode shape),
so WorkflowControlWorkflow can own its polling activity. Until that refactor
lands it runs on the legacy event_waiter collector/processor path.
TriggerListenerWorkflow / PollingTriggerWorkflow are compatibility
implementations, not the target architecture. _events.py carries the
typed WorkflowEvent factory + dual-path dispatcher (dispatch_twitter_event_received)
ready for canary opt-in.
Filtering is done by the closure returned from build_filter in
nodes/twitter/_filters.py (auto-registered into event_waiter.FILTER_BUILDERS).
Inputs (handles)
Trigger node - no inputs.
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
trigger_type |
options | mentions |
yes | - | One of mentions / search / timeline. Filter compares against the event's trigger_type field. |
search_query |
string | "" |
yes when trigger_type=search |
trigger_type: ['search'] |
Substring-matched (case-insensitive) against event query. |
user_id |
string | "" |
no | trigger_type: ['timeline'] |
When set, must exactly match event user_id. Empty -> authenticated user (resolved by the poller, not the filter). |
filter_retweets |
boolean | true |
no | - | Accepted by frontend; not consumed by the execution-side filter. Any effect must be implemented by the poller. |
filter_replies |
boolean | false |
no | - | Same as above - frontend-only hint. |
poll_interval |
number | 60 |
no | - | Seconds between polls (15-3600). Consumed by deployment/ when deploying the workflow, not by handle_trigger_node. |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
TwitterReceiveOutput |
Raw event data returned by event_waiter.wait_for_event. The declared Output model (tweet_id, text, author, plus extra="allow") passes through the full dispatched payload. |
Output payload (contract)
The event shape is produced by whichever polling loop dispatches
twitter_event_received (legacy event_type, preserved in _events.py).
Documented fields the filter and downstream nodes rely on:
{
trigger_type: 'mentions' | 'search' | 'user_timeline';
tweet_id: string;
text: string;
author_id: string;
author_username?: string;
created_at: string;
// search-specific:
query?: string;
// timeline-specific:
user_id?: string;
// optionally: metrics, referenced_tweets, entities
}
The handler wraps this in { success: true, result: <event_data>, execution_time }.
Logic Flow
flowchart TD
A[handle_trigger_node] --> B[event_waiter.get_trigger_config twitterReceive]
B -- None --> E1[Return success=false<br/>error: Unknown trigger type]
B -- config --> C[event_waiter.register<br/>_filters.build_filter]
C --> D[broadcaster.update_node_status waiting]
D --> E[await event_waiter.wait_for_event]
E -- CancelledError --> Ecx[Return success=false<br/>error: Cancelled by user]
E -. any other Exception .-> EG[Return success=false<br/>error: str e]
E -- event --> F[Return success=true<br/>result = event_data]
subgraph Producer
P1[Deployment polling task] --> P2[Fetch via XDK<br/>mentions/search/user_timeline]
P2 --> P3[event_waiter.dispatch<br/>twitter_event_received]
P3 --> P4[_filters.build_filter.matches]
P4 -- match --> P5[Waiter.future.set_result]
end
Decision Logic (filter)
build_filter(params) (in nodes/twitter/_filters.py) returns a matches(data)
closure that rejects non-matching events:
trigger_type != 'all'anddata['trigger_type'] != trigger_type-> reject. (Frontend only exposesmentions/search/timeline; there is no way to selectallfrom the UI.)- search branch: if
trigger_type == 'search'andsearch_queryset, compare lowercase-substring againstdata['query']. Emptysearch_queryaccepts any search event. - user_timeline branch: if
trigger_type == 'user_timeline'anduser_idis set, requiredata['user_id'] == user_id(exact). Emptyuser_idaccepts any timeline event. - No
filter_retweets/filter_replieslogic exists inbuild_filter.
Execution-side handler branches
- Unknown
trigger_type:handle_trigger_nodelooks up the config and returns an error envelope if missing. FortwitterReceivethe config is hard-coded inTRIGGER_REGISTRY, so this branch is unreachable in practice. asyncio.CancelledErrorfromwait_for_event-> success=false,error="Cancelled by user".- Any other exception -> success=false,
error=str(e).
Side Effects
- Database writes: none from the handler. The poller in
deployment/may write independently. - Broadcasts:
status_broadcaster.update_node_status(node_id, "waiting", {message, event_type: "twitter_event_received", waiter_id}, workflow_id=...)when the waiter is registered. - External API calls: none from the handler. The polling loop makes
periodic
GET /2/users/:id/mentions,GET /2/tweets/search/recent, orGET /2/users/:id/tweetsrequests. - File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: OAuth tokens via
auth_service.get_oauth_tokens("twitter")(read by the poller, not by the handler). - Services:
event_waiter,StatusBroadcaster,deployment/polling infrastructure. - Python packages:
xdk. - Environment variables: none.
Edge cases & known limits
filter_retweets/filter_repliesignored: despite the UI toggles, the execution-side filter does nothing with them. Unless the poller honours them downstream, retweets and replies will surface.- Frontend <-> filter mismatch: frontend offers
trigger_type='timeline'but the filter compares againstevent_type == 'user_timeline'. The poller must dispatch events taggedtrigger_type: 'user_timeline'(note the prefix) or matching will fail silently. - Substring match on
search_query: case-insensitive substring - no boolean operators, no token-awareness."AI"insidequery="raid"matches. user_idcomparison is exact: leading@or whitespace mismatches silently.- No timeout on wait: the handler waits indefinitely. Only exits on event, cancellation, or server restart.
- Polling latency:
poll_intervaldefault is 60s - expect up to a minute between a tweet being created and the node firing. - No dedup at the filter: consecutive polls producing the same
tweet_idrely on the poller for deduplication. The filter will happily match the same tweet twice.
Related
- Sibling nodes:
twitterSend,twitterSearch,twitterUser - Event waiter architecture: Event Waiter System
- Deployment / polling triggers:
server/services/deployment/