USuseboom
Initiatives

Add or replace a success metric

Changed on

Configure what counts as success for an initiative: a customer-data event, a record on a custom object, or a value extracted from the conversation, measured within 48 hours of the first message. Omit rootId to add a metric; pass an existing metric's rootId to replace it with a new version. This is not a patch — send the metric's complete configuration, because omitted fields are cleared. Successes are recalculated on every read, so replacing a metric also changes what the dashboard reports for past conversations. Use success_metrics_catalog to find the event, object type or variable to point at.

post/api/v1/initiatives/{id}/success-metrics

Request

  • Base URL
    https://www.useboom.ai
  • Auth
    HTTP bearer

Path parameters

idstring required

The initiative id.

Request body

rootIdstring

Omit to add a new metric. Pass an existing metric's rootId to replace it with a new version.

namestring required

The metric label, shown in the dashboard picker.

signalType'CDP_EVENT' | 'CUSTOM_OBJECT' | 'EXTRACTED_VARIABLE'

What counts as success: a customer-data event, a record on a custom object, or a value extracted from the conversation. Default CDP_EVENT.

aggregation'COUNT' | 'SUM' | 'AVERAGE' | 'MAX'

How matched values roll up. COUNT needs no value field; SUM, AVERAGE and MAX each require one. Default COUNT.

roiEnabledboolean

Whether this metric's dashboard shows ROI — attributed sales over what the journey's messages cost, at Boom's fixed average rates. Only meaningful when the metric sums a money value, so it is forced off for COUNT. Default false.

eventNamestring nullable

Required when signalType is CDP_EVENT: the event name that marks success.

valuePropertystring nullable

The numeric event property to aggregate. Required when signalType is CDP_EVENT and aggregation is not COUNT.

valueSource'EVENT_PROPERTY' | 'RELATED_OBJECT'

Whether the aggregated value lives on the event itself or on a custom object the event points at. Default EVENT_PROPERTY.

valueObjectTypeIdstring nullable

Required when valueSource is RELATED_OBJECT: the custom-object type to read the value from.

valueRefPropertystring nullable

Required when valueSource is RELATED_OBJECT: the event property holding the object's external id.

variableIdstring nullable

Required when signalType is EXTRACTED_VARIABLE: the extracted variable that defines success.

objectTypeIdstring nullable

Required when signalType is CUSTOM_OBJECT: the custom-object type a qualifying record belongs to.

objectAttributeFilterobject nullable

Optional equality filter on the object's attributes, e.g. {"status":"SUCCEEDED"}.

objectTimeAttributestring nullable

Required when signalType is CUSTOM_OBJECT: the attribute holding the business timestamp to measure against.

objectValueAttributestring nullable

The numeric object attribute to aggregate. Required when signalType is CUSTOM_OBJECT and aggregation is not COUNT.

Response

Success

rootIdstring required

Stable id for this metric across versions. Pass it back to edit the metric.

versioninteger required

Version number; every edit creates a new one.

status'ACTIVE' | 'SUPERSEDED' required
namestring required
signalType'CDP_EVENT' | 'CUSTOM_OBJECT' | 'EXTRACTED_VARIABLE' required
aggregation'COUNT' | 'SUM' | 'AVERAGE' | 'MAX' required
roiEnabledboolean required
eventNamestring nullable required
valuePropertystring nullable required
valueSource'EVENT_PROPERTY' | 'RELATED_OBJECT' required
valueObjectTypeIdstring nullable required
valueRefPropertystring nullable required
variableIdstring nullable required
objectTypeIdstring nullable required
objectAttributeFilterobject nullable required
objectTimeAttributestring nullable required
objectValueAttributestring nullable required
windowHoursinteger required

Hours after the first outbound message in which a signal still counts. Fixed at 48.

createdAtstring required

ISO 8601 timestamp of this version.

Changes