Register a custom measure 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.

POST/v3/ControlPlane/ConversationInsights/CustomFieldMappings

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

Registers a custom field for the account. entityMetadata.sourceType selects where the field's value comes from, and the matching property on entityMetadata (intelligenceOperator for INTELLIGENCE_OPERATOR) carries its details. Only the MEASURE category is supported for now.

The request is validated before the mapping is created:

name contains only letters, digits and _, and is not already registered for the account (otherwise 409);
description, when present, is at most 150 characters;
for INTELLIGENCE_OPERATOR, the operator has an active version with outputFormat JSON, and entityMetadata.intelligenceOperator.field is one or two .-separated segments that resolve to a number or integer property in that version's output schema (otherwise 400);
the account has a free slot in the category; by default an account can register up to 3 custom measures (otherwise 403). Use GET /v3/ControlPlane/ConversationInsights/CustomFieldMappingsCapacity to check the remaining slots.

Create-only: if a mapping with the same name already exists for the account, 409 is returned with the existing mapping's id and nothing is changed. To modify an existing mapping, use PATCH /v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}.

Request

Authentication

Basic Auth

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

categoryenum<string>

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.

Possible values:

MEASURE

namestring

required

Name of the custom field, used to reference it in Insights queries. Contains only letters, digits and _, and must not be empty. Must be unique within the account across every sourceType; registering an existing name returns 409. Cannot be changed after registration.

Example: LeadScorePattern: ^[A-Za-z0-9_]+$

descriptionstring

Optional

Optional, free-text description of this custom field mapping, up to 150 characters. Display-only — not part of any uniqueness check.

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

entityMetadataobject

required

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

Responses

201400401403409429500503

The custom field mapping was created.

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 required property (category, name, entityMetadata, entityMetadata.sourceType, operatorId, field) is missing, or category / sourceType is not a supported value;
name is empty or contains characters other than letters, digits and _, or description is longer than 150 characters;
entityMetadata does not carry the property that matches its sourceType, or carries any other property;
operatorId is not a valid operator ID;
the operator has no active version or its outputFormat is not JSON;
field has more than two segments, contains unsupported characters, or does not resolve to a number or integer property in the operator's output schema.

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

The account has reached its limit of custom measures (default 3), or does not have access to custom field mappings.

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

A mapping with this name already exists for the account. Names are unique per account across every sourceType, so this applies regardless of which entity either mapping is sourced from or whether the payload matches. Nothing is changed. params.id carries the existing mapping's id; use PATCH on it to modify the mapping.

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 registration could not be retrieved from Conversational Intelligence. No mapping was created; 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

Register a custom measure 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 createCustomFieldMapping() {
11  const customFieldMapping =
12    await client.insights.v3.customFieldMappings.create({
13      category: "MEASURE",
14      name: "LeadScore",
15      description: "Lead quality score derived from sentiment analysis",
16      entityMetadata: {
17        sourceType: "INTELLIGENCE_OPERATOR",
18        intelligenceOperator: {
19          operatorId: "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
20          operatorName: "Sentiment Analysis",
21          field: "leadScore",
22        },
23      },
24    });
25
26  console.log(customFieldMapping.id);
27}
28
29createCustomFieldMapping();

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": "LeadScore",
15  "updatedAt": "2026-09-30T10:00:00Z"
16}