Skip to content Skip to navigation Skip to topbar

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 an account under a category, sourced from an upstream entity — selected via the entityMetadata.sourceType discriminator, which determines the required shape of entityMetadata. Only the MEASURE category is supported for now.

For sources with a resolvable field-path concept, validates that entityMetadata.field resolves on the entity's latest active version by calling that source's own resolution API (the Intelligence fetch-operator API for sourceType: INTELLIGENCE_OPERATOR), then performs an idempotent upsert keyed on (accountSid, category, name). entityMetadata.sourceType plus that variant's own identity field (operatorId for INTELLIGENCE_OPERATOR) must match the existing registration's owner for the upsert to succeed — a mismatch returns 409. Enforces the per-account, per-category capacity limit.

Request

Authentication

Basic Auth

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

categoryenum<string>

required

The type of field being registered. Only MEASURE is supported.

Possible values:

MEASURE

namestring

required

Customer-facing name for the field; becomes the ClickHouse Map key and the platform field alias. Unique per account across every sourceType — the Map key namespace is account-global.

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

descriptionstring

Optional

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

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

entityMetadata

oneOf:

required

Reference to the upstream entity that sources this field. Shape is selected by the sourceType discriminator and owned by that upstream, not by this API — adding a new upstream means adding a variant here, not changing the request shape.

Every variant carries sourceType via EntityMetadataBase, so a client that does not recognise a newly added variant can still deserialize the common fields rather than failing outright.

The owner check for idempotent upserts is scoped to sourceType plus that variant's own identity field (operatorId for INTELLIGENCE_OPERATOR); a mismatch against an existing registration's owner returns 409.

Show entityMetadata properties

Responses

200201400401403409429500

The name was already registered for this operator and was updated in-place.

Schema

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

TTID for conversation insights custom field mapping

Example: convinsights_mapping_01m31967b7em08vh1pqgbam3mj

categoryenum<string>

Optional

The type of field being registered. Only MEASURE is supported.

Possible values:

MEASURE

namestring

Optional

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

entityMetadata

oneOf:

Optional

Reference to the upstream entity that sources this field. Shape is selected by the sourceType discriminator and owned by that upstream, not by this API — adding a new upstream means adding a variant here, not changing the request shape.

Every variant carries sourceType via EntityMetadataBase, so a client that does not recognise a newly added variant can still deserialize the common fields rather than failing outright.

The owner check for idempotent upserts is scoped to sourceType plus that variant's own identity field (operatorId for INTELLIGENCE_OPERATOR); a mismatch against an existing registration's owner returns 409.

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 materially modified in-place. Null until the first update-in-place.

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

Newly registered.

Schema

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

TTID for conversation insights custom field mapping

Example: convinsights_mapping_01m31967b7em08vh1pqgbam3mj

categoryenum<string>

Optional

The type of field being registered. Only MEASURE is supported.

Possible values:

MEASURE

namestring

Optional

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

entityMetadata

oneOf:

Optional

Reference to the upstream entity that sources this field. Shape is selected by the sourceType discriminator and owned by that upstream, not by this API — adding a new upstream means adding a variant here, not changing the request shape.

Every variant carries sourceType via EntityMetadataBase, so a client that does not recognise a newly added variant can still deserialize the common fields rather than failing outright.

The owner check for idempotent upserts is scoped to sourceType plus that variant's own identity field (operatorId for INTELLIGENCE_OPERATOR); a mismatch against an existing registration's owner returns 409.

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 materially modified in-place. Null until the first update-in-place.

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

Bad 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

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

The name is already registered for this account with different attributes. Names are unique per account, so a name can only be re-registered idempotently by the same owner.

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

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        operatorId: "OPxxxx",
19        operatorName: "Sentiment Analysis",
20        field: "leadScore",
21      },
22    });
23
24  console.log(customFieldMapping.id);
25}
26
27createCustomFieldMapping();

Response

1{
2  "category": "MEASURE",
3  "createdAt": "2009-07-06T20:30:00Z",
4  "description": "Lead quality score derived from sentiment analysis",
5  "entityMetadata": {},
6  "id": "id",
7  "name": "LeadScore",
8  "updatedAt": "2009-07-06T20:30:00Z"
9}