Referencia de la API
- Dónde encontrar la documentación completa de la API de AutoTalk
- Cómo autenticar solicitudes con tu clave de API
- Principales endpoints de la API y qué hacen
AutoTalk expone una API REST pública que permite a aplicaciones externas enviar mensajes a contactos y trabajar con datos dinámicos (Dynadata). La API sigue la especificación OpenAPI 3.0.
Documentación interactiva de la API
La documentación completa e interactiva de la API está disponible en:
Desde allí puedes navegar por los endpoints documentados, ver esquemas de solicitud y respuesta, y probar llamadas directamente en el navegador. El documento publicado no cubre exactamente todo lo que está activo: cuando una ruta listada en esta página falta en él, esta página lo indica en esa ruta.
Autenticación
Cada solicitud debe llevar uno de tres encabezados — con una excepción, el catálogo público de planes que aparece más abajo. Los tres resuelven al mismo contexto de empresa, comparten los mismos límites de uso (medidor mensual api_requests) y dan acceso a los mismos endpoints — solo se diferencian en cómo se emite el token.
x-api-key (recomendado para integraciones externas)
Una clave de API de larga duración (formato sk-…) creada desde el panel de AutoTalk.
x-api-key: sk-YOUR_API_KEY
Para generar una, ve a Integraciones > Tokens de API y haz clic en el botón +. Consulta Tokens de API para instrucciones paso a paso. Este es el encabezado que deseas para cualquier CRM, helpdesk, script o puente personalizado que llame a AutoTalk desde fuera.
x-jwt-token (uso interno de los agentes de AutoTalk)
Un JWT de corta duración firmado por AutoTalk y emitido por la acción de workflow de agente actions/security/auth/jwt/generate. El payload es {companyId, ips?, dur?, scopes?}; la duración predeterminada es 300 segundos, opcionalmente acotada por una lista de IPs permitidas que se verifica contra la IP pública real del emisor tal como la ve el edge de AutoTalk (los encabezados reenviados como x-forwarded-for no son de confianza).
Activa el modo avanzado en esa acción para solicitar además una lista de scopes, y el token emitido queda limitado a esas capacidades en /v1 y en el servidor MCP. Un token emitido sin lista de scopes no lleva el claim scopes y por lo tanto no concede nada: autentica, pero todas las puertas lo rechazan, así que enumera siempre las capacidades que necesitarán tus pasos posteriores. Una lista de scopes suministrada con el modo avanzado desactivado se rechaza (jwt_scopes_require_advanced) en lugar de descartarse en silencio, y un nombre de scope desconocido se rechaza al generar el token (jwt_invalid_scopes) en lugar de ignorarse.
Todo token firmado por AutoTalk lleva ahora un claim kind que indica para qué sirve, y /v1 acepta únicamente kind: "v1" — un token emitido para otra finalidad (la redirección de conexión de canal vía OAuth, por ejemplo) se rechaza con 401. Los tokens se emiten por ejecución y caducan en minutos, así que no hay nada que migrar. La exigencia es incondicional: /v1 rechaza un JWT cuyo claim kind esté ausente, malformado (presente, pero no una cadena utilizable) o distinto de "v1", en cada solicitud. No hay variable de entorno ni paso de despliegue que el operador deba realizar.
x-jwt-token: YOUR_JWT_TOKEN
Los agentes lo usan para llamar a /v1/ en nombre de la propia empresa — típicamente desde un paso de código JavaScript (actions/code/execute con language: "javascript") que recibe step(N).jwt como entrada. No existe un endpoint público para generarlo; los integradores externos deben usar x-api-key.
Un ejemplo completo y funcional está en Discord Spam Moderator — un agente actor que genera un JWT y lo utiliza para eliminar spam de Discord, advertir infractores y expulsar reincidentes.
x-auth-token (encabezado unificado)
Un encabezado de conveniencia que acepta cualquiera de las dos formas. Valores que comienzan con sk- se tratan como claves de API; los demás se validan como JWT (y, si el valor es ambiguo, se intenta primero como JWT).
x-auth-token: sk-YOUR_API_KEY
# o
x-auth-token: YOUR_JWT_TOKEN
Cuando hay varios encabezados presentes, x-jwt-token tiene prioridad sobre x-api-key, y ambos tienen prioridad sobre x-auth-token.
Trata los tres tipos de token como contraseñas. Nunca los incluyas en control de versiones ni los compartas en canales públicos. Si un token es comprometido, revócalo (claves de API) o espera su expiración (JWT) y rótalo.
URL Base
Todas las solicitudes de API usan la siguiente URL base:
https://api.autotalk.io/v1
Principales endpoints
A continuación se muestra una descripción general de las principales áreas de la API. Para detalles completos de solicitud/respuesta, visita la documentación interactiva.
Empresa
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/self | Recuperar el perfil de la empresa autenticada |
Contactos
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/contacts/{contactId}/send_message | Enviar un mensaje a un contacto específico |
Dynadata (datos dinámicos)
Los endpoints de Dynadata te permiten gestionar entidades de datos personalizadas (contactos, pedidos, tickets o cualquier tipo que tu empresa defina).
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/dynadata/types | Listar todos los tipos de Dynadata disponibles |
| POST | /v1/dynadata/type/{type}/list | Listar elementos de un tipo específico |
| GET | /v1/dynadata/type/{type}/item/{_id} | Recuperar un único elemento por ID |
| POST | /v1/dynadata/type/{type}/create | Crear un nuevo elemento |
| POST | /v1/dynadata/type/{type}/update | Actualizar un elemento existente |
| DELETE | /v1/dynadata/type/{type}/item/{_id} | Eliminar un elemento por ID |
| POST | /v1/dynadata/type/{type}/validate | Validar un elemento sin guardar |
| GET | /v1/dynadata/type/{type}/schema | Obtener el esquema JSON de un tipo |
| GET | /v1/dynadata/type/{type}/schema/zod | Obtener el esquema Zod de un tipo |
| POST | /v1/dynadata/type/{type}/executeFunction/{functionName} | Ejecutar una función en un tipo |
| POST | /v1/dynadata/type/{type}/item/{_id}/executeFunction/{functionName} | Ejecutar una función en un elemento específico |
log_entries es de solo lectura a través de la APIcreate, update y delete sobre el tipo log_entries se rechazan en /v1 y en el servidor MCP para todos los llamadores — cualesquiera que sean los permisos que tenga la clave de API, y también para un x-jwt-token. La respuesta es 403 con code: "log_entry_writes_not_allowed". log_entries es el rastro de auditoría que la plataforma escribe sobre tu tráfico de API, así que ningún scope concede la capacidad de falsificar o borrar filas en él. Las lecturas (list, item, schema) no se ven afectadas.
Esto es un cambio de comportamiento: esas escrituras antes funcionaban. Si escribías registros propios en log_entries, muévelos a un tipo de Dynadata propio (un custom type, por ejemplo) — allí create/update/delete siguen igual. El ejemplo publicado Discord Spam Moderator todavía contiene llamadas de ese tipo; ahora fallan, y el ejemplo está escrito de modo que un log fallido no es fatal.
Los operadores self-hosted pueden definir V1_ALLOW_LOG_ENTRY_WRITES=true en el backend para restaurar el comportamiento anterior mientras migran una integración. El valor predeterminado es false y no está disponible en la plataforma alojada.
Almacenamiento
Sube archivos (imágenes, PDFs, audio) y obtén una referencia propia {bucket, fullPath} que puedes pasar a send_message, campos de documentos Dynadata o funciones como createWhatsappWebEvoProduct. Consulta Subir archivos.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/storage/upload-url | Reservar una URL de subida firmada (paso 1) |
| POST | /v1/storage/upload-complete | Finalizar la subida; devuelve {bucket, fullPath} (paso 2) |
| GET | /v1/storage/url | Obtener una URL de descarga firmada, válida hasta 7 días, para un objeto almacenado |
Transcripciones
La API de transcripción asíncrona independiente (issue #822). Encola un trabajo de transcripción para un archivo de audio almacenado y consulta su estado y resultado. Autenticada con tu x-api-key.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/transcriptions | Encolar un trabajo de transcripción |
| GET | /v1/transcriptions/{id} | Obtener el estado y el resultado de un trabajo |
Transformaciones de medios
La API asíncrona de transformación de medios (issue #247). Encola una conversión de formato para un archivo de audio o vídeo almacenado y luego consulta su estado y su salida. Es la misma cola de trabajos que usan la acción de workflow Transformar Medios y la herramienta MCP get_transcode_job, así que un trabajo encolado en cualquier superficie se puede consultar desde las dos que leen: GET /v1/transcodes/{id} y la herramienta get_transcode_job — la acción de workflow solo encola, no lee. El solapamiento termina en la lectura: cancelar y reintentar existen solo aquí, en /v1. El servidor MCP no registra ninguna herramienta de cancelación ni de reintento, y el documento del trabajo es de solo lectura para el tenant, así que un trabajo iniciado desde un workflow o desde MCP se puede cancelar o reintentar por estas dos rutas y por ninguna otra.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/transcodes | Encolar un trabajo de transformación. fullPath y preset son obligatorios; bucket es opcional y usa por defecto el bucket de almacenamiento de la plataforma — un único bucket compartido por todos los tenants, con los archivos de tu empresa bajo su propio prefijo de ruta — así que rara vez hace falta enviarlo. Presets: mp4, ogg_opus, wav, flac_16k_mono |
| GET | /v1/transcodes/{id} | Obtener un trabajo. job.output.bucket y job.output.fullPath son el archivo convertido, y solo se rellenan cuando job.status es done |
| POST | /v1/transcodes/{id}/cancel | Cancelar un trabajo que aún no ha terminado — pending, probing, transcoding o finalizing. Un trabajo en cualquier otro estado es rechazado |
| POST | /v1/transcodes/{id}/retry | Volver a ejecutar desde cero un trabajo failed o canceled. Cualquier otro estado se rechaza, igual que un trabajo cuyo lease de worker siga en el futuro — todo camino que escribe failed o canceled limpia el lease, así que esa segunda condición no debería estorbar normalmente, y ambos rechazos vuelven con el mismo transcode_job_not_retryable. La solicitud pasa por las mismas comprobaciones de cuota de transcoding y de trabajos en cola que el encolado, y la conversión se ejecuta y se cobra de nuevo salvo que esa misma fuente y ese mismo preajuste ya se hayan convertido, en cuyo caso se reutiliza el resultado guardado y no se cobra nada |
Los presets, los límites de tamaño y duración, el tope de trabajos por empresa y los códigos de fallo son los mismos aquí que en la acción de workflow — consulta Transformar Medios.
El documento OpenAPI publicado detrás de api.autotalk.io/docs no lista los endpoints de transformación, así que un cliente generado a partir de él no los tendrá. Las rutas están activas y son compatibles; esta tabla es la referencia hasta que la especificación las incluya.
Voz
Convierte texto en audio almacenado, y antes reescribe el texto escrito en la forma en que se diría. Ninguno de los dos endpoints devuelve bytes de audio: POST /v1/speech almacena el audio y devuelve una referencia {bucket, fullPath} que puedes pasar directamente a send_message, a un campo de archivo de Dynadata o a GET /v1/storage/url.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/speech | Sintetizar text (como máximo 4096 caracteres) en un objeto de audio almacenado. voiceProfileId y format son opcionales. Devuelve la referencia almacenada más size, format y qué medidor se cobró |
| POST | /v1/spoken-text | Reescribir markdown (como máximo 8000 caracteres) en la forma hablada de ese texto. Devuelve solo texto, sin audio |
POST /v1/speech es síncrono — el audio ya existe cuando la llamada regresa y no hay ningún trabajo que consultar. El markdown se lee mal en voz alta, así que ejecuta /v1/spoken-text antes cuando el texto venga de un LLM o de un campo de texto enriquecido. Su salida, eso sí, no está limitada en caracteres — solo en tokens (1200 de ellos), lo que normalmente queda muy por debajo del límite de 4096 caracteres de la síntesis, pero no está garantizado, y menos aún cerca del máximo de 8000 caracteres de entrada. Comprueba el tamaño de la reescritura antes de enviarla a /v1/speech, y divídela si volvió más larga.
Uso
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/usage | La instantánea de uso del tenant: totales de los medidores, tiempo de compute desglosado por categoría, bytes usados de almacenamiento y de base de datos, el plan activo con sus límites resueltos e información del período de suscripción |
Acepta granularity=month (el valor por defecto) o granularity=day. La ventana es un período de calendario en UTC — el mes actual, o desde las 00:00 UTC de hoy con granularity=day — que no es necesariamente tu período de suscripción. La instantánea en sí es la que devuelve la herramienta MCP get_usage — ambas superficies la leen del mismo helper — pero los envoltorios difieren: MCP devuelve la instantánea desnuda, mientras que /v1 la envuelve como {success: true, usage}.
Workflows
Ejecuta un workflow manual de forma directa (issue #218) y lee sus salidas duraderas — la returnExpression evaluada como result, archivos de salida como refs de storage (utilizables con GET /v1/storage/url) y logs por paso. Usa mode: "async" para ejecuciones largas (p. ej., varios pasos de código Python) y consulta el endpoint del run; pasa includeStepOutputs: true para persistir también snapshots por paso.
Verifica siempre ok, no el estado HTTP. Un paso que falla no aborta el workflow, así que un run puede terminar con pasos rotos: en ese caso la respuesta es status: "partial" con ok: false, un error de código workflow_steps_failed y una lista failedSteps: [{step, code, userMessage}]. Solo status: "success" significa que el run hizo lo que debía.
Cuando el fallo forma parte del diseño — un paso cuyo fallo maneja un paso posterior con step_error(N)/step_ok(N), o un efecto secundario opcional — marca permitir fallo en ese paso en el editor de workflows. Su fallo pasa a reportarse como {step, code, userMessage, handled: true}, exactamente igual que antes, pero ya no fuerza status: "partial": un run cuyos únicos fallos son manejados sigue siendo status: "success", ok: true. Cualquier fallo de paso NO declarado así sigue haciendo que el run sea partial.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/workflows/{id}/run | Ejecutar un workflow (mode: "sync" devuelve {ok, result, files, logs, executionTimeMs, runId}; mode: "async" devuelve 202 {runId}) |
| GET | /v1/workflows/{id}/runs/{runId} | Obtener el estado y las salidas duraderas de un run |
Público (sin autenticación)
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/public/plans | El catálogo público de planes. Pasa sellableOnly=true para devolver solo los planes actualmente a la venta |
Este es el único endpoint de esta página que no resuelve ninguna empresa y no exige encabezado de autenticación. Todo lo demás necesita uno de los tres encabezados de arriba.
Igual que los endpoints de transformación de arriba, esta ruta tampoco está en el documento OpenAPI publicado, así que un cliente generado a partir de él no tendrá esta operación. La ruta está activa; es la especificación la que aún no la incluye.
Ejemplo de solicitud
Aquí hay un ejemplo de envío de un mensaje de texto a un contacto usando curl:
curl -X POST https://api.autotalk.io/v1/contacts/CONTACT_ID/send_message \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "text",
"body": {
"text": "Hello! How can we help you today?"
}
}'
Próximos pasos
- Tokens de API -- Genera y gestiona tus claves de API
- Webhooks -- Recibe notificaciones de eventos de AutoTalk
- Workflows -- Automatiza tareas dentro de AutoTalk