Conecta tus herramientas y tus agentes de IA a tu bandeja.

Imagim Hilo expone una API REST, webhooks de salida y un servidor MCP. Con ellos, otras apps leen y actúan sobre tu bandeja, se enteran cuando algo pasa, y tu agente de IA (Claude, ChatGPT) la opera en lenguaje natural.

Las integraciones son del plan Crece en adelante. Si tu plan es Base o Emprende, mejóralo para crear llaves y webhooks.

Empezar

1. Entra a tu cuenta en Imagim Hilo, sección API para desarrolladores, y crea una llave con los permisos que necesites. La llave se muestra una sola vez, guárdala bien.

2. Úsala en cada petición con el encabezado de autorización. Todo vive bajo un solo dominio:

Base URL:  https://api.imagimhilo.com
Auth:      Authorization: Bearer ihk_tu_llave

API REST (v1)

Método y ruta	Qué hace	Permiso
`GET /v1/me`	Verifica la llave; devuelve el negocio y sus permisos	—
`GET /v1/contacts`	Lista los contactos	`contacts:read`
`POST /v1/contacts`	Crea un contacto	`contacts:write`
`GET /v1/conversations`	Lista las conversaciones	`conversations:read`
`GET /v1/conversations/{id}/messages`	Mensajes de una conversación	`conversations:read`
`POST /v1/conversations/{id}/messages`	Envía un mensaje (llega por el canal real)	`messages:write`

Ejemplo

# Enviar un mensaje a una conversación
curl -X POST https://api.imagimhilo.com/v1/conversations/123/messages \
  -H "Authorization: Bearer ihk_tu_llave" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hola, ya tenemos stock 💚"}'

Idempotencia. En los POST que crean algo (contactos y mensajes) puedes enviar el encabezado Idempotency-Key con un valor único por operación. Si reintentas con la misma key (por un timeout o un reintento de Zapier), no se vuelve a ejecutar: recibes la misma respuesta y el mensaje NO se manda dos veces al cliente. La misma key con otro cuerpo responde 422.

Webhooks de salida

Que Imagim Hilo le avise a tu app cuando algo pasa, sin que tengas que estar preguntando. Crea el webhook en tu cuenta, elige los eventos y guarda el secreto (se muestra una sola vez).

Evento	Cuándo se dispara
`message.received`	Un cliente escribe un mensaje
`contact.created`	Se crea un contacto nuevo
`conversation.assigned`	Se asigna una conversación a un agente

Verificar la firma

Cada envío trae los encabezados webhook-id, webhook-timestamp y webhook-signature. La firma es v1,<base64> donde el base64 es un HMAC-SHA256, con tu secreto como llave, sobre el texto {id}.{timestamp}.{cuerpo}. Compáralo con el header y descarta si no coincide (protege contra falsificaciones y reenvíos):

import base64, hmac, hashlib

def verificar(secreto, headers, cuerpo_crudo):
    firmado = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.{cuerpo_crudo}"
    esperado = "v1," + base64.b64encode(
        hmac.new(secreto.encode(), firmado.encode(), hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(esperado, headers['webhook-signature'])

Servidor MCP AI-first

Aquí está lo que casi nadie tiene. Conecta tu agente de IA (Claude, ChatGPT, Cursor) a tu bandeja y opérala hablándole normal: "resúmeme los chats de hoy", "cotiza estos productos", "responde a los que preguntaron por envíos".

Endpoint MCP:  https://api.imagimhilo.com/mcp
Transporte:    Streamable HTTP (JSON-RPC 2.0)
Auth:          Authorization: Bearer ihk_tu_llave

En Claude o ChatGPT, agrega un conector/servidor MCP remoto con esa URL y tu llave. El agente descubre las herramientas solo.

Herramientas disponibles

Herramienta	Qué hace	Permiso
`business_info`	Datos del negocio y permisos de la llave	—
`list_conversations`	Conversaciones recientes	`conversations:read`
`list_contacts`	Contactos	`contacts:read`
`get_conversation_messages`	Mensajes de una conversación	`conversations:read`
`send_message`	Enviar un mensaje al cliente	`messages:write`
`search_knowledge`	Buscar en tu base de conocimiento	`knowledge:read`
`list_products`	Catálogo con precios (para cotizar)	`knowledge:read`
`add_note`	Nota interna en una conversación	`conversations:write`
`list_appointments`	Las citas de la agenda (cliente, asesor, estado, enlace de calendario)	`appointments:read`
`appointment_slots`	Cupos libres, por asesor o del equipo	`appointments:read`
`book_appointment`	Agenda una cita y le confirma al cliente por su chat	`appointments:write`
`reschedule_appointment`	Mueve una cita (y avisa al cliente si se lo pides)	`appointments:write`
`cancel_appointment`	Cancela una cita y libera el cupo	`appointments:write`

Permisos (scopes)

Cada llave lleva solo los permisos que le des. Dale lo mínimo que necesite:

contacts:read · contacts:write
conversations:read · conversations:write
knowledge:read
messages:write

Toda petición está acotada a TU negocio: una llave solo ve y toca tus datos. Guarda tus llaves y secretos como contraseñas; si se filtran, revócalos desde tu cuenta.