{ "openapi": "3.0.1", "info": { "title": "Twilio - Insights", "description": "The Twilio Insights v3 API provides semantic query access to Conversations\nanalytics data. Resources include synchronous Query, Metadata, and asynchronous\nQueryJobs for long-running queries.\n", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio Support", "url": "https://support.twilio.com", "email": "support@twilio.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.1.0", "x-twilio": { "apiStandards": "v1.0" } }, "servers": [ { "url": "https://insights.twilio.com" } ], "security": [ { "basic_apikey_or_accountsid": [] } ], "tags": [ { "name": "TwilioInsights", "description": "Twilio Insights synchronous Query and Metadata resources." }, { "name": "TwilioInsightsAsync", "description": "Twilio Insights asynchronous QueryJobs resource (long-running query operations)." }, { "name": "TwilioInsightsConfig", "description": "Twilio Insights Config API for custom measure field mapping registration." } ], "components": { "securitySchemes": { "basic_apikey_or_accountsid": { "scheme": "basic", "type": "http", "description": "This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing." } }, "responses": { "UnprocessableContentError": { "description": "Unprocessable content (idempotency key payload mismatch)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "BadRequestError": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "UnauthorizedError": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "ForbiddenError": { "description": "Forbidden request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "RateLimitError": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "headers": { "X-Rate-Limit-Limit": { "schema": { "type": "string" } }, "X-Rate-Limit-Remaining": { "schema": { "type": "string" } }, "X-Rate-Limit-Config": { "schema": { "type": "string" } } }, "schemas": { "PaginationMeta": { "type": "object", "description": "The pagination metadata containing navigation tokens and result information.\nBy convention, this schema should be added to the response payload's\n'meta' attribute.\n", "required": [ "key", "pageSize" ], "properties": { "key": { "type": "string", "nullable": false, "description": "The key of the list property contains the actual data items.\nThis enables programmatic iteration over paginated results.\n", "example": "items" }, "pageSize": { "type": "integer", "nullable": false, "description": "The actual number of items returned in this response.\nMay be less than the requested pageSize for the last page.\n", "example": 20 }, "previousToken": { "type": "string", "nullable": true, "description": "Token to fetch the previous page of results.\nOnly included if there is a previous page, otherwise omitted.\n", "example": "eyJwYWdlIjowLCJxdWVyeSI6ImJvb2tzIn0=" }, "nextToken": { "type": "string", "nullable": true, "description": "Token to fetch the next page of results.\nOnly included if there is a next page, otherwise omitted.\n", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } }, "QueryDefinition": { "type": "object", "description": "Structured query definition that specifies what data to retrieve and how to filter, group, and order it", "properties": { "measures": { "type": "array", "description": "Array of measures to retrieve, representing quantitative values or metrics to be calculated", "items": { "type": "string" }, "example": [ "OperatorResult.Count" ] }, "dimensions": { "type": "array", "description": "Array of dimensions to retrieve, representing categorical attributes for grouping and organizing data", "items": { "type": "string" }, "example": [ "DateCreated", "OperatorResults" ] }, "filters": { "type": "array", "description": "Nested filter conditions. Always use `op` and `expressions`.", "items": { "type": "object", "required": [ "expressions" ], "properties": { "op": { "type": "string", "enum": [ "AND", "OR", "EQ", "NE", "GT", "LT", "IN" ], "example": "AND" }, "expressions": { "type": "array", "items": { "type": "object", "required": [ "op", "field" ], "properties": { "op": { "type": "string", "enum": [ "AND", "OR", "EQ", "NE", "GT", "LT", "IN" ], "example": "IN" }, "field": { "type": "string", "example": "OperatorResult.Value" }, "values": { "type": "array", "items": { "type": "string" }, "example": [ "positive", "negative" ] } } } } } } }, "orderBy": { "type": "array", "description": "Specifications for sorting the query results by specific fields in ascending or descending order", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Dimension or measure to order by", "example": "OperatorResults.CreatedDate" }, "direction": { "type": "string", "description": "Sort order direction, ascending or descending", "enum": [ "ASC", "DESC" ], "example": "DESC" } } } } } }, "InsightsQueryRequest": { "type": "object", "required": [ "query" ], "properties": { "domain": { "type": "string", "example": "Conversations", "description": "The business domain to execute the query against" }, "query": { "$ref": "#/components/schemas/QueryDefinition" } } }, "InsightsQueryResponse": { "type": "object", "properties": { "domain": { "type": "string", "example": "Insights", "description": "Indicates the business domain the query was executed against" }, "items": { "type": "array", "description": "Array of result objects containing the query results. Each object contains properties matching the requested measures and dimensions.", "items": { "type": "object", "description": "Query result object with dynamic properties based on requested measures and dimensions.", "additionalProperties": { "description": "Dynamic property values based on requested measures and dimensions." } }, "example": [ { "Id": "conv1", "Languages": [ "en" ], "Channels": [ "voice" ], "OperatorResult.Value": "positive" }, { "Id": "conv2", "Languages": [ "en", "es" ], "Channels": [ "chat" ], "OperatorResult.Value": "negative" } ] }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "InsightsMetadataResponse": { "type": "object", "description": "Response containing metadata about available cubes, measures, and dimensions for a domain", "properties": { "domain": { "type": "string", "example": "Insights", "description": "The business domain name for which metadata is being provided" }, "cubes": { "type": "array", "description": "List of data cubes available in the domain, each containing measures and dimensions", "items": { "type": "object", "required": [ "name", "measures", "dimensions" ], "properties": { "name": { "type": "string", "description": "Name of the cube, used as a reference in queries" }, "description": { "type": "string", "description": "Human-readable description of what the cube represents" }, "measures": { "type": "array", "description": "List of measures available in the cube, representing quantitative values that can be aggregated", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Identifier used to reference this measure in queries" }, "description": { "type": "string", "description": "Detailed explanation of what this measure represents" }, "type": { "type": "string", "description": "Type of the measure" }, "aggregation": { "type": "string", "description": "Aggregation type for the measure (e.g., sum, count, average)" } } } }, "dimensions": { "type": "array", "description": "List of dimensions available in the cube, representing categorical attributes for grouping data", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Identifier used to reference this dimension in queries" }, "description": { "type": "string", "description": "Detailed explanation of what this dimension represents" }, "type": { "type": "string", "description": "Data type of the dimension (e.g., string, number, boolean, date)" } } } } } } } } }, "LongRunningOperationStatus": { "description": "The valid status values for long-running operations.", "type": "string", "enum": [ "PENDING", "RUNNING", "CANCELLED", "COMPLETED", "FAILED" ] }, "OperationError": { "description": "The error details for a failed operation, embedded inside a 200 OK operation envelope.", "type": "object", "required": [ "code", "message", "httpStatusCode" ], "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32", "example": 50001 }, "message": { "description": "A human readable error message", "type": "string", "example": "Query execution timeout exceeded" }, "httpStatusCode": { "description": "HTTP status code that would have been returned for a synchronous failure", "type": "integer", "format": "int32", "example": 504 }, "detail": { "description": "Additional context about the failure", "type": "string", "nullable": true, "example": "Query exceeded the 120s execution limit." } } }, "QueryJobSubmitResponse": { "description": "The initial 202 response for an async query submission.\nConforms to LongRunningOperation202Response from Twilio API Standards.\n", "type": "object", "additionalProperties": true, "required": [ "operationId", "status", "statusUrl", "createdAt" ], "properties": { "operationId": { "type": "string", "format": "Proc_JobTtid", "description": "The unique identifier for the asynchronous query operation, in TTID format.", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "status": { "$ref": "#/components/schemas/LongRunningOperationStatus" }, "statusUrl": { "type": "string", "format": "uri", "description": "The URI to poll for operation status.", "example": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "createdAt": { "type": "string", "format": "date-time", "description": "The time when the operation was accepted, in RFC 3339 UTC format.", "example": "2026-05-25T14:30:00Z" } } }, "QueryJobStatusResponse": { "description": "The status response for an async query operation.\nConforms to LongRunningOperationStatusResponse from Twilio API Standards.\n", "type": "object", "additionalProperties": true, "required": [ "operationId", "status", "createdAt" ], "properties": { "operationId": { "type": "string", "format": "Proc_JobTtid", "description": "The unique identifier for the asynchronous query operation, in TTID format.", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "status": { "$ref": "#/components/schemas/LongRunningOperationStatus" }, "statusUrl": { "type": "string", "format": "uri", "example": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-05-25T14:30:00Z" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "The time when the operation reached a terminal state (CANCELLED, COMPLETED, or FAILED), in RFC 3339 UTC format. Null while the operation is still PENDING or RUNNING.", "example": "2026-05-25T14:32:17Z" }, "error": { "nullable": true, "description": "The error details, present only when status is FAILED.", "allOf": [ { "$ref": "#/components/schemas/OperationError" } ] }, "resultUrl": { "type": "string", "format": "uri", "nullable": true, "description": "The URL to retrieve query results, present only when status is COMPLETED.\nSupports pagination via the pageSize and pageToken query parameters.\n", "example": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r/Results" }, "resultId": { "type": "string", "nullable": true, "description": "The identifier of the results resource, present only when status is COMPLETED.\nEqual to operationId, since results are keyed by the operation ID.\n", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" }, "resultRetentionPeriod": { "type": "string", "format": "duration", "nullable": true, "description": "The duration for how long results are retained, in ISO 8601 format.", "example": "P7D" } } }, "QueryJobListResponse": { "description": "A paginated list of async query operations for the account.", "type": "object", "required": [ "items", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/QueryJobStatusResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "MappingCategory": { "type": "string", "description": "The category of the custom field. Supported values:\n- `MEASURE`: a numeric value that can be aggregated and queried as a\n measure in Conversations Insights.\n", "enum": [ "MEASURE" ] }, "SourceType": { "type": "string", "description": "The kind of entity that supplies the custom field's value. Each value has\na matching property on `entityMetadata` that carries that source's\ndetails. Supported values:\n- `INTELLIGENCE_OPERATOR`: the value is read from the output of a\n Conversational Intelligence operator. Details go in\n `entityMetadata.intelligenceOperator`.\n", "enum": [ "INTELLIGENCE_OPERATOR" ] }, "IntelligenceOperatorSource": { "type": "object", "description": "Details of a custom field whose value is read from a Conversational\nIntelligence operator's output. The operator must:\n- have an active version;\n- have `outputFormat` `JSON` (`TEXT` and `CLASSIFICATION` operators\n are rejected).\n\nRequests that reference an ineligible operator are rejected with `400`.\n", "required": [ "operatorId", "field" ], "properties": { "operatorId": { "type": "string", "description": "The ID of the Conversational Intelligence operator whose output\nsupplies this field's value. Must match\n`^intelligence_operator_[0-7][0-9a-z]{25}$`. Cannot be changed after\nregistration.\n", "pattern": "^intelligence_operator_[0-7][0-9a-z]{25}$", "example": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b" }, "operatorName": { "type": "string", "description": "Optional, display-only name of the operator. Stored as supplied and\nnot validated against the operator.\n", "example": "Sentiment Analysis" }, "field": { "type": "string", "description": "Path to the property in the operator's output schema that supplies\nthis field's value. Rules:\n- one or two segments separated by `.` \u2014 a top-level property\n (`leadScore`) or one level of nesting (`scores.leadScore`);\n- each segment contains only letters, digits and `_`; array\n indexing (such as `items[0]`) is not supported;\n- the path must exist in the output schema of the operator's\n latest active version and resolve to a property of type `number`\n or `integer`.\n", "pattern": "^[A-Za-z0-9_]+(\\.[A-Za-z0-9_]+)?$", "example": "leadScore" } } }, "EntityMetadata": { "type": "object", "description": "Identifies the entity that supplies this field's value. `sourceType`\nselects the source, and the property named for that source carries its\ndetails. Exactly that one source property must be present:\n\n| `sourceType` | Required property |\n|---|---|\n| `INTELLIGENCE_OPERATOR` | `intelligenceOperator` |\n\nA request whose `sourceType` doesn't match the source property it sends,\nor that sends any other property, is rejected with `400`.\n", "additionalProperties": false, "required": [ "sourceType" ], "properties": { "sourceType": { "$ref": "#/components/schemas/SourceType" }, "intelligenceOperator": { "$ref": "#/components/schemas/IntelligenceOperatorSource" } } }, "CustomFieldMappingRequest": { "type": "object", "description": "Registration payload for a single custom field. The mapping is created in\nthe account identified by the request's credentials.\n", "required": [ "category", "name", "entityMetadata" ], "properties": { "category": { "$ref": "#/components/schemas/MappingCategory" }, "name": { "type": "string", "description": "Name of the custom field, used to reference it in Insights queries.\nContains only letters, digits and `_`, and must not be empty.\nMust be unique within the account across every `sourceType`;\nregistering an existing name returns `409`. Cannot be changed after\nregistration.\n", "pattern": "^[A-Za-z0-9_]+$", "example": "LeadScore" }, "description": { "type": "string", "description": "Optional, free-text description of this custom field mapping, up to\n150 characters. Display-only \u2014 not part of any uniqueness check.\n", "maxLength": 150, "example": "Lead quality score derived from sentiment analysis" }, "entityMetadata": { "$ref": "#/components/schemas/EntityMetadata" } } }, "CustomFieldMappingUpdateRequest": { "type": "object", "description": "Partial update of a custom field mapping. Only properties present in the\nbody are changed; absent properties keep their current value. The body\nmust contain at least one change: an empty body is rejected with `400`.\nProperties that cannot be updated (such as `name`, `category` or\n`operatorId`) are rejected with `400` rather than ignored.\n", "additionalProperties": false, "minProperties": 1, "properties": { "entityMetadata": { "$ref": "#/components/schemas/EntityMetadataUpdate" } } }, "EntityMetadataUpdate": { "type": "object", "description": "Updatable subset of `entityMetadata`. `sourceType` must equal the\nmapping's current `sourceType` (it cannot be changed), and the property\nnamed for that source carries the fields to update:\n\n| `sourceType` | Update property | Updatable fields |\n|---|---|---|\n| `INTELLIGENCE_OPERATOR` | `intelligenceOperator` | `field` |\n", "additionalProperties": false, "required": [ "sourceType" ], "properties": { "sourceType": { "$ref": "#/components/schemas/SourceType" }, "intelligenceOperator": { "$ref": "#/components/schemas/IntelligenceOperatorSourceUpdate" } } }, "IntelligenceOperatorSourceUpdate": { "type": "object", "description": "Updatable fields of a custom field mapping sourced from a Conversational\nIntelligence operator. At least one field must be present. Currently\nonly `field` can be modified; `operatorId` and `operatorName` cannot be\nupdated.\n", "additionalProperties": false, "minProperties": 1, "properties": { "field": { "type": "string", "description": "New path to the property in the operator's output schema. Follows the\nsame rules as `field` at registration: one or two `.`-separated\nsegments of letters, digits and `_`, resolving to a `number` or\n`integer` property on the operator's latest active version.\n", "pattern": "^[A-Za-z0-9_]+(\\.[A-Za-z0-9_]+)?$", "example": "scores.leadScore" } } }, "CustomFieldMappingResponse": { "type": "object", "description": "A registered custom field mapping.", "required": [ "category", "name", "entityMetadata" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the custom field mapping.", "example": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj" }, "category": { "$ref": "#/components/schemas/MappingCategory" }, "name": { "type": "string", "description": "Name of the custom field, unique within the account.", "example": "LeadScore" }, "description": { "type": "string", "description": "Optional, free-text description supplied at registration time.\nDisplay-only \u2014 not part of any uniqueness check.\n", "maxLength": 150, "example": "Lead quality score derived from sentiment analysis" }, "entityMetadata": { "$ref": "#/components/schemas/EntityMetadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the mapping was registered.", "example": "2026-08-13T14:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the mapping was last modified via `PATCH`. Null until the first update.", "example": "2026-09-30T10:00:00Z" } } }, "CustomFieldMappingsList": { "type": "object", "description": "A page of custom field mappings registered for the account. The mappings\nare under `items`, and `meta.key` is `items`.\n", "required": [ "items", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldMappingResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "CustomFieldCapacity": { "type": "object", "description": "Custom field mapping slot capacity for the account, by category. Only the\n`measure` category is supported for now; the object is empty when custom\nmeasures are not available for the account.\n", "properties": { "measure": { "$ref": "#/components/schemas/CategoryCapacity" } } }, "CategoryCapacity": { "type": "object", "description": "Slots consumed and remaining for the measure category. By default an\naccount can register up to 3 custom measures, so `consumed + remaining`\nis the account's limit. Registering a new mapping when `remaining` is\n`0` returns `403`.\n", "required": [ "consumed", "remaining" ], "properties": { "consumed": { "type": "integer", "minimum": 0, "description": "Number of custom field mapping slots already registered.", "example": 1 }, "remaining": { "type": "integer", "minimum": 0, "description": "Number of custom field mapping slots still available.", "example": 2 } } } } }, "paths": { "/v3/InsightsDomains/Conversations/Query": { "servers": [ { "url": "https://insights.twilio.com" } ], "post": { "summary": "Execute a synchronous semantic query", "description": "Execute a semantic query against the Conversations domain.\nReturns results inline. For long-running queries, use the QueryJobs endpoint.\n", "tags": [ "TwilioInsights" ], "operationId": "CreateQueryResults", "parameters": [ { "name": "pageSize", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 20, "format": "int32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryRequest" } } } }, "responses": { "200": { "description": "Successful query response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] }, "get": { "summary": "Retrieve paginated query results", "description": "Retrieve subsequent pages of a synchronous query using a page token.", "tags": [ "TwilioInsights" ], "operationId": "FetchQueryResults", "parameters": [ { "name": "pageToken", "in": "query", "description": "Pagination token", "required": true, "schema": { "type": "string", "example": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } ], "responses": { "200": { "description": "Successful query response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/InsightsDomains/Conversations/Metadata": { "servers": [ { "url": "https://insights.twilio.com" } ], "get": { "summary": "Retrieve domain metadata", "description": "Returns available cubes, measures, and dimensions for the Conversations domain.", "tags": [ "TwilioInsights" ], "operationId": "FetchMetadata", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsMetadataResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/InsightsDomains/Conversations/QueryJobs": { "servers": [ { "url": "https://insights.twilio.com" } ], "post": { "summary": "Submit an asynchronous query", "description": "Submit a long-running semantic query against the Conversations domain.\nReturns 202 Accepted with an operationId and a Location header pointing\nto the QueryJobs status endpoint for polling.\n", "tags": [ "TwilioInsightsAsync" ], "operationId": "CreateQueryJob", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "description": "A client-generated UUIDv7 key that ensures idempotent behavior.\nSubmitting the same key with an identical request returns the same operation\nwithout re-execution. Scoped to Account + Region. Retained for 24 hours.\n", "schema": { "type": "string", "format": "uuid", "example": "01890a5d-aa0f-7c80-b8e6-0242ac140004" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryRequest" } } } }, "responses": { "202": { "description": "Async query accepted", "headers": { "Location": { "description": "URI to poll for operation status.", "schema": { "type": "string", "format": "uri", "example": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r" } }, "Retry-After": { "description": "Seconds before the client should first poll.", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryJobSubmitResponse" }, "example": { "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r", "status": "PENDING", "statusUrl": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r", "createdAt": "2026-05-25T14:30:00Z" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "422": { "description": "Unprocessable content (idempotency key payload mismatch)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] }, "get": { "summary": "Retrieve a list of asynchronous queries", "description": "Returns a paginated list of asynchronous query operations for the authenticated account.\nOptionally filter by status.\n", "tags": [ "TwilioInsightsAsync" ], "operationId": "ListQueryJobs", "parameters": [ { "name": "pageSize", "in": "query", "description": "The maximum number of resources to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "pageToken", "in": "query", "description": "Token for pagination", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "The operation status to filter results by.", "required": false, "schema": { "$ref": "#/components/schemas/LongRunningOperationStatus" } } ], "responses": { "200": { "description": "Paginated list of async query operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryJobListResponse" }, "example": { "items": [ { "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r", "status": "RUNNING", "createdAt": "2026-05-25T14:30:00Z", "statusUrl": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r", "resultId": "proc_job_01h9d8r0vte3hz8tykdj329t7r" } ], "meta": { "key": "items", "pageSize": 1 } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/InsightsDomains/Conversations/QueryJobs/{operationId}": { "servers": [ { "url": "https://insights.twilio.com" } ], "get": { "summary": "Retrieve asynchronous query status and results", "description": "Poll the operation status. When status is COMPLETED, the response\nincludes query results inline.\nWhen FAILED, the response includes error details conforming to the\nOperationError schema.\n", "tags": [ "TwilioInsightsAsync" ], "operationId": "FetchQueryJobStatus", "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "The unique identifier for the asynchronous query operation, in TTID format.", "schema": { "type": "string", "format": "Proc_JobTtid", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" } } ], "responses": { "200": { "description": "Operation status (may include results if COMPLETED)", "headers": { "Retry-After": { "description": "Seconds before the client should poll again (present while PENDING/RUNNING).", "schema": { "type": "integer", "example": 10 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryJobStatusResponse" }, "examples": { "running": { "summary": "Operation still running", "value": { "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r", "status": "RUNNING", "createdAt": "2026-05-25T14:30:00Z", "statusUrl": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r" } }, "completed": { "summary": "Operation completed", "value": { "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r", "status": "COMPLETED", "createdAt": "2026-05-25T14:30:00Z", "completedAt": "2026-05-25T14:32:17Z", "statusUrl": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r", "resultRetentionPeriod": "P7D" } }, "failed": { "summary": "Operation failed", "value": { "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r", "status": "FAILED", "createdAt": "2026-05-25T14:30:00Z", "completedAt": "2026-05-25T14:30:12Z", "statusUrl": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r", "error": { "code": 50001, "message": "Query execution timeout exceeded", "httpStatusCode": 504, "detail": "Query exceeded the 120s execution limit for this account." } } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/InsightsDomains/Conversations/QueryJobs/{operationId}/Results": { "servers": [ { "url": "https://insights.twilio.com" } ], "get": { "summary": "Retrieve asynchronous query results", "description": "Retrieve paginated results for a completed asynchronous query operation.\nThe resultUrl in the status response points to this endpoint.\nReturns 404 if the operation is not yet COMPLETED or has expired.\n", "tags": [ "TwilioInsightsAsync" ], "operationId": "FetchQueryJobResults", "parameters": [ { "name": "operationId", "in": "path", "required": true, "description": "The unique identifier for the asynchronous query operation, in TTID format.", "schema": { "type": "string", "format": "Proc_JobTtid", "example": "proc_job_01h9d8r0vte3hz8tykdj329t7r" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of resources to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "pageToken", "in": "query", "description": "Token for pagination", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Query results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsQueryResponse" }, "example": { "domain": "Conversations", "items": [ { "Id": "conv1", "Languages": [ "en" ], "Channels": [ "voice" ], "OperatorResult.Value": "positive" }, { "Id": "conv2", "Languages": [ "en", "es" ], "Channels": [ "chat" ], "OperatorResult.Value": "negative" } ], "meta": { "key": "items", "pageSize": 2, "nextToken": "eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=" } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/ControlPlane/ConversationInsights/CustomFieldMappings": { "servers": [ { "url": "https://insights.twilio.com" } ], "post": { "summary": "Register a custom measure field mapping", "description": "Registers a custom field for the account. `entityMetadata.sourceType`\nselects where the field's value comes from, and the matching property on\n`entityMetadata` (`intelligenceOperator` for `INTELLIGENCE_OPERATOR`)\ncarries its details. Only the `MEASURE` category is supported for now.\n\nThe request is validated before the mapping is created:\n- `name` contains only letters, digits and `_`, and is not already\n registered for the account (otherwise `409`);\n- `description`, when present, is at most 150 characters;\n- for `INTELLIGENCE_OPERATOR`, the operator has an active version with\n `outputFormat` `JSON`, and `entityMetadata.intelligenceOperator.field`\n is one or two `.`-separated segments that resolve to a `number` or\n `integer` property in that version's output schema (otherwise `400`);\n- the account has a free slot in the category; by default an account can\n register up to 3 custom measures (otherwise `403`). Use\n `GET /v3/ControlPlane/ConversationInsights/CustomFieldMappingsCapacity`\n to check the remaining slots.\n\nCreate-only: if a mapping with the same `name` already exists for the\naccount, `409` is returned with the existing mapping's `id` and nothing\nis changed. To modify an existing mapping, use\n`PATCH /v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}`.\n", "tags": [ "TwilioInsightsConfig" ], "operationId": "CreateCustomFieldMapping", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldMappingRequest" }, "examples": { "measure_from_intelligence_operator": { "summary": "Register a custom measure sourced from an Intelligence operator", "value": { "category": "MEASURE", "name": "LeadScore", "description": "Lead quality score derived from sentiment analysis", "entityMetadata": { "sourceType": "INTELLIGENCE_OPERATOR", "intelligenceOperator": { "operatorId": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b", "operatorName": "Sentiment Analysis", "field": "leadScore" } } } } } } } }, "responses": { "201": { "description": "The custom field mapping was created.", "headers": { "ETag": { "description": "ETag of the new mapping; supply it as `If-Match` on `PATCH`.", "schema": { "type": "string", "example": "\"2026-08-13T14:30:00Z\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldMappingResponse" } } } }, "400": { "description": "The request is invalid. One of:\n- a required property (`category`, `name`, `entityMetadata`,\n `entityMetadata.sourceType`, `operatorId`, `field`) is missing, or\n `category` / `sourceType` is not a supported value;\n- `name` is empty or contains characters other than letters,\n digits and `_`, or `description` is longer than 150 characters;\n- `entityMetadata` does not carry the property that matches its\n `sourceType`, or carries any other property;\n- `operatorId` is not a valid operator ID;\n- the operator has no active version or its `outputFormat` is not\n `JSON`;\n- `field` has more than two segments, contains unsupported\n characters, or does not resolve to a `number` or `integer`\n property in the operator's output schema.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "example": { "code": 20050, "message": "The 'field' value 'leadScore' does not resolve on the latest active version of operator 'intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b'.", "httpStatusCode": 400, "userError": true } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "403": { "description": "The account has reached its limit of custom measures (default 3), or\ndoes not have access to custom field mappings.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "example": { "code": 20051, "message": "The account has reached its custom mapping capacity for category 'MEASURE'.", "httpStatusCode": 403, "userError": true } } } }, "409": { "description": "A mapping with this `name` already exists for the account. Names are\nunique per account across every `sourceType`, so this applies\nregardless of which entity either mapping is sourced from or whether\nthe payload matches. Nothing is changed. `params.id` carries the\nexisting mapping's `id`; use `PATCH` on it to modify the mapping.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "example": { "code": 20052, "message": "A custom field mapping named 'LeadScore' already exists for this account.", "httpStatusCode": 409, "userError": true, "params": { "category": "MEASURE", "name": "LeadScore", "id": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj" } } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "503": { "description": "The operator details needed to validate the registration could not\nbe retrieved from Conversational Intelligence. No mapping was\ncreated; retry after the `Retry-After` interval.\n", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "example": { "code": 20503, "message": "The service is temporarily unavailable. Please retry after a short delay.", "httpStatusCode": 503, "userError": false } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] }, "get": { "summary": "List custom measure field mappings for an account", "description": "Returns the custom field mappings registered for the account, one page at\na time. Use `pageSize` to limit the number of mappings returned, and pass\n`meta.nextToken` from a response as `pageToken` to fetch the next page.\nOn the last page, `meta.nextToken` is `null`.\n", "tags": [ "TwilioInsightsConfig" ], "operationId": "ListCustomFieldMappings", "parameters": [ { "name": "pageSize", "in": "query", "description": "The maximum number of resources to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "pageToken", "in": "query", "description": "Token for pagination", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of custom field mappings registered for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldMappingsList" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "403": { "description": "Forbidden request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/ControlPlane/ConversationInsights/CustomFieldMappings/{mappingId}": { "servers": [ { "url": "https://insights.twilio.com" } ], "get": { "summary": "Fetch a custom field mapping", "description": "Returns a single custom field mapping by its `mappingId`. The `ETag`\nresponse header identifies the mapping's current version; supply it as\n`If-Match` on `PATCH` to guard against concurrent updates.\n", "tags": [ "TwilioInsightsConfig" ], "operationId": "FetchCustomFieldMapping", "parameters": [ { "name": "mappingId", "in": "path", "required": true, "description": "The unique identifier of the custom field mapping, as returned in `id` when the mapping was created.", "schema": { "type": "string", "example": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj" } } ], "responses": { "200": { "description": "The custom field mapping.", "headers": { "ETag": { "description": "Current ETag of the mapping; supply it as `If-Match` on `PATCH`.", "schema": { "type": "string", "example": "\"2026-08-13T14:30:00Z\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldMappingResponse" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "403": { "description": "Forbidden request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] }, "patch": { "summary": "Update a custom field mapping", "description": "Partially updates an existing custom field mapping. Only the properties\npresent in the body are changed. The updatable properties depend on the\nmapping's `sourceType`; for `INTELLIGENCE_OPERATOR`, only\n`entityMetadata.intelligenceOperator.field` can be updated today.\n\nThe new `field` is validated the same way as at registration: it must be\none or two `.`-separated segments of letters, digits and `_`, and resolve\nto a `number` or `integer` property in the output schema of the\noperator's latest active version.\n\nThe mapping's `id`, `name`, `category`, `createdAt` and owning entity\nnever change. Sending a `field` value equal to the current one is a no-op that\nreturns `200` without modifying the mapping, so the operation is\nidempotent. Supply `If-Match` with the `ETag` returned by `GET`, `POST`\nor a previous `PATCH` to guard against concurrent updates.\n\nValues already ingested are not recomputed; results processed after the\nupdate use the new `field`.\n", "tags": [ "TwilioInsightsConfig" ], "operationId": "PatchCustomFieldMapping", "parameters": [ { "name": "mappingId", "in": "path", "required": true, "description": "The unique identifier of the custom field mapping, as returned in `id` when the mapping was created.", "schema": { "type": "string", "example": "convinsights_mapping_01m31967b7em08vh1pqgbam3mj" } }, { "in": "header", "name": "If-Match", "required": false, "description": "ETag of the custom field mapping, as returned in the `ETag` response header.\nWhen supplied, the update is applied only if the mapping has not changed\nsince that ETag was issued; otherwise `412` is returned.\n", "schema": { "type": "string", "example": "\"2026-08-13T14:30:00Z\"" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldMappingUpdateRequest" }, "examples": { "update_intelligence_operator_field": { "summary": "Point a custom measure at a different operator output field", "value": { "entityMetadata": { "sourceType": "INTELLIGENCE_OPERATOR", "intelligenceOperator": { "field": "scores.leadScore" } } } } } } } }, "responses": { "200": { "description": "The mapping was updated, or the supplied values already matched and\nnothing changed.\n", "headers": { "ETag": { "description": "Current ETag of the mapping; supply it as `If-Match` on the next update.", "schema": { "type": "string", "example": "\"2026-09-30T10:00:00Z\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldMappingResponse" } } } }, "400": { "description": "The request is invalid. One of:\n- a malformed body, an empty body or source object (nothing to\n update), a missing `entityMetadata.sourceType`, or a `field` that\n fails its pattern;\n- a property that cannot be updated (for example `name`,\n `category`, `operatorId`) is present;\n- `entityMetadata.sourceType` does not match the mapping's current\n `sourceType`, or is not supported for updates;\n- the new `field` does not resolve to a `number` or `integer`\n property on the operator's latest active version, or the operator\n no longer has an active `JSON` version.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "examples": { "field_not_resolvable": { "value": { "code": 20050, "message": "The 'field' value 'scores.leadScore' does not resolve on the latest active version of operator 'intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b'.", "httpStatusCode": 400, "userError": true } }, "field_not_updatable": { "value": { "code": 20053, "message": "The property 'name' cannot be updated.", "httpStatusCode": 400, "userError": true, "params": { "field": "name" } } }, "source_type_mismatch": { "value": { "code": 20054, "message": "The 'sourceType' does not match the mapping's current source type.", "httpStatusCode": 400, "userError": true, "params": { "expected": "INTELLIGENCE_OPERATOR", "actual": "OTHER_SOURCE" } } } } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "403": { "description": "Forbidden request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "409": { "description": "The mapping was modified by a concurrent request while this update\nwas being applied. Fetch the mapping and retry.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "example": { "code": 20409, "message": "The custom field mapping was modified concurrently. Please retry.", "httpStatusCode": 409, "userError": true } } } }, "412": { "description": "The `If-Match` value does not match the mapping's current `ETag`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "example": { "code": 20412, "message": "The custom field mapping has changed since the supplied ETag was issued.", "httpStatusCode": 412, "userError": true } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "503": { "description": "The operator details needed to validate the update could not be\nretrieved from Conversational Intelligence. The mapping was not\nchanged; retry after the `Retry-After` interval.\n", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying.", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] }, "example": { "code": 20503, "message": "The service is temporarily unavailable. Please retry after a short delay.", "httpStatusCode": 503, "userError": false } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } }, "/v3/ControlPlane/ConversationInsights/CustomFieldMappingsCapacity": { "servers": [ { "url": "https://insights.twilio.com" } ], "get": { "summary": "Get custom field mapping capacity for an account", "description": "Returns the account's custom measure slot capacity \u2014 slots consumed and\nremaining. Only the `measure` category is supported for now.\n", "tags": [ "TwilioInsightsConfig" ], "operationId": "FetchCustomFieldMappingCapacity", "responses": { "200": { "description": "Custom field mapping capacity for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldCapacity" } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "403": { "description": "Forbidden request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "429": { "description": "Too Many requests (rate limit exceeded for request originating from public API)", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the time window", "schema": { "type": "integer" }, "example": 5 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current time window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Reset": { "description": "Time in seconds until the rate limit resets", "schema": { "type": "integer" }, "example": 45 }, "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" }, "X-Rate-Limit-Remaining": { "$ref": "#/components/headers/X-Rate-Limit-Remaining" }, "X-Rate-Limit-Config": { "$ref": "#/components/headers/X-Rate-Limit-Config" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "A human readable error message", "type": "string" }, "httpStatusCode": { "description": "HTTP response status code", "type": "integer", "format": "int32" }, "userError": { "description": "Whether the error is a user error (true) or a system error (false)", "type": "boolean" }, "params": { "description": "A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message", "httpStatusCode" ] } } } } }, "security": [ { "basic_apikey_or_accountsid": [] } ] } } } }