Referencia de la API

Esta página cubre la API REST server-side para subir catálogos y contenido y recuperar resúmenes de conversaciones. Para integración frontend, ver la Referencia del SDK y los docs de componentes React / Vue.

El endpoint de búsqueda de la storefront (POST /public/search/lexical, llamado con la key pública) no forma parte de esta API: ver Instalar Search en una storefront headless.

Autenticación

Añade tu API key privada de Dialog en el header Authorization de cada request.

Authorization: MY_PRIVATE_KEY

Tu API key privada es visible en el dashboard Dialog después de crear una organización API Integration. Mantenla server-side, no debe shippearse en el navegador.

Resúmenes de conversaciones

Esta API está desactivada por defecto. Contacta con Dialog para habilitar las solicitudes de resúmenes desde la integración del widget. Una vez solicitada la generación, tu servidor puede recuperar el resumen por sessionId con la clave API privada de la misma organización Dialog.

GET https://api.askdialog.ai/integrations/conversation-summaries/{sessionId}
Authorization: MY_PRIVATE_KEY

La respuesta depende del progreso:

HTTP/1.1 202 Accepted
Cache-Control: no-store

{"status":"pending"}

HTTP/1.1 200 OK
Cache-Control: no-store

{"status":"ready","summary":"Resumen de 4.000 caracteres como máximo."}

Consulta de nuevo el endpoint mientras el estado sea pending. No se exige un intervalo de reintento. Una sesión desconocida devuelve 404; un fallo de generación devuelve 409. La sesión debe pertenecer a la organización identificada por tu clave privada.

Upload URLs

Dialog usa URLs S3 pre-firmadas para los uploads de catálogo y contenido.

Obtener upload URLs

POST https://rtbzcxkmwj.execute-api.eu-west-1.amazonaws.com/organization/catalog-upload-url

Respuesta:

{
  "catalogUploadUrl": {
    "url": "your-upload-url",
    "fields": {
      "bucket": "dialog-bucket-name",
      "X-Amz-Algorithm": "",
      "key": "fileKey",
      "Policy": "",
      "X-Amz-Credential": "",
      "X-Amz-Date": "",
      "X-Amz-Signature": "",
      "X-Amz-Security-Token": ""
    }
  },
  "pageUploadUrl": { /* mismo formato */ },
  "blogPostUploadUrl": { /* mismo formato */ }
}

Para cada archivo, usa la URL y los fields para subir al bucket S3 de Dialog. Ver AWS S3 pre-signed URL docs para el flow completo.

Uploads

Upload de catálogo

Sube un archivo JSON que matchea el schema del catálogo. Ver Schema del catálogo para el JSON Schema completo.

Upload de blog

Si tu sitio tiene un blog, sube un array de { title, content }:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "content": { "type": "string" }
    },
    "required": ["title", "content"]
  }
}

Upload de pages

Para FAQ, info de envíos y otras páginas estáticas, sube un array de { title, content } (mismo schema que el blog).

Troubleshooting

Status	Causa probable	Solución
401	Header de auth ausente	Añadir `Authorization: YOUR_KEY`
403	Key inválida o expirada	Regenerar la key en el dashboard
400	Payload no conforme	Validar contra el schema
500	Error del servidor	Escribir al soporte con el ID de request

Suite

Schema del catálogo: formato JSON exacto del upload de catálogo.
Referencia del SDK: integración frontend.