Signal Integration

Reporting observations and feeding the Engine.

Signals report what happened after a touch delivers — delivery, engagement, response, sentiment, conversion. The Engine uses these readings to trigger adjustment rules.

Types

Type	Measures	Metrics
`delivery`	Message arrived	`delivered`, `bounced`, `blocked`
`engagement`	Audience interacted	`opened`, `clicked`, `viewed`
`response`	Audience responded	`replied`, `called_back`, `forwarded`
`behavior`	Observable actions	`visited_site`, `downloaded`, `shared`
`sentiment`	Emotional signal	`positive`, `negative`, `neutral`, `hostile`
`conversion`	Goal completion	`signed`, `purchased`, `enrolled`

Submitting

await rodeo.signals.report({
  signalId: "twilio-webhook",
  touchId: touch.id,
  sceneId: scene.id,
  type: "delivery",
  metric: "delivered",
  value: true,
  confidence: 1.0,
});

Fields

Field	Type	Required	Description
`signalId`	string	yes	Signal source identifier
`touchId`	UUID	yes	Target touch
`sceneId`	UUID	yes	Parent scene
`type`	string	yes	Signal type
`metric`	string	yes	What was measured
`value`	any	yes	Measurement value
`confidence`	number	no	Reliability, 0.0--1.0 (default 1.0)

Batch

await rodeo.signals.reportBatch([
  { signalId: "twilio-webhook", touchId: touch.id, sceneId: scene.id, type: "delivery", metric: "delivered", value: true },
  { signalId: "twilio-webhook", touchId: touch.id, sceneId: scene.id, type: "response", metric: "replied", value: "Sounds interesting" },
  { signalId: "sentiment-analyzer", touchId: touch.id, sceneId: scene.id, type: "sentiment", metric: "positive", value: 0.85, confidence: 0.72 },
]);

Webhook pattern

app.post("/webhooks/twilio", async (req, res) => {
  const { MessageSid, MessageStatus } = req.body;
  const touch = await findTouchByProviderRef(MessageSid);
  if (!touch) return res.sendStatus(200);

  await rodeo.signals.report({
    signalId: "twilio-delivery",
    touchId: touch.id,
    sceneId: touch.sceneId,
    type: "delivery",
    metric: MessageStatus,
    value: MessageStatus === "delivered",
  });

  res.sendStatus(200);
});

Confidence

Range	Signal
1.0	Direct observation (webhook, API response)
0.7--0.9	Inferred (open tracking, behavioral)
0.3--0.6	Estimated (sentiment analysis, prediction)
< 0.3	Speculative

The Engine weighs readings by confidence when evaluating adjustment rules.

Querying

const scene = await rodeo.scenes.get(sceneId);
// scene.signal_readings contains all readings