Custom API

Conecta tu portal de clientes, sistema de comentarios u otra herramienta a Sift. Custom API importa conversaciones privadas e inicia el análisis de Sift. Las conversaciones importadas usan los estados normales de las acciones. Los moderadores pueden asignárselas, etiquetarlas y cambiar su estado. Sift no puede enviar respuestas a estas conversaciones.

De un vistazoCopy Anchor Link

Qué estás viendoCopy Anchor Link

Abre Settings → Connections → Integrations → Custom API. Cada fuente representa un sistema externo. Sus tres pestañas guían la configuración:

El flujo es: Fuente → Clave Import → Validar → Importar → Recibo → Análisis de Sift.

ConfigurarloCopy Anchor Link

1. Selecciona Add source. Introduce el nombre de la fuente. El nombre del canal predeterminado es opcional y usa el nombre de la fuente de forma predeterminada.
2. En Setup, añade canales o etiquetas de fuente si los necesitas. Conserva el canal con ID externo default.
3. En Fields, asigna los campos personalizados antes de enviarlos.
4. En API keys, crea una clave Import. El valor predeterminado selecciona esta fuente y una caducidad de 90 días.
5. Copia el secreto una vez. Guárdalo en el almacén de secretos de tu herramienta.
6. Copia el endpoint de Setup.

Los administradores de la organización gestionan fuentes y claves. Usa una fuente por sistema externo. Los IDs de elementos y autores se mantienen separados entre fuentes.

Elegir la clave correctaCopy Anchor Link

Usa claves separadas para importar y consultar informes. Las opciones de caducidad son 30 días, 90 días o sin caducidad. La revocación bloquea las solicitudes nuevas.

Enviar un elementoCopy Anchor Link

Guarda este ejemplo como item.json. Sustituye los valores por tu contenido.

{
  "externalId": "feedback-184",
  "text": "Please add CSV export for feedback.",
  "occurredAt": "2026-10-12T09:00:00Z",
  "author": {
    "externalId": "customer-73",
    "name": "Maya Chen"
  }
}

Asigna https://api.getsift.ai a SIFT_API_BASE, el ID de tu fuente a SIFT_SOURCE_ID y tu clave Import a SIFT_IMPORT_KEY. Después envía:

curl --fail-with-body -X POST \
  "$SIFT_API_BASE/v0/sources/$SIFT_SOURCE_ID/items" \
  -H "X-API-Key: $SIFT_IMPORT_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @item.json

Para staging, usa https://api.staging.getsift.ai. Mantén separadas las fuentes y claves de staging y producción.

Los campos obligatorios son externalId, text, occurredAt, author.externalId y author.name. Usa un ID estable de tu sistema. No necesitas un ID de mensaje de plataforma. Usa la fecha original en formato ISO con Z o un desplazamiento de zona horaria.

Try an item en Setup valida el JSON antes de importar. La validación por API usa POST /v0/sources/{sourceId}/items/validate con un array items. Validar no almacena contenido ni inicia el análisis.

Una importación correcta devuelve HTTP 202 y un array receipts. Guarda el ID del recibo, el ID del elemento, la revisión y el estado. La aceptación no significa que el análisis esté completo.

Canales, etiquetas y campos personalizadosCopy Anchor Link

Una fuente admite hasta 50 canales. Las etiquetas de fuente y canal pueden filtrar las conversaciones importadas.

Asigna claves del productor a campos registrados en Fields. Por ejemplo, asigna plan a un campo de autor. Después envía "customFields": {"plan": "Pro"} dentro de author. Las claves sin asignación se rechazan. Las ediciones humanas y los campos verificados permanecen protegidos.

Hilos y respuestasCopy Anchor Link

Para un elemento independiente, omite los IDs de hilo y padre. Para la raíz de un hilo, asigna su propio externalId a threadExternalId. Para una respuesta, envía el ID raíz como threadExternalId y el ID del padre inmediato como parentExternalId.

Importa las raíces primero. Una respuesta no puede ser su propio padre ni raíz. Una respuesta recibida antes de su raíz puede mostrar waiting_for_root.

Consultar el procesamientoCopy Anchor Link

Abre Activity o consulta recibos recientes con GET /v0/sources/{sourceId}/receipts?limit=50. El límite es de 1 a 100; el valor predeterminado es 50.

Los recibos almacenados muestran el análisis actual como completo, pendiente, omitido o no disponible. Open conversation abre la conversación importada. El análisis describe el registro actual, no una revisión concreta del recibo.

La respuesta de recibos recientes incluye recordId, analysisStatus y url. Consulta un recibo con GET /v0/sources/{sourceId}/receipts/{receiptId}. Esta respuesta individual no incluye el estado del análisis.

Sift usa su análisis existente para el contenido importado, incluidos títulos, resúmenes y sentimiento. El procesamiento tarda un tiempo. Si Search no muestra resultados, incluye la fecha original occurredAt en su intervalo.

Lotes, reintentos y correccionesCopy Anchor Link

Envía {"items": [...]} a POST /v0/sources/{sourceId}/items/batch. Usa IDs distintos. Cada elemento tiene un límite de 100 KiB. El texto admite hasta 64.000 caracteres. Los objetos de campos personalizados y metadatos permiten 64 claves y seis niveles anidados. Divide los lotes que superen 100 elementos o 1 MiB.

Si una importación agota el tiempo de espera, reenvía el mismo ID y contenido. Un reintento exacto devuelve el recibo original. El contenido distinto con el mismo ID causa un conflicto. Reintenta una importación fallida con POST /v0/sources/{sourceId}/receipts/{receiptId}/retry. No puedes reintentar trabajo pendiente o completado de esta forma.

Para corregir contenido, envía PATCH /v0/sources/{sourceId}/items/{externalId}:

{
  "expectedRevision": 1,
  "requestId": "7192cdcb-c9d4-4cf4-8c37-d09d8a2ff715",
  "text": "Please add CSV export with dates."
}

Usa la revisión más reciente y un UUID nuevo para cada corrección. Para un reintento de red, reutiliza el UUID y el cuerpo. Puedes corregir texto, título, campos personalizados del elemento o metadatos. La identidad, fecha original, autor, canal e hilo no cambian. Los objetos de campos personalizados y metadatos sustituyen los objetos correspondientes. Incluye los valores que quieras conservar.

Resolver problemasCopy Anchor Link

Pausar bloquea importaciones y correcciones nuevas. Archivar conserva conversaciones y recibos almacenados.

ConsejosCopy Anchor Link

• Mantén estables los IDs de elementos y autores. Codifica los IDs para usarlos en rutas URL.
• Guarda los cuerpos de las solicitudes y los IDs de recibo para reintentar con seguridad.
• No pongas claves en código del navegador, registros ni control de versiones.
• Usa la fecha original, no la fecha de envío de la solicitud.

RelacionadoCopy Anchor Link