Update a custom field mapping

(new)

Public beta

Conversation Insights, including the APIs, is currently available as a public beta release and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

Conversation Insights is not PCI compliant or a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA or PCI.

Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

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

Base url: https://insights.twilio.com (base url)

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.

Request

Authentication

Basic Auth

Headers

Property nameTypeRequiredPIIDescription

if-Matchstring

Optional

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.

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

Path parameters

Property nameTypeRequiredPIIDescription

mappingIdstring

required

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

Example: convinsights_mapping_01m31967b7em08vh1pqgbam3mj

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

entityMetadataobject

Optional

Updatable subset of entityMetadata. sourceType must equal the mapping's current sourceType (it cannot be changed), and the property named for that source carries the fields to update:

| sourceType | Update property | Updatable fields | |---|---|---| | INTELLIGENCE_OPERATOR | intelligenceOperator | field |

Show entityMetadata properties

Responses

200400401403404409412429500503

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

Schema

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

The unique identifier of the custom field mapping.

Example: convinsights_mapping_01m31967b7em08vh1pqgbam3mj

categoryenum<string>

Optional

The category of the custom field. Supported values:

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

Possible values:

MEASURE

namestring

Optional

Name of the custom field, unique within the account.

Example: LeadScore

descriptionstring

Optional

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

Example: Lead quality score derived from sentiment analysisMax length: 150

entityMetadataobject

Optional

Identifies the entity that supplies this field's value. sourceType selects the source, and the property named for that source carries its details. Exactly that one source property must be present:

| sourceType | Required property | |---|---| | INTELLIGENCE_OPERATOR | intelligenceOperator |

A request whose sourceType doesn't match the source property it sends, or that sends any other property, is rejected with 400.

Show entityMetadata properties

createdAtstring<date-time>

Optional

When the mapping was registered.

Example: 2026-08-13T14:30:00Z

updatedAtstring<date-time>

Optional

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

Example: 2026-09-30T10:00:00Z

The request is invalid. One of:

a malformed body, an empty body or source object (nothing to update), a missing entityMetadata.sourceType, or a field that fails its pattern;
a property that cannot be updated (for example name, category, operatorId) is present;
entityMetadata.sourceType does not match the mapping's current sourceType, or is not supported for updates;
the new field does not resolve to a number or integer property on the operator's latest active version, or the operator no longer has an active JSON version.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Unauthorized request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Forbidden request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Resource not found

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

The mapping was modified by a concurrent request while this update was being applied. Fetch the mapping and retry.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

The If-Match value does not match the mapping's current ETag.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

The operator details needed to validate the update could not be retrieved from Conversational Intelligence. The mapping was not changed; retry after the Retry-After interval.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Update a custom field mapping

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function patchCustomFieldMapping() {
11  const customFieldMapping = await client.insights.v3
12    .customFieldMappings("convinsights_mapping_01m31967b7em08vh1pqgbam3mj")
13    .patch({
14      entityMetadata: {
15        sourceType: "INTELLIGENCE_OPERATOR",
16        intelligenceOperator: {
17          field: "scores.leadScore",
18        },
19      },
20    });
21
22  console.log(customFieldMapping.id);
23}
24
25patchCustomFieldMapping();

Response

1{
2  "category": "MEASURE",
3  "createdAt": "2026-08-13T14:30:00Z",
4  "description": "Lead quality score derived from sentiment analysis",
5  "entityMetadata": {
6    "sourceType": "INTELLIGENCE_OPERATOR",
7    "intelligenceOperator": {
8      "operatorId": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
9      "operatorName": "Sentiment Analysis",
10      "field": "leadScore"
11    }
12  },
13  "id": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj",
14  "name": "Miss Christine Morgan",
15  "updatedAt": "2026-09-30T10:00:00Z"
16}