Introducción y autenticación
Conectá tu aplicación con las conversaciones, contactos y mensajes de tu CRM. Esta guía usa la API de cuentas: el mismo dominio del panel, un token de usuario y respuestas JSON.
Antes de empezar
| Necesitás | Dónde encontrarlo |
|---|---|
| Dominio del CRM | La dirección donde abrís el panel. En los ejemplos usamos https://crm.ejemplo.com. |
account_id |
El número en /app/accounts/123/.... En ese caso, es 123. |
| Token de usuario | Menú de tu perfil → Ajustes del perfil → Token de acceso. |
| Una cuenta de prueba | Usá una bandeja y un contacto propios para probar operaciones de escritura. |
El token permite actuar como su usuario. Guardalo en el servidor o en variables de entorno. No lo incluyas en código público, aplicaciones del navegador, capturas ni repositorios.
Tu primera consulta
Configurá estas variables en tu terminal. Reemplazá el dominio, la cuenta y el token por los tuyos:
export CRM_BASE_URL="https://crm.ejemplo.com"
export CRM_ACCOUNT_ID="123"
read -rs CRM_API_TOKEN
export CRM_API_TOKEN
El comando read espera que pegues el token y presiones Enter; no lo muestra ni lo guarda como parte del comando en el historial.
Listá las conversaciones de todos los estados:
curl --fail-with-body --get \
"$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations" \
--header "api_access_token: $CRM_API_TOKEN" \
--data-urlencode "status=all" \
--data-urlencode "page=1"
Respuesta abreviada de ejemplo:
{
"data": {
"meta": { "mine_count": 0, "assigned_count": 1, "unassigned_count": 0, "all_count": 1 },
"payload": [
{ "id": 4821, "inbox_id": 12, "status": "open", "labels": [],
"meta": { "sender": { "id": 991, "name": "Ana Pérez" } } }
]
}
}
data.payload: [] es una respuesta válida: no hay conversaciones en esa página o para ese alcance. En una instalación con datos, guardá el id de una conversación para seguir con mensajes.
Autenticación y alcance
Usá el header api_access_token, sin el prefijo Bearer. El token pertenece a un usuario; la ruta determina sobre qué cuenta opera. No es un token distinto por cuenta.
| Aspecto | Comportamiento |
|---|---|
| Cuentas | El usuario debe pertenecer a la cuenta indicada en la URL. |
| Permisos | Se aplican los controles del recurso y del rol. El token no agrega permisos. |
| Solo lectura | El token de usuario no tiene un alcance de solo lectura configurable. |
| Expiración | El token no tiene una fecha de vencimiento automática. |
| Revocación | Coordiná la revocación del token con el administrador. Quitar al usuario de una cuenta retira su acceso a esa cuenta, no a las otras. No asumas que cambiar su contraseña rota el token. |
Para una integración, usá un usuario dedicado con el rol mínimo necesario. Probá tanto una operación permitida como una que deba rechazarse antes de conectarlo a datos reales.
Roles y permisos
| Recurso | Agente | Administrador |
|---|---|---|
| Conversaciones y mensajes | Acceso sujeto a las bandejas y a los permisos configurados. | Acceso de administración de la cuenta. |
| Contactos | La política base permite consultar, buscar, crear y actualizar contactos de la cuenta. No están aislados por bandeja. | Además puede importar, exportar y eliminar contactos. |
| Asignación de conversaciones | Puede restringirse para que solo la gestione un administrador. | Puede gestionar asignaciones. |
| Webhooks y configuración de bandejas | No puede administrarlos con el rol base de agente. | Puede administrarlos. |
| Roles personalizados | Pueden modificar el alcance; verificá la configuración de tu instalación. | Puede configurar el acceso disponible en la instalación. |
La API puede devolver 401 tanto por token inválido como por falta de permisos. Consultá errores y diagnóstico antes de reemplazar un token que funciona en otras rutas.
Cómo leer las respuestas
Las rutas no usan todas el mismo envoltorio JSON. Elegí la clave según el endpoint:
| Request | Dónde está el recurso |
|---|---|
GET .../conversations |
data.payload[]; contadores en data.meta. |
POST .../conversations/filter |
payload[]; contadores en meta. |
GET .../conversations/{id} |
Objeto de conversación en la raíz. |
GET .../conversations/{id}/messages |
payload[]; contexto de la conversación en meta. |
GET .../contacts o GET .../contacts/search |
payload[]; paginación en meta. |
GET .../contacts/{id} |
payload. |
POST .../contacts |
payload.contact; vínculo en payload.contact_inbox. |
Enviá JSON con Content-Type: application/json. Para archivos usá multipart/form-data y dejá que tu cliente HTTP genere el boundary. Los IDs y las fechas se explican en campos disponibles.
Elegí el siguiente paso
- Contactos y bandejas: conectar tu sistema con una conversación.
- Mensajes y adjuntos: enviar texto o archivos.
- Webhooks: recibir cambios sin hacer polling.
- Referencia de API: consultar operaciones y descargar la especificación.
Las guías se enfocan en integraciones de cuentas. La API pública de canales API utiliza otros identificadores y autenticación; no intercambies sus rutas con /api/v1/accounts/.... Las operaciones de plataforma requieren credenciales de administración de la instalación y no forman parte de esta documentación.