Developer
Referencia de campos de la API
Cada endpoint REST a continuación lista sus campos de consulta, ruta, cuerpo y respuesta. Lee esto junto con la guía de la API.
De un vistazo
| Contrato | Comportamiento |
|---|---|
| Autenticación | Encabezado X-API-Key |
| URL base | https://api.getsift.ai |
| Versión | v0 |
| Filtrado completo en lista de acciones | fullFilter |
| Paginación de conversaciones | page y pageSize |
| Paginación de MCP | Contrato diferente; usa cursor y limit |
| Contrato REST completo legible por máquina | OpenAPI JSON |
Qué estás viendo
Esta referencia sigue el contrato público de OpenAPI obtenido el 2026-10-08. Cubre cada campo anidado declarado. Las etiquetas de requerido y opcional aplican dentro del objeto padre. Un hijo marcado como requerido no hace obligatorio a un padre opcional. Los valores nulos representan hechos faltantes o no disponibles. Los mapas dinámicos pueden contener claves definidas por la organización. Usa el contrato OpenAPI en vivo para cambios posteriores a esta fecha de referencia.
Reglas de filtrado y paginación
GET /v0/action/list toma por defecto los últimos siete días y las acciones respondidas.
Envía fullFilter para aplicar el DSL completo de Operaciones. No agrega el valor predeterminado de respondidas.
Los campos heredados filter y filterJson leen solo el indicador de respondidas. No los uses para filtrar por plataforma, cola o estado.
No combines fullFilter con ninguno de los campos heredados.
La lista de acciones no acepta entrada de page numerada. Su respuesta incluye metadatos de página, pero eso no crea un parámetro de página.
Continúa con ventanas de marca de tiempo y deduplica por actionId. Las marcas de tiempo iguales pueden complicar exportaciones grandes; usa la paginación por cursor de MCP para recorridos de registros reanudables.
El campo to de la lista de acciones es exclusivo: una fila con fecha exactamente igual a to queda fuera de la ventana. Un valor solo de fecha corresponde a medianoche UTC, no al final de ese día.
sortBy controla tanto el filtro de fecha como el orden de más reciente a más antiguo. Proporciona marcas de tiempo explícitas para ventanas precisas.
sortBy=updatedAt lee el último cambio del caso (un cambio de estado, cola, responsable o mensaje). El campo updatedAt exportado usa el mismo reloj, por lo que una ventana nunca devuelve una fila con fecha fuera de ella.
La búsqueda de conversaciones acepta page y pageSize numerados. Inspecciona totalRecordsCapped antes de tratar un conteo reportado como exacto.
Campos de los endpoints
GET /v0/action/list
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
pageSize (query) | integer | Opcional. Tamaño de página de la respuesta. Por defecto 50. Mínimo 1. Máximo 500. |
filter (query) | string | Opcional. Texto de filtro específico del endpoint. Lee la guía de filtrado antes de usarlo. |
filterJson (query) | string | Opcional. Texto de filtro JSON heredado; solo aplica el indicador de respondido. |
fullFilter (query) | string | Opcional. Filtro DSL de Operaciones completo. No lo combines con filter ni filterJson. Máximo de caracteres 10000. |
includeFullConversation (query) | boolean | Opcional. Incluye la conversación serializada. Por defecto false. |
sortBy (query) | string | Opcional. Elige createdAt o updatedAt para filtrar y ordenar del más reciente al más antiguo. Por defecto "createdAt". Valores: createdAt, updatedAt. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
data | array of object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data[].actionId | string | Requerido. Identificador de acción de Sift. Consérvalo como string. |
data[].actionTitle | string | Requerido. Título de la acción. |
data[].actionSummary | string | Requerido. Resumen de Sift sobre la acción. |
data[].status | string | Requerido. Estado actual. Usa el enum declarado cuando esté presente. |
data[].platform | string | Requerido. Plataforma de origen. |
data[].recordType | string / null | Requerido. Tipo de registro de origen. |
data[].isPublicPost | boolean | Requerido. Indica si el registro es público. |
data[].siftURL | string | Requerido. Enlace a la acción en Sift. |
data[].sourceURL | string / null | Requerido. Enlace al registro original; puede ser null para contenido privado. |
data[].queue | string / null | Requerido. Etiqueta de la cola actual. |
data[].initialQueue | string / null | Requerido. Etiqueta de la cola original. |
data[].sentiment | string / null | Requerido. Etiqueta de sentimiento. |
data[].sentimentScore | number / null | Requerido. Puntuación de sentimiento almacenada. |
data[].moderation | string / null | Requerido. Valor de moderación almacenado. |
data[].assigneeName | string / null | Requerido. Nombre del agente asignado. |
data[].assigneeEmail | string / null | Requerido. Correo electrónico del agente asignado. |
data[].assigneeUserId | string / null | Requerido. Identificador del agente asignado. |
data[].assigneeRole | string / null | Requerido. Rol del agente asignado. |
data[].userName | string | Requerido. Nombre del cliente. |
data[].userUsername | string | Requerido. Nombre de usuario del cliente en la plataforma. |
data[].userId | string | Requerido. Identificador del usuario. Conserva su valor string original. |
data[].userEmail | string / null | Requerido. Correo electrónico del cliente. |
data[].userFollowerCount | number / null | Requerido. Cantidad de seguidores almacenada del cliente; null si no está disponible. |
data[].createdAt | string | Requerido. Marca de tiempo de creación. |
data[].updatedAt | string / null | Requerido. Marca de tiempo de la última actualización. |
data[].initialMessageTime | string / null | Requerido. Hora del primer mensaje del cliente. |
data[].initialResponseTime | string / null | Requerido. Hora de la primera respuesta del agente. |
data[].closeTime | string / null | Requerido. Hora en que se cerró la acción. |
data[].claimTime | string / null | Requerido. Hora en que se reclamó la acción. |
data[].firstResponseTime | string / null | Requerido. Valor de duración de respuesta exportado. No lo interpretes como marca de tiempo. |
data[].handleTime | string / null | Requerido. Valor de duración de gestión exportado. No lo interpretes como marca de tiempo. |
data[].serverName | string | Requerido. Nombre de la cuenta o comunidad de origen. |
data[].channelName | string | Requerido. Nombre del canal de origen. |
data[].csatScore | string / null | Requerido. Puntuación de satisfacción del cliente reportada. |
data[].csatFeedback | string / null | Requerido. Comentarios de satisfacción del cliente. |
data[].estimatedCSAT | number / null | Requerido. Puntuación de satisfacción estimada. |
data[].totalMessages | number / null | Requerido. Cantidad de mensajes. |
data[].totalUserMessages | number / null | Requerido. Cantidad de mensajes del cliente. |
data[].totalAgentMessages | number / null | Requerido. Cantidad de mensajes del agente. |
data[].tags | array of object | Requerido. Etiquetas de la acción. |
data[].tags[].value | string | Obligatorio. Etiqueta del tag. |
data[].tags[].group | string | Requerido. Etiqueta del grupo de etiquetas. |
data[].closingTags | array of object | Requerido. Etiquetas aplicadas al cierre. |
data[].closingTags[].value | string | Obligatorio. Etiqueta del tag. |
data[].closingTags[].group | string | Requerido. Etiqueta del grupo de etiquetas. |
data[].customFields | object | Requerido. Nombres y valores de campos definidos por la organización. |
data[].rootMessageText | string / null | Requerido. Cuerpo del mensaje raíz. |
data[].conversationJson | string / null | Requerido. JSON de conversación serializado cuando se solicita; null en caso contrario. |
totalRecords | number | Requerido. Cantidad de registros coincidentes devueltos por este endpoint. |
currentPage | number | Requerido. Página representada por la respuesta. |
pageSize | number | Requerido. Tamaño de página de la respuesta. |
totalPages | number | Requerido. Número de páginas reportadas. |
Respuesta 400
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/action/{id}
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
id (ruta) | string | Requerido. Identificador de este objeto. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
user | object | Requerido. Perfil del cliente. |
user.name | string | Requerido. Nombre para mostrar. |
user.username | string | Requerido. Nombre de usuario en la plataforma. |
user.userId | string | Requerido. Identificador del usuario. Conserva su valor original como string. |
user.email | string / null | Requerido. Dirección de correo electrónico. |
user.followerCount | number / null | Requerido. Cantidad de seguidores almacenada; null si no está disponible. |
actionId | string | Requerido. Identificador de acción de Sift. Consérvalo como string. |
actionTitle | string | Requerido. Título de la acción. |
actionSummary | string | Requerido. Resumen de la acción generado por Sift. |
platform | string | Requerido. Plataforma de origen. |
recordType | string / null | Requerido. Tipo de registro de origen. |
isPublicPost | boolean | Requerido. Indica si el registro es público. |
sentiment | string / null | Requerido. Etiqueta de sentimiento. |
sentimentScore | number / null | Requerido. Puntuación de sentimiento almacenada. |
queue | string / null | Requerido. Etiqueta de la cola actual. |
initialQueue | string / null | Requerido. Etiqueta de la cola original. |
status | string | Requerido. Estado actual. Usa el enum declarado cuando esté presente. |
createdAt | string | Requerido. Marca de tiempo de creación. |
siftURL | string | Requerido. Enlace a la acción en Sift. |
sourceURL | string / null | Requerido. Enlace al registro original; puede ser null para contenido privado. |
updatedAt | string / null | Requerido. Marca de tiempo de la última actualización. |
initialMessageTime | string / null | Requerido. Hora del primer mensaje del cliente. |
initialResponseTime | string / null | Requerido. Hora de la primera respuesta del agente. |
closeTime | string / null | Requerido. Hora en que se cerró la acción. |
firstResponseTime | string / null | Requerido. Valor exportado de duración de respuesta. No lo interpretes como marca de tiempo. |
handleTime | string / null | Requerido. Valor exportado de duración de gestión. No lo interpretes como marca de tiempo. |
claimTime | string / null | Requerido. Hora en que se reclamó la acción. |
assignee | object | Requerido. Agente de Sift asignado. |
assignee.name | string / null | Requerido. Nombre para mostrar. |
assignee.email | string / null | Requerido. Dirección de correo electrónico. |
assignee.userId | string / null | Requerido. Identificador del usuario. Conserva su valor original como string. |
assignee.role | string / null | Requerido. Etiqueta de rol. |
serverName | string | Requerido. Nombre de la cuenta o comunidad de origen. |
channelName | string | Requerido. Nombre del canal de origen. |
tags | array of object | Requerido. Etiquetas de la acción. |
tags[].value | string | Obligatorio. Etiqueta del tag. |
tags[].group | string | Requerido. Etiqueta del grupo de etiquetas. |
closingTags | array of object | Requerido. Etiquetas aplicadas al cierre. |
closingTags[].value | string | Obligatorio. Etiqueta del tag. |
closingTags[].group | string | Requerido. Etiqueta del grupo de etiquetas. |
moderation | string / null | Requerido. Valor de moderación almacenado. |
comments | array of object | Requerido. Comentarios exportados. |
comments[].text | string | Requerido. Cuerpo del texto. |
comments[].authorNativeId | string | Requerido. ID de autor nativo de la plataforma. |
comments[].authorNativeName | string / null | Requerido. Nombre de autor nativo de la plataforma. |
messages | array of object | Requerido. Registros de mensajes exportados. |
messages[].id | string | Requerido. Identificador de este objeto. |
messages[].timestamp | string | Requerido. Marca de tiempo del mensaje o evento. |
messages[].author | string | Requerido. Nombre del autor. |
messages[].authorId | string | Opcional. Identificador del autor. |
messages[].authorType | string | Requerido. USER, AGENT o BOT. Valores: USER, AGENT, BOT. |
messages[].message | string | Requerido. Cuerpo del mensaje. |
messages[].mediaUrls | array of string | Requerido. Enlaces de medios. |
rootMessageText | string / null | Requerido. Cuerpo del mensaje raíz. |
conversation | array of object | Opcional. Conversación completa opcional. |
conversation[].id | string | Requerido. Identificador de este objeto. |
conversation[].timestamp | string | Requerido. Marca de tiempo del mensaje o evento. |
conversation[].author | string | Requerido. Nombre del autor. |
conversation[].authorId | string / null | Requerido. Identificador del autor. |
conversation[].authorType | string | Requerido. USER, AGENT o BOT. Valores: USER, AGENT, BOT. |
conversation[].message | string | Requerido. Cuerpo del mensaje. |
conversation[].parentMessageId | string / null | Requerido. Identificador del mensaje padre; null si no está disponible. |
conversation[].mediaUrls | array of string | Requerido. Enlaces de medios. |
customFields | object | Requerido. Nombres y valores de campos definidos por la organización. |
csatScore | string / null | Requerido. Puntuación de satisfacción del cliente reportada. |
csatFeedback | string / null | Requerido. Comentarios de satisfacción del cliente. |
estimatedCSAT | number / null | Requerido. Puntuación de satisfacción estimada. |
totalMessages | number / null | Requerido. Cantidad de mensajes. |
totalUserMessages | number / null | Requerido. Cantidad de mensajes del cliente. |
totalAgentMessages | number / null | Requerido. Cantidad de mensajes del agente. |
Respuesta 404
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
PATCH /v0/actions/{actionId}/custom-fields
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
actionId (ruta) | string | Requerido. Identificador de acción de Sift. Manténgalo como string. Mínimo de caracteres 1. |
Cuerpo JSON
| Campo | Tipo | Requisito y significado |
|---|---|---|
fields | array of object | Requerido. Campos personalizados en esta solicitud o respuesta. Mínimo de elementos 1. |
fields[].fieldName | string | Requerido. Nombre del campo personalizado registrado. Mínimo de caracteres 1. |
fields[].value | JSON | Requerido. Valor del campo. El tipo aceptado depende del campo declarado. |
fields[].confidence | number | Opcional. Confianza opcional de 0 a 1. Mínimo 0. Máximo 1. |
fields[].rationale | string | Opcional. Razón opcional para el valor del campo. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
actionId | string | Requerido. Identificador de acción de Sift. Manténgalo como string. |
updated | array of object | Requerido. Campos que esta solicitud actualiza. |
updated[].fieldName | string | Requerido. Nombre del campo personalizado registrado. |
updated[].value | JSON | Requerido. Valor del campo. El tipo aceptado depende del campo declarado. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
fieldErrors | object | Opcional. Mapa de nombre de campo a mensaje de validación. |
Respuesta 404
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
fieldErrors | object | Opcional. Mapa de nombre de campo a mensaje de validación. |
Respuesta 422
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
fieldErrors | object | Opcional. Mapa de nombre de campo a mensaje de validación. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
fieldErrors | object | Opcional. Mapa de nombre de campo a mensaje de validación. |
GET /v0/actions/{actionId}/custom-fields
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
actionId (ruta) | string | Requerido. Identificador de acción de Sift. Manténgalo como string. Mínimo de caracteres: 1. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
actionId | string | Requerido. Identificador de acción de Sift. Manténgalo como string. |
fields | array of object | Requerido. Campos personalizados en esta solicitud o respuesta. |
fields[].fieldName | string | Requerido. Nombre del campo personalizado registrado. |
fields[].displayName | string | Requerido. Etiqueta del campo visible para el cliente. |
fields[].fieldType | string | Requerido. Tipo de campo registrado. |
fields[].value | JSON | Requerido. Valor del campo. El tipo aceptado depende del campo declarado. |
fields[].provenance | JSON | Opcional. Origen almacenado del valor. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
fieldErrors | object | Opcional. Mapa de nombre de campo a mensaje de validación. |
Respuesta 404
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
fieldErrors | object | Opcional. Mapa de nombre de campo a mensaje de validación. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
fieldErrors | object | Opcional. Mapa de nombre de campo a mensaje de validación. |
GET /v0/agents
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
data | array of object | Requerido. Datos del resultado. Lee el contrato anidado de este endpoint. |
data[].agentId | string | Requerido. Identificador del agente en Sift. |
data[].metrics | object | Requerido. Métricas para la ventana seleccionada. |
data[].metrics.totalActions | number | Requerido. Cantidad de acciones. |
data[].metrics.totalActionsWithResponse | number | Requerido. Acciones con respuesta del agente. |
data[].metrics.totalMessages | number | Requerido. Cantidad de mensajes. |
data[].metrics.totalAgentMessages | number | Requerido. Cantidad de mensajes del agente. |
data[].metrics.totalUserMessages | number | Requerido. Cantidad de mensajes del cliente. |
data[].metrics.averageCsat | number | Requerido. Satisfacción promedio reportada. |
data[].metrics.averageResponseTime | number o null | Requerido. Tiempo de respuesta promedio. Null cuando el agente no tiene respuestas medidas en el periodo. Consulta la referencia de métricas para las unidades. |
data[].metrics.averageHandleTime | number o null | Requerido. Tiempo de manejo promedio. Null cuando el agente no tiene tiempo de manejo medido en el periodo. Consulta la referencia de métricas para las unidades. |
data[].metrics.averageEstimatedCsat | number | Requerido. Satisfacción estimada promedio. |
data[].metrics.averageResolutionQuality | number | Requerido. Calidad de resolución promedio. |
data[].metrics.averageSentimentChange | number | Requerido. Cambio de sentimiento promedio. |
data[].metrics.averageRubricScore | number | Requerido. Puntuación de rúbrica promedio. |
data[].workload | object | Requerido. Conteos por estado de carga de trabajo. |
data[].workload.active | number | Requerido. Cantidad de acciones activas. |
data[].workload.closed | number | Requerido. Cantidad de acciones cerradas. |
data[].workload.cancelled | number | Requerido. Cantidad de acciones canceladas. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/agents/{id}
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (consulta) | JSON | Opcional. Inicio de la ventana. Consulta las reglas de fecha del endpoint. |
to (consulta) | JSON | Opcional. Fin de la ventana. Consulta las reglas de fecha del endpoint. |
id (ruta) | string | Requerido. Identificador de este objeto. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
data | object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data.metrics | array of object | Requerido. Métricas para la ventana seleccionada. |
data.aggregatedMetrics | object | Requerido. Métricas agregadas del agente. |
data.aggregatedMetrics.totalActions | number | Requerido. Cantidad de acciones. |
data.aggregatedMetrics.totalMessages | number | Requerido. Cantidad de mensajes. |
data.aggregatedMetrics.totalAgentMessages | number | Requerido. Cantidad de mensajes del agente. |
data.aggregatedMetrics.totalUserMessages | number | Requerido. Cantidad de mensajes del cliente. |
data.aggregatedMetrics.averageCsat | number | Requerido. Satisfacción reportada promedio. |
data.aggregatedMetrics.averageResponseTime | number o null | Requerido. Mediana del tiempo de respuesta. Null cuando el agente no tiene respuestas medidas en el periodo. Consulta la referencia de métricas para las unidades. |
data.aggregatedMetrics.averageHandleTime | number o null | Requerido. Mediana del tiempo de manejo. Null cuando el agente no tiene tiempo de manejo medido en el periodo. Consulta la referencia de métricas para las unidades. |
data.aggregatedMetrics.averageEstimatedCsat | number | Requerido. Satisfacción estimada promedio. |
data.aggregatedMetrics.averageResolutionQuality | number | Requerido. Calidad de resolución promedio. |
data.aggregatedMetrics.averageSentimentChange | number | Requerido. Cambio de sentimiento promedio. |
data.aggregatedMetrics.averageRubricScore | number | Requerido. Puntuación de rúbrica promedio. |
data.currentWorkload | object | Requerido. Carga de trabajo actual del agente. |
data.currentWorkload.active | number | Requerido. Cantidad de acciones activas. |
data.currentWorkload.closed | number | Requerido. Cantidad de acciones cerradas. |
data.currentWorkload.cancelled | number | Requerido. Cantidad de acciones canceladas. |
data.queues | array of object | Requerido. Registros de cola del agente. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 404
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/queues
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
data | array of object | Requerido. Datos del resultado. Lee el contrato anidado de este endpoint. |
data[].queueId | string / null | Requerido. Identificador de la cola; null puede representar la ausencia de cola. |
data[].queueName | string / null | Requerido. Nombre de la cola. |
data[].metrics | object | Requerido. Métricas para la ventana seleccionada. |
data[].metrics.totalActions | number | Requerido. Cantidad de acciones. |
data[].metrics.totalMessages | number | Requerido. Cantidad de mensajes. |
data[].metrics.totalAgentMessages | number | Requerido. Cantidad de mensajes del agente. |
data[].metrics.totalUserMessages | number | Requerido. Cantidad de mensajes del cliente. |
data[].metrics.averageCsat | number | Requerido. Satisfacción reportada promedio. |
data[].metrics.averageResponseTime | number | Requerido. Tiempo de respuesta promedio. Consulta la referencia de métricas para las unidades. |
data[].metrics.averageHandleTime | number | Requerido. Tiempo de manejo promedio. Consulta la referencia de métricas para las unidades. |
data[].metrics.averageEstimatedCsat | number | Requerido. Satisfacción estimada promedio. |
data[].metrics.averageResolutionQuality | number | Requerido. Calidad de resolución promedio. |
data[].metrics.averageSentimentChange | number | Requerido. Cambio de sentimiento promedio. |
data[].metrics.averageRubricScore | number | Requerido. Puntuación de rúbrica promedio. |
data[].metrics.averageSentimentScore | number | Requerido. Puntuación de sentimiento promedio. |
data[].workload | object | Requerido. Conteos por estado de carga de trabajo. |
data[].workload.active | number | Requerido. Cantidad de acciones activas. |
data[].workload.closed | number | Requerido. Cantidad de acciones cerradas. |
data[].workload.cancelled | number | Requerido. Cantidad de acciones canceladas. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/analytics/tags
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
respondedOnly (query) | boolean | Opcional. Restringe el análisis de etiquetas a los registros respondidos cuando está habilitado. |
limit (query) | number | Opcional. Tamaño máximo de resultados solicitado. |
offset (query) | number | Opcional. Desplazamiento inicial de resultados. |
search (query) | string | Opcional. Búsqueda de texto sobre etiquetas. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
data | object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data.summary | object | Requerido. Resumen de los datos seleccionados. |
data.summary.totalTags | number | Requerido. Cantidad de etiquetas. |
data.summary.totalTagGroups | number | Requerido. Cantidad de grupos de etiquetas. |
data.summary.totalTaggedRecords | number | Requerido. Cantidad de registros etiquetados. |
data.summary.totalActions | number | Requerido. Cantidad de acciones. |
data.tagBreakdown | array of object | Requerido. Distribución de etiquetas. |
data.tagBreakdown[].tagId | string | Requerido. Identificador de la etiqueta. |
data.tagBreakdown[].tagName | string | Requerido. Etiqueta de la etiqueta. |
data.tagBreakdown[].groupName | string / null | Requerido. Etiqueta del grupo de etiquetas. |
data.tagBreakdown[].count | number | Requerido. Conteo para este grupo. |
data.tagBreakdown[].percentage | number | Requerido. Porcentaje para este grupo. |
data.volumeByTag | array of object | Requerido. Volumen y puntuaciones para cada etiqueta. |
data.volumeByTag[].tagId | string | Requerido. Identificador de la etiqueta. |
data.volumeByTag[].tagName | string | Requerido. Etiqueta de la etiqueta. |
data.volumeByTag[].total | number | Requerido. Total para este alcance. |
data.volumeByTag[].responded | number | Requerido. Cantidad de respondidos. |
data.volumeByTag[].notResponded | number | Requerido. Cantidad de no respondidos. |
data.volumeByTag[].avgSentiment | number / null | Requerido. Sentimiento promedio. |
data.volumeByTag[].avgActionability | number / null | Requerido. Accionabilidad promedio. |
data.volumeByTag[].avgRelevance | number / null | Requerido. Relevancia promedio. |
data.pagination | object | Requerido. Recibo de paginación. |
data.pagination.total | number | Requerido. Total para este alcance. |
data.pagination.limit | number | Requerido. Tamaño máximo de resultados solicitado. |
data.pagination.offset | number | Requerido. Desplazamiento inicial de resultados. |
data.pagination.hasMore | boolean | Requerido. Indica si existe otra página. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/analytics/tags/volume
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
respondedOnly (query) | boolean | Opcional. Restringe el análisis de etiquetas a los registros respondidos cuando está habilitado. |
topTagsLimit (query) | number | Opcional. Número máximo de etiquetas principales. |
tagIds (query) | string | Opcional. IDs de etiquetas separados por comas. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
data | object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data.data | array of object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data.tags | array of string | Requerido. Etiquetas de acción. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/analytics/sentiment
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
data | array of object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data[].day | string | Requerido. Agrupación por día. |
data[].Very Negative | number | Requerido. Conteo de sentimiento muy negativo. |
data[].Negative | number | Requerido. Conteo de sentimiento negativo. |
data[].Neutral | number | Requerido. Conteo de sentimiento neutral. |
data[].Positive | number | Requerido. Conteo de sentimiento positivo. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/analytics/sentiment/by-tag
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
data | array of object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data[].tagName | string | Requerido. Etiqueta del tag. |
data[].veryNegative | number | Requerido. Conteo de sentimiento muy negativo. |
data[].negative | number | Requerido. Conteo de sentimiento negativo. |
data[].neutral | number | Requerido. Conteo de sentimiento neutral. |
data[].positive | number | Requerido. Conteo de sentimiento positivo. |
data[].totalMentions | number | Requerido. Menciones contabilizadas para este tag. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/analytics/engagement
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
from (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el inicio. Una fecha sin hora corresponde a medianoche UTC. |
to (query) | cadena de fecha | Opcional. Fecha o marca de tiempo ISO 8601 para el final. Consulta las reglas de fecha del endpoint. |
platforms (query) | string | Opcional. Valores de plataforma de origen separados por comas. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
data | object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data.engagementPercentiles | array of object | Requerido. Percentiles de volumen de mensajes por plataforma. |
data.engagementPercentiles[].platform | string | Requerido. Plataforma de origen. |
data.engagementPercentiles[].p25MessagesPerUser | number | Requerido. Percentil 25 de mensajes por usuario. |
data.engagementPercentiles[].medianMessagesPerUser | number | Requerido. Mediana de mensajes por usuario. |
data.engagementPercentiles[].p75MessagesPerUser | number | Requerido. Percentil 75 de mensajes por usuario. |
data.growthTrends | array of object | Requerido. Crecimiento semanal de usuarios por plataforma. |
data.growthTrends[].week | string | Requerido. Intervalo semanal. Formato date-time. |
data.growthTrends[].platform | string | Requerido. Plataforma de origen. |
data.growthTrends[].currentWeekUsers | number | Requerido. Cantidad de usuarios de la semana actual. |
data.growthTrends[].previousWeekUsers | number | Requerido. Cantidad de usuarios de la semana anterior. |
data.growthTrends[].growthPercentage | number | Requerido. Porcentaje de crecimiento. |
data.conversionFunnel | array of object | Requerido. Filas del embudo definidas por la fuente. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
GET /v0/conversations/search
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
filter (query) | string | Opcional. Texto de filtro específico del endpoint. Lee la guía de filtrado antes de usarlo. |
page (query) | integer | Opcional. Página numerada, comenzando en 1. Valor predeterminado 1. Mínimo 1. Máximo 10000. |
pageSize (query) | integer | Opcional. Tamaño de página de la respuesta. Valor predeterminado 50. Mínimo 1. Máximo 100. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
data | array of object | Requerido. Datos del resultado. Lee el contrato anidado para este endpoint. |
data[].actionId | string | Requerido. Identificador de acción de Sift. Consérvalo como string. |
data[].actionTitle | string | Requerido. Título de la acción. |
data[].actionSummary | string | Requerido. Resumen de Sift sobre la acción. |
data[].status | string | Requerido. Estado actual. Usa el enum declarado cuando esté presente. |
data[].platform | string | Requerido. Plataforma de origen. |
data[].recordType | string / null | Requerido. Tipo de registro de origen. |
data[].isPublicPost | boolean | Requerido. Indica si el registro es público. |
data[].siftURL | string | Requerido. Enlace a la acción en Sift. |
data[].sourceURL | string / null | Requerido. Enlace al registro original; puede ser null para contenido privado. |
data[].queue | string / null | Requerido. Etiqueta de la cola actual. |
data[].initialQueue | string / null | Requerido. Etiqueta de la cola original. |
data[].sentiment | string / null | Requerido. Etiqueta de sentimiento. |
data[].sentimentScore | number / null | Requerido. Puntuación de sentimiento almacenada. |
data[].moderation | string / null | Requerido. Valor de moderación almacenado. |
data[].assigneeName | string / null | Requerido. Nombre del agente asignado. |
data[].assigneeEmail | string / null | Requerido. Correo electrónico del agente asignado. |
data[].assigneeUserId | string / null | Requerido. Identificador del agente asignado. |
data[].assigneeRole | string / null | Requerido. Rol del agente asignado. |
data[].userName | string | Requerido. Nombre del cliente. |
data[].userUsername | string | Requerido. Nombre de usuario del cliente en la plataforma. |
data[].userId | string | Requerido. Identificador del usuario. Conserva su valor string original. |
data[].userEmail | string / null | Requerido. Correo electrónico del cliente. |
data[].userFollowerCount | number / null | Requerido. Cantidad de seguidores almacenada del cliente; null si no está disponible. |
data[].createdAt | string | Requerido. Marca de tiempo de creación. |
data[].updatedAt | string / null | Requerido. Marca de tiempo de la última actualización. |
data[].initialMessageTime | string / null | Requerido. Hora del primer mensaje del cliente. |
data[].initialResponseTime | string / null | Requerido. Hora de la primera respuesta del agente. |
data[].closeTime | string / null | Requerido. Hora en que se cerró la acción. |
data[].claimTime | string / null | Requerido. Hora en que se reclamó la acción. |
data[].firstResponseTime | string / null | Requerido. Valor de duración de respuesta exportado. No lo interpretes como marca de tiempo. |
data[].handleTime | string / null | Requerido. Valor de duración de manejo exportado. No lo interpretes como marca de tiempo. |
data[].serverName | string | Requerido. Nombre de la cuenta o comunidad de origen. |
data[].channelName | string | Requerido. Nombre del canal de origen. |
data[].csatScore | string / null | Requerido. Puntuación de satisfacción del cliente reportada. |
data[].csatFeedback | string / null | Requerido. Comentarios de satisfacción del cliente. |
data[].estimatedCSAT | number / null | Requerido. Puntuación de satisfacción estimada. |
data[].totalMessages | number / null | Requerido. Cantidad de mensajes. |
data[].totalUserMessages | number / null | Requerido. Cantidad de mensajes del cliente. |
data[].totalAgentMessages | number / null | Requerido. Cantidad de mensajes del agente. |
data[].tags | array of object | Requerido. Etiquetas de la acción. |
data[].tags[].value | string | Obligatorio. Etiqueta del tag. |
data[].tags[].group | string | Requerido. Etiqueta del grupo de etiquetas. |
data[].closingTags | array of object | Requerido. Etiquetas aplicadas al cierre. |
data[].closingTags[].value | string | Obligatorio. Etiqueta del tag. |
data[].closingTags[].group | string | Requerido. Etiqueta del grupo de etiquetas. |
data[].customFields | object | Requerido. Nombres y valores de campos definidos por la organización. |
data[].rootMessageText | string / null | Requerido. Cuerpo del mensaje raíz. |
data[].conversationJson | string / null | Requerido. JSON de conversación serializado cuando se solicita; null en caso contrario. |
data[].threadId | string | Requerido. Identificador del hilo. |
data[].easyId | string / null | Requerido. Identificador de caso legible. |
data[].contributors | string / null | Requerido. Resumen de colaboradores almacenado. |
totalRecords | number | Requerido. Cantidad de registros coincidentes devueltos por este endpoint. |
totalRecordsCapped | boolean | Requerido. Indica si el conteo se detiene en un límite máximo. No trates un conteo limitado como exacto. |
currentPage | number | Requerido. Página representada por la respuesta. |
pageSize | number | Requerido. Tamaño de página de la respuesta. |
totalPages | number | Requerido. Número de páginas reportadas. |
Respuesta 400
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. |
error | string | Requerido. Mensaje de error. |
POST /v0/moderation/cases
Campos de solicitud y respuesta
Cuerpo JSON
| Campo | Tipo | Requisito y significado |
|---|---|---|
externalId | string | Requerido. Identificador del productor. Consérvalo en reintentos exactos. Mínimo de caracteres 1. Máximo de caracteres 256. |
sourceSystem | string | Requerido. Nombre del sistema productor. Mínimo de caracteres 1. Máximo de caracteres 128. |
sourcePlatform | string | Requerido. Plataforma publicitaria de origen. Mínimo de caracteres 1. Máximo de caracteres 128. |
sourceAdId | string | Requerido. Identificador del anuncio de origen. Mínimo de caracteres 1. Máximo de caracteres 256. |
advertiserId | string | Opcional. Identificador del anunciante. Mínimo de caracteres 1. Máximo de caracteres 256. |
advertiserName | string | Requerido. Nombre del anunciante. Mínimo de caracteres 1. Máximo de caracteres 500. |
campaignId | string | Opcional. Identificador de la campaña. Mínimo de caracteres 1. Máximo de caracteres 256. |
market | string | Requerido. Mercado para la evaluación de políticas. Mínimo de caracteres 1. Máximo de caracteres 128. |
placement | string | Requerido. Ubicación del anuncio. Mínimo de caracteres 1. Máximo de caracteres 128. |
language | string | Opcional. Idioma del contenido enviado. Valor predeterminado "en". Mínimo de caracteres 1. Máximo de caracteres 64. |
providerMetadata | object | Opcional. Metadatos del proveedor conservados con el envío. |
landingPageUrl | string / null | Requerido. URL de la página de destino. |
title | string | Requerido. Título del registro. Mínimo de caracteres 1. Máximo de caracteres 500. |
headline | string | Opcional. Titular del anuncio. Mínimo de caracteres 1. Máximo de caracteres 500. |
brandName | string | Opcional. Nombre de la marca anunciada. Mínimo de caracteres 1. Máximo de caracteres 500. |
callToAction | string | Opcional. Valor de llamada a la acción. Valores: APPLY_NOW, BOOK_NOW, GET_NOW, INSTALL_NOW, MORE, SHOP_NOW, SIGN_UP, VIEW, WATCH. |
publicProfile | object | Opcional. Información del perfil público. |
publicProfile.displayName | string | Opcional. Etiqueta del campo visible para el cliente. Mínimo de caracteres 1. Máximo de caracteres 500. |
publicProfile.logoUrl | string | Opcional. URL del logotipo de la marca. Formato uri. |
publicProfile.verified | boolean | Opcional. Indica si esta evaluación verifica la afirmación. |
media | array of object | Requerido. Recursos multimedia ordenados. Mínimo de elementos 1. Máximo de elementos 20. |
media[].url | string | Requerido. Enlace de origen HTTP o HTTPS absoluto. Formato uri. |
media[].type | string | Requerido. Tipo declarado para este objeto. Valores: image, video. |
media[].position | integer | Requerido. Posición de este recurso en la secuencia de medios. Mínimo 1. Máximo 20. |
attachment | object | Requerido. Adjunto de destino para el anuncio. |
attachment.type | string | Requerido. Tipo declarado para este objeto. Valores: web_view, deep_link, app_install, lens, long_form_video. |
attachment.destinationUrl | string / null | Requerido. URL de destino del adjunto. |
targeting | object | Requerido. Configuración de segmentación del anuncio. |
targeting.ageMin | integer / null | Requerido. Edad mínima segmentada. |
targeting.ageMax | integer / null | Opcional. Edad máxima segmentada. |
targeting.geos | array of string | Requerido. Áreas geográficas segmentadas. Mínimo de elementos 1. Máximo de elementos 250. |
targeting.languages | array of string | Opcional. Idiomas segmentados. Mínimo de elementos 1. Máximo de elementos 100. |
copy | object | Requerido. Texto del anuncio y título vinculado. |
copy.body | string | Opcional. Cuerpo del registro. Máximo de caracteres 20000. |
copy.caption | string | Opcional. Leyenda del anuncio. Máximo de caracteres 20000. |
copy.linkDescription | string | Opcional. Descripción del destino vinculado. Máximo de caracteres 20000. |
copy.sourceTitle | string | Opcional. Título del origen enviado. Máximo de caracteres 20000. |
discoverTile | boolean | Opcional. Indica si la ubicación usa un tile de Discover. |
partnershipAd | boolean | Opcional. Indica si este es un anuncio de asociación. |
format | string / null | Opcional. Formato del anuncio. |
arLens | string / null | Opcional. Información del lente de realidad aumentada. |
submittedAt | string | Opcional. Marca de tiempo del envío. Formato date-time. |
Respuesta 202
| Campo | Tipo | Requisito y significado |
|---|---|---|
caseId | string | Requerido. Identificador del caso aceptado. Úsalo para consultas de estado. |
externalId | string | Requerido. Identificador del productor. Consérvalo en reintentos exactos. |
status | string | Requerido. Estado actual. Usa el enum declarado cuando esté disponible. Valores: accepted, duplicate. |
analysisStatus | string | Requerido. Estado actual de la evaluación. Una decisión está disponible solo después de completarse. Valores: pending. |
evaluationId | string | Requerido. Identificador de la evaluación, cuando esté disponible. |
idempotency | object | Requerido. Recibo de reintento. |
idempotency.key | string | Requerido. Clave de idempotencia. |
idempotency.replayed | boolean | Requerido. Indica si esta solicitud reutiliza un envío anterior. |
Respuesta 400
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud tiene éxito. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array of string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array of string | Opcional. Rutas de campos de entrada inválidos. |
supported | array of string | Opcional. Indica si la evidencia respalda esta afirmación. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud tiene éxito. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array of string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array of string | Opcional. Rutas de campos de entrada inválidos. |
supported | array of string | Opcional. Indica si la evidencia respalda esta afirmación. |
Respuesta 409
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud tiene éxito. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array of string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array of string | Opcional. Rutas de campos de entrada inválidos. |
supported | array of string | Opcional. Indica si la evidencia respalda esta afirmación. |
Respuesta 422
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud tiene éxito. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array of string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array of string | Opcional. Rutas de campos de entrada inválidos. |
supported | array of string | Opcional. Indica si la evidencia respalda esta afirmación. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud tiene éxito. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array of string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array of string | Opcional. Rutas de campos de entrada inválidos. |
supported | array of string | Opcional. Indica si la evidencia respalda esta afirmación. |
POST /v0/moderation/cases/batch
Campos de solicitud y respuesta
Cuerpo JSON
| Campo | Tipo | Requisito y significado |
|---|---|---|
cases | array de objeto | Requerido. Lote de casos de moderación, 1–100 elementos. Mínimo de elementos 1. Máximo de elementos 100. |
cases[].externalId | string | Requerido. Identificador del productor. Consérvalo en reintentos exactos. Mínimo de caracteres 1. Máximo de caracteres 256. |
cases[].sourceSystem | string | Requerido. Nombre del sistema productor. Mínimo de caracteres 1. Máximo de caracteres 128. |
cases[].sourcePlatform | string | Requerido. Plataforma publicitaria de origen. Mínimo de caracteres 1. Máximo de caracteres 128. |
cases[].sourceAdId | string | Requerido. Identificador del anuncio de origen. Mínimo de caracteres 1. Máximo de caracteres 256. |
cases[].advertiserId | string | Opcional. Identificador del anunciante. Mínimo de caracteres 1. Máximo de caracteres 256. |
cases[].advertiserName | string | Requerido. Nombre del anunciante. Mínimo de caracteres 1. Máximo de caracteres 500. |
cases[].campaignId | string | Opcional. Identificador de la campaña. Mínimo de caracteres 1. Máximo de caracteres 256. |
cases[].market | string | Requerido. Mercado para la evaluación de políticas. Mínimo de caracteres 1. Máximo de caracteres 128. |
cases[].placement | string | Requerido. Ubicación del anuncio. Mínimo de caracteres 1. Máximo de caracteres 128. |
cases[].language | string | Opcional. Idioma del contenido enviado. Valor predeterminado "en". Mínimo de caracteres 1. Máximo de caracteres 64. |
cases[].providerMetadata | objeto | Opcional. Metadatos del proveedor conservados con el envío. |
cases[].landingPageUrl | string / null | Requerido. URL de la página de destino. |
cases[].title | string | Requerido. Título del registro. Mínimo de caracteres 1. Máximo de caracteres 500. |
cases[].headline | string | Opcional. Titular del anuncio. Mínimo de caracteres 1. Máximo de caracteres 500. |
cases[].brandName | string | Opcional. Nombre de la marca anunciada. Mínimo de caracteres 1. Máximo de caracteres 500. |
cases[].callToAction | string | Opcional. Valor de llamada a la acción. Valores: APPLY_NOW, BOOK_NOW, GET_NOW, INSTALL_NOW, MORE, SHOP_NOW, SIGN_UP, VIEW, WATCH. |
cases[].publicProfile | objeto | Opcional. Información del perfil público. |
cases[].publicProfile.displayName | string | Opcional. Etiqueta de campo visible para el cliente. Mínimo de caracteres 1. Máximo de caracteres 500. |
cases[].publicProfile.logoUrl | string | Opcional. URL del logotipo de la marca. Formato uri. |
cases[].publicProfile.verified | boolean | Opcional. Indica si esta evaluación verifica la afirmación. |
cases[].media | array de objeto | Requerido. Recursos multimedia ordenados. Mínimo de elementos 1. Máximo de elementos 20. |
cases[].media[].url | string | Requerido. Enlace de origen HTTP o HTTPS absoluto. Formato uri. |
cases[].media[].type | string | Requerido. Tipo declarado para este objeto. Valores: image, video. |
cases[].media[].position | integer | Requerido. Posición de este recurso en la secuencia de medios. Mínimo 1. Máximo 20. |
cases[].attachment | objeto | Requerido. Adjunto de destino para el anuncio. |
cases[].attachment.type | string | Requerido. Tipo declarado para este objeto. Valores: web_view, deep_link, app_install, lens, long_form_video. |
cases[].attachment.destinationUrl | string / null | Requerido. URL de destino del adjunto. |
cases[].targeting | objeto | Requerido. Configuración de segmentación del anuncio. |
cases[].targeting.ageMin | integer / null | Requerido. Edad mínima segmentada. |
cases[].targeting.ageMax | integer / null | Opcional. Edad máxima segmentada. |
cases[].targeting.geos | array de string | Requerido. Áreas geográficas segmentadas. Mínimo de elementos 1. Máximo de elementos 250. |
cases[].targeting.languages | array de string | Opcional. Idiomas segmentados. Mínimo de elementos 1. Máximo de elementos 100. |
cases[].copy | objeto | Requerido. Texto del anuncio y título vinculado. |
cases[].copy.body | string | Opcional. Cuerpo del registro. Máximo de caracteres 20000. |
cases[].copy.caption | string | Opcional. Leyenda del anuncio. Máximo de caracteres 20000. |
cases[].copy.linkDescription | string | Opcional. Descripción del destino vinculado. Máximo de caracteres 20000. |
cases[].copy.sourceTitle | string | Opcional. Título de la fuente enviada. Máximo de caracteres 20000. |
cases[].discoverTile | boolean | Opcional. Indica si la ubicación usa un tile de Discover. |
cases[].partnershipAd | boolean | Opcional. Indica si es un anuncio de asociación. |
cases[].format | string / null | Opcional. Formato del anuncio. |
cases[].arLens | string / null | Opcional. Información del lens de realidad aumentada. |
cases[].submittedAt | string | Opcional. Marca de tiempo del envío. Formato date-time. |
Respuesta 202
| Campo | Tipo | Requisito y significado |
|---|---|---|
results | array de objeto | Requerido. Resultado ordenado para cada entrada del lote. |
results[].externalId | string | Requerido. Identificador del productor. Consérvalo en reintentos exactos. |
results[].caseId | string | Requerido. Identificador del caso aceptado. Úsalo para consultas de estado. |
results[].status | string | Requerido. Estado actual. Usa el enum declarado cuando esté disponible. Valores: accepted, duplicate, rejected. |
results[].analysisStatus | string | Opcional. Estado actual de la evaluación. Una decisión está disponible solo después de completarse. Valores: pending. |
results[].evaluationId | string | Opcional. Identificador de la evaluación, cuando esté disponible. |
results[].idempotency | objeto | Opcional. Recibo de reintento. |
results[].idempotency.key | string | Requerido. Clave de idempotencia. |
results[].idempotency.replayed | boolean | Requerido. Indica si esta solicitud reutiliza un envío anterior. |
results[].errors | array de string | Opcional. Mensajes de validación. |
results[].message | string | Opcional. Cuerpo del mensaje. |
results[].code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
results[].missingFields | array de string | Opcional. Rutas de campos de entrada faltantes. |
results[].invalidFields | array de string | Opcional. Rutas de campos de entrada inválidos. |
Respuesta 400
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array de string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array de string | Opcional. Rutas de campos de entrada inválidos. |
supported | array de string | Opcional. Indica si la evidencia respalda esta afirmación. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud es exitosa. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array de string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array de string | Opcional. Rutas de campos de entrada inválidos. |
supported | array de string | Opcional. Indica si la evidencia respalda esta afirmación. |
GET /v0/moderation/cases/{caseId}
Campos de solicitud y respuesta
Campos de ruta y consulta
| Campo | Tipo | Requisito y significado |
|---|---|---|
caseId (ruta) | string | Requerido. Identificador del caso aceptado. Úsalo para consultas de estado. Mínimo de caracteres: 1. |
Respuesta 200
| Campo | Tipo | Requisito y significado |
|---|---|---|
caseId | string | Requerido. Identificador del caso aceptado. Úsalo para consultas de estado. |
externalId | string | Requerido. Identificador del productor. Consérvalo en reintentos exactos. |
analysisStatus | string | Requerido. Estado actual de la evaluación. Una decisión está disponible solo después de completarse. Valores: policy_not_configured, pending, running, completed, failed. |
evaluationId | string | Opcional. Identificador de la evaluación, cuando está disponible. |
decision | object | Opcional. Decisión de moderación completada. Lee los campos de decisión anidados. |
decision.disposition | string | Requerido. Disposición final del caso. Valores: age_gate, approve, escalate, reject. |
decision.confidence | string | Requerido. Confianza opcional de 0 a 1. Valores: low, medium, high. |
decision.title | string / null | Requerido. Título del registro. Valor predeterminado: null. |
decision.reason | string | Requerido. Motivo de este resultado. Mínimo de caracteres: 1. |
decision.hits | array of object | Requerido. Reglas que coincidieron con la evaluación. |
decision.hits[].ruleId | string | Requerido. Identificador de la regla que coincidió. Mínimo de caracteres: 1. |
decision.hits[].ruleSlug | string | Requerido. Slug de la regla que coincidió. Mínimo de caracteres: 1. |
decision.hits[].polarity | string | Requerido. Polaridad asignada a la afirmación evaluada. Valores: AMBIGUOUS, NEGATIVE, POSITIVE. |
decision.hits[].confidence | string | Requerido. Confianza opcional de 0 a 1. Valores: low, medium, high. |
decision.hits[].reasoning | string / null | Requerido. Explicación de la evaluación. |
decision.hits[].evidence | array of object | Requerido. Evidencia que respalda esta evaluación. |
decision.hits[].evidence[].modality | string | Requerido. Modalidad de la evidencia. Valores: image, video, text, metadata. |
decision.hits[].evidence[].claim | string | Requerido. Afirmación evaluada por la regla. Mínimo de caracteres: 1. |
decision.hits[].evidence[].locator | object | Opcional. Ubicación de la evidencia dentro de la fuente. |
decision.hits[].evidence[].locator.asset | string | Opcional. Recurso multimedia evaluado por esta evidencia. Valores: public_profile_logo. |
decision.hits[].evidence[].locator.mediaIndex | integer | Opcional. Índice del recurso multimedia que contiene la evidencia. Mínimo: 0. Máximo: 9007199254740991. |
decision.hits[].evidence[].locator.boundingBox | JSON | Opcional. Ubicación de la evidencia dentro de una imagen. |
decision.hits[].evidence[].locator.startSeconds | number | Opcional. Inicio de la evidencia de video, en segundos. Mínimo: 0. |
decision.hits[].evidence[].locator.endSeconds | number | Opcional. Fin de la evidencia de video, en segundos. Mínimo: 0. |
decision.hits[].evidence[].locator.textSpan | object | Opcional. Fragmento de la evidencia dentro del texto. |
decision.hits[].evidence[].locator.textSpan.field | string | Opcional. Campo que contiene la evidencia. Mínimo de caracteres: 1. Máximo de caracteres: 128. |
decision.hits[].evidence[].locator.textSpan.start | integer | Requerido. Inicio del fragmento de evidencia. Mínimo: 0. Máximo: 9007199254740991. |
decision.hits[].evidence[].locator.textSpan.end | integer | Requerido. Fin del fragmento de evidencia. Mínimo: 0. Máximo: 9007199254740991. |
decision.advertiserAssessment | object | Requerido. Evaluación del anunciante en la decisión final. |
decision.advertiserAssessment.polarity | string | Requerido. Polaridad asignada a la afirmación evaluada. Valores: AMBIGUOUS, NEGATIVE, POSITIVE. |
decision.advertiserAssessment.reasoning | string | Requerido. Explicación de la evaluación. Mínimo de caracteres: 1. Máximo de caracteres: 1000. |
decision.landingAssessment | object | Requerido. Evaluación de la página de destino en la decisión final. |
decision.landingAssessment.polarity | string | Requerido. Polaridad asignada a la afirmación evaluada. Valores: AMBIGUOUS, NEGATIVE, POSITIVE. |
decision.landingAssessment.reasoning | string | Requerido. Explicación de la evaluación. Mínimo de caracteres: 1. Máximo de caracteres: 1000. |
decision.decisionSource | string | Requerido. Origen de la decisión. Valor predeterminado: "model". Valores: model, fail_closed. |
decision.failureCode | string / null | Requerido. Falla de evaluación legible por máquina. Valor predeterminado: null. |
decision.failureMessage | string / null | Requerido. Mensaje de falla legible por humanos. Valor predeterminado: null. |
failureCode | string | Opcional. Falla de evaluación legible por máquina. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array of string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array of string | Opcional. Rutas de campos de entrada inválidos. |
supported | array of string | Opcional. Indica si la evidencia respalda esta afirmación. |
Respuesta 404
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. Valores: False. |
error | string | Requerido. Mensaje de error. |
message | string | Opcional. Cuerpo del mensaje. |
code | string | Opcional. Código de error legible por máquina. Valores: MODERATION_INPUT_INCOMPLETE, MODERATION_INPUT_INVALID. |
missingFields | array of string | Opcional. Rutas de campos de entrada faltantes. |
invalidFields | array of string | Opcional. Rutas de campos de entrada inválidos. |
supported | array of string | Opcional. Indica si la evidencia respalda esta afirmación. |
POST /v0/ingest/records
Campos de solicitud y respuesta
Cuerpo JSON
| Campo | Tipo | Requisito y significado |
|---|---|---|
platform | string | Requerido. Plataforma de origen. Valores: DISCORD, SLACK, GITHUB, ZENDESK, TELEGRAM, FACEBOOK_GROUP, TWITTER_COMMUNITY, SALESFORCE, FACEBOOK, TWITTER, THREADS, TIKTOK, INSTAGRAM, LINKEDIN, WHATSAPP, YOUTUBE, GAINSIGHT, APPSTORE, GOOGLE_PLAY, HIGHER_LOGIC, DISCOURSE, CUSTOM_FORM, MODERATION_API, CHROME_WEB_STORE, CANNY. |
serverId | string | Requerido. Identificador de la cuenta o comunidad de origen. Mínimo de caracteres 1. |
serverName | string | Requerido. Nombre de la cuenta o comunidad de origen. Mínimo de caracteres 1. |
channelId | string | Opcional. Identificador del canal de origen. |
channelName | string | Opcional. Nombre del canal de origen. |
processingLevel | string | Opcional. INSIGHTS para el procesamiento normal de insights, o STATS_ONLY para el procesamiento solo de estadísticas. Valores: INSIGHTS, STATS_ONLY. |
source | object | Opcional. Metadatos de origen del productor. |
source.system | string | Requerido. Nombre del sistema productor. Mínimo de caracteres 1. |
source.sourceId | string | Opcional. Identificador de origen del productor. |
records | array of object | Requerido. Lote de registros normalizados, 1 a 500 elementos. Mínimo de elementos 1. Máximo de elementos 500. |
records[].externalId | string | Requerido. Identificador del productor. Consérvalo en reintentos exactos. Mínimo de caracteres 1. |
records[].threadExternalId | string | Opcional. Identificador de hilo del productor. |
records[].parentExternalId | string | Opcional. Identificador del elemento padre del productor. |
records[].authorId | string | Requerido. Identificador del autor. Mínimo de caracteres 1. |
records[].authorName | string | Requerido. Nombre del autor del productor. Mínimo de caracteres 1. |
records[].title | string | Opcional. Título del registro. |
records[].body | string | Requerido. Cuerpo del registro. |
records[].score | number | Opcional. Puntuación opcional de 0 a 5. Mínimo 0. Máximo 5. |
records[].createdAt | string | Requerido. Marca de tiempo de creación. Mínimo de caracteres 1. |
records[].url | string | Opcional. Enlace de origen absoluto HTTP o HTTPS. |
records[].recordType | string | Requerido. Tipo de registro de origen. Mínimo de caracteres 1. |
records[].customFields | object | Opcional. Nombres y valores de campos definidos por la organización. |
Respuesta 202
| Campo | Tipo | Requisito y significado |
|---|---|---|
status | string | Requerido. Estado actual. Usa el enum declarado cuando esté presente. Valores: accepted. |
accepted | number | Requerido. Número de registros de entrada aceptados. |
Respuesta 403
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. Valores: False. |
error | string | Requerido. Mensaje de error. |
Respuesta 422
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. Valores: False. |
error | string | Requerido. Mensaje de error. |
Respuesta 500
| Campo | Tipo | Requisito y significado |
|---|---|---|
success | boolean | Requerido. Indica si la solicitud fue exitosa. Valores: False. |
error | string | Requerido. Mensaje de error. |
Comportamiento de escritura
Las escrituras de campos personalizados requieren una clave con alcance de escritura. Los valores deben coincidir con los tipos de campo registrados de la organización.
Un error de validación puede devolver fieldErrors. Lee las definiciones de campo antes de escribir un valor.
La ingesta de moderación requiere el modo ad_policy de la organización y una clave con alcance de escritura.
Un externalId sin cambios con contenido sin cambios devuelve duplicate en un reintento exacto.
Contenido en conflicto para un ID existente devuelve 409 para un caso individual. Los resultados del lote permanecen ordenados e informan el rechazo por elemento.
Consulta el caseId devuelto. Una decisión aparece solo después de que la evaluación actual se complete.
La ingesta normalizada acepta entre 1 y 500 registros y devuelve aceptación asíncrona. La aceptación no garantiza que el procesamiento esté completo. La identidad del registro usa la organización, la plataforma, el servidor y el ID externo. Conserva estos identificadores para los reintentos.
Consejos
- Mantén los identificadores como strings y conserva los valores nulos.
- Valida los campos de respuesta antes de reutilizarlos en otra solicitud.
- Lee la Referencia de métricas antes de interpretar las unidades de métricas.
- No mezcles envoltorios de respuesta REST con envoltorios de operación MCP.