TWtwilio
TwilioInsightsConfig

Update a custom field mapping

Changed on

Partially updates an existing custom field mapping. Only the properties present in the body are changed. The updatable properties depend on the mapping's sourceType; for INTELLIGENCE_OPERATOR, only entityMetadata.intelligenceOperator.field can be updated today.

The new field is validated the same way as at registration: it must be one or two .-separated segments of letters, digits and _, and resolve to a number or integer property in the output schema of the operator's latest active version.

The mapping's id, name, category, createdAt and owning entity never change. Sending a field value equal to the current one is a no-op that returns 200 without modifying the mapping, so the operation is idempotent. Supply If-Match with the ETag returned by GET, POST or a previous PATCH to guard against concurrent updates.

Values already ingested are not recomputed; results processed after the update use the new field.

patch/v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}

Request

  • Base URL
    https://insights.twilio.com
  • URL
    https://insights.twilio.com/v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}
  • Auth
    HTTP basic

Path parameters

mappingIdstring required
Example:convinsights_mapping_01m31967b7em08vh1pqgbam3mj

The unique identifier of the custom field mapping, as returned in id when the mapping was created.

Headers

If-Matchstring
Example:"2026-08-13T14:30:00Z"

ETag of the custom field mapping, as returned in the ETag response header. When supplied, the update is applied only if the mapping has not changed since that ETag was issued; otherwise 412 is returned.

Request body

Example request

{
  "entityMetadata": {
    "intelligenceOperator": {
      "field": "scores.leadScore"
    }
  }
}

Response

The mapping was updated, or the supplied values already matched and nothing changed.

idstring

The unique identifier of the custom field mapping.

category'MEASURE' required

The category of the custom field. Supported values:

  • MEASURE: a numeric value that can be aggregated and queried as a measure in Conversations Insights.
namestring required

Name of the custom field, unique within the account.

descriptionstring

Optional, free-text description supplied at registration time. Display-only — not part of any uniqueness check.

createdAtstring date-time

When the mapping was registered.

updatedAtstring date-time nullable

When the mapping was last modified via PATCH. Null until the first update.

Example response

{
  "id": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj",
  "name": "LeadScore",
  "description": "Lead quality score derived from sentiment analysis",
  "entityMetadata": {
    "intelligenceOperator": {
      "operatorId": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
      "operatorName": "Sentiment Analysis",
      "field": "leadScore"
    }
  },
  "createdAt": "2026-08-13T14:30:00Z",
  "updatedAt": "2026-09-30T10:00:00Z"
}

Changes