Integración TigoChat - TigoVoice
API Trusted — Llamadas
El API Trusted de Llamadas proporciona una interfaz segura y controlada para la gestión de eventos, registros y acciones relacionadas con llamadas dentro de la plataforma. Su propósito es permitir la integración confiable entre sistemas internos o externos, asegurando la trazabilidad, autenticación y control de acceso en cada operación.
A través de este API, los sistemas autorizados pueden crear, consultar y actualizar información asociada a llamadas (entrantes, salientes o transferidas), así como registrar métricas operativas o asociar datos complementarios en tiempo real.
El acceso al API se realiza mediante un endpoint y un token de autenticación que deben ser solicitados a los administradores de Tigo Chat.
Este documento describe los endpoints disponibles, los parámetros requeridos, las estructuras de respuesta y las consideraciones de seguridad necesarias para una correcta implementación bajo el esquema de Trusted Access.
🌐 Base URL
🔐 Autenticación
Debes incluir el token de acceso en cada solicitud utilizando el encabezado:
📤 Crear llamada desde API
{
"user": {
"phone_number": "+56971234123", # Teléfono del cliente (obligatorio pero útil para trazabilidad)
"name": "Onel Cuellar", # Nombre del cliente
"email": "onelsounid@gmail.com" # Correo del cliente (opcional)
},
"custom_attributes": {
"conversation.servicetype": "Personas::fijo", # Tipo de formulario y servicio (formato: Personas/Empresas::servicio)
"request.type": "Comprar o mejorar mi producto", # Motivo principal de la solicitud según catálogo de equivalencias
"call.transactionid": "6381905", # ID de transacción/llamada (único por interacción)
"call.starttime": "2025-11-10T15:30:00Z", # Fecha de inicio de la interacción
"call.direction": "0", # Valores si la llamada es saliente o entrante
"call.status": "1",
"call.queue": "Cola",
"call.center": "TIGOBO",
"telephone.plant": "TigoVoice"
},
"assignee_email": "onel.cuellar@zervizgroup.com", # Correo del agente asignado (solo si se necesita dirigir el ticket)
"attachments": [], # Lista de URLs de archivos adjuntos
"subject": "Llamada entrante - Compra de servicio: +56971234123",
"labels": [
"llamada_inbound",
"formulario_api"
],
"content": (
"📞 *ID:* 6381905\n"
"📱 *CLIENTE:* 33124822\n"
"🔄 *TIPO:* Inbound\n"
"📝 *MOTIVO:* Compra de servicio\n"
"👨💼 *AGENTE:* Onel Cuéllar (ID: 179909)\n"
"🕒 *INICIO:* 24/06/2025 14:07:02\n"
)
}
✅ Respuesta esperada
{'conversation_id': 2685}
⚠️ Mensaje de error
{'error': ['custom_attributes.call.direction is required']}
✏️ Actualizar llamada existente
No todo los campos que están documentados acá, son necesarios, es un payload a modo de ejemplo, consultar con los administradores de TigoChat
{
"custom_attributes": {
"request.type": "Comprar o mejorar mis productos",
"call.endTime": "2025-11-11T10:45:00Z",
"call.waittime": 25,
"call.duration.time": 120,
"call.disconneectedby": "agent"
},
"subject": "Solicitud de Retención PYME",
"assignee_email": "onel.cuellar@zervizgroup.com",
"team_id": 2,
"labels": [
"transferencia_llamada"
],
"internal_note": "*ARCHIVO DE AUDIO:* https://example.com/reco9879870_2024.mp3\n*DURACIÓN:* 02:30 minutos\n*AGENTE:* Onel Cuéllar\n*NOTA:* Cliente interesado en mejorar su plan actual.",
"conversation_audio_files": {
"file_name": "audio-zzzz1.mp3",
"payload": {
"duration": 120,
"size": 45000,
"url": "https://example.com/reco9879870_2024.mp3"
}
}
}
✅ Respuesta esperada
{'conversation_id': 2685}
⚠️ Mensaje de error
{'error': ['custom_attributes.call.direction is required']}
✏️ Actualizar llamada existente desde un archivo de audio
{
"internal_note": "*RESUMEN:* Cliente interesado en mejorar su plan actual."
}
✅ Respuesta esperada
{'conversation_id': 2685}
⚠️ Mensaje de error
{'error': ['custom_attributes.call.direction is required']}
Documento informativo — API Trusted Llamadas. Ajusta los ejemplos según tu entorno.