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 todos los endpoints, ver esquemas de solicitud y respuesta, y probar llamadas directamente en el navegador.
Autenticación
Cada solicitud debe llevar uno de tres encabezados. 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 asistentes de AutoTalk)
Un JWT de corta duración firmado por AutoTalk y emitido por la acción de workflow de asistente actions/security/auth/jwt/generate. El payload es {companyId, ips?, dur?}; 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).
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 JavaScript (actions/code/javascript/execute) 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 |
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 de corta duración 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 |
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