Canal API

El canal API es un canal genérico basado en webhooks que te permite integrar cualquier plataforma de mensajería o sistema externo con Zelta Chat. Es la opción ideal cuando necesitas conectar un canal que no tiene integración nativa o cuando quieres crear un flujo de comunicación personalizado.

Casos de uso

Caso de uso	Descripción
Canal de mensajería propio	Integra tu propia app de chat o sistema de mensajería interno
Plataformas sin integración nativa	Conecta servicios de mensajería que no tienen canal dedicado
Sistemas de tickets	Recibe notificaciones de sistemas externos como conversaciones
Formularios web	Convierte envíos de formularios en conversaciones de soporte
Integraciones a medida	Cualquier sistema que pueda enviar y recibir HTTP

Crear un canal API

1. Ve a Ajustes > Canales > + Agregar canal.
2. Selecciona API.
3. Completa los campos:

Campo	Descripción
Nombre del canal	Nombre descriptivo (ej: "Canal Personalizado - App Móvil")
URL de webhook (opcional)	URL donde Zelta Chat enviará los mensajes salientes
Clave de webhook (opcional)	Clave secreta para firmar las peticiones salientes

4. Haz clic en Crear canal.

Después de crear el canal, Zelta Chat te proporcionará:

• URL de entrada (inbound): Donde tu sistema debe enviar los mensajes entrantes
• Token del canal: Para autenticar las peticiones

Enviar mensajes a Zelta Chat (Inbound)

Para crear o continuar una conversación, envía una petición POST a la URL de entrada del canal.

Crear una conversación nueva

curl -X POST https://chat.zelta.dev/api/v1/channels/api/messages \
  -H "Content-Type: application/json" \
  -H "api_access_token: TU_TOKEN_DE_CANAL" \
  -d '{
    "content": "Hola, necesito ayuda con mi pedido",
    "message_type": "incoming",
    "contact": {
      "name": "Juan Pérez",
      "email": "[email protected]",
      "phone": "+507 6000 0000",
      "identifier": "cliente_12345"
    },
    "additional_attributes": {
      "order_id": "ORD-2024-001",
      "source": "app_movil"
    }
  }'

Respuesta exitosa

{
  "id": 1234,
  "content": "Hola, necesito ayuda con mi pedido",
  "message_type": "incoming",
  "conversation_id": 567,
  "contact": {
    "id": 89,
    "name": "Juan Pérez"
  }
}

Continuar una conversación existente

Para agregar mensajes a una conversación existente, incluye el conversation_id:

curl -X POST https://chat.zelta.dev/api/v1/channels/api/messages \
  -H "Content-Type: application/json" \
  -H "api_access_token: TU_TOKEN_DE_CANAL" \
  -d '{
    "content": "Ya encontré mi número de pedido: ORD-2024-001",
    "message_type": "incoming",
    "conversation_id": 567,
    "contact": {
      "identifier": "cliente_12345"
    }
  }'

Recibir mensajes de Zelta Chat (Outbound)

Cuando un agente responde a una conversación del canal API, Zelta Chat envía una petición POST a la URL de webhook que configuraste.

Formato del webhook saliente

{
  "event": "message_created",
  "message": {
    "id": 5678,
    "content": "Hola Juan, con gusto te ayudo. ¿Puedes compartirme tu número de pedido?",
    "message_type": "outgoing",
    "conversation_id": 567,
    "created_at": "2024-03-15T10:30:00Z"
  },
  "conversation": {
    "id": 567,
    "status": "open"
  },
  "contact": {
    "id": 89,
    "name": "Juan Pérez",
    "identifier": "cliente_12345"
  },
  "sender": {
    "id": 12,
    "name": "María López",
    "type": "agent"
  }
}

Verificar la firma del webhook

Si configuraste una clave de webhook, cada petición incluye un encabezado X-Zelta-Signature con una firma HMAC-SHA256:

X-Zelta-Signature: sha256=abc123def456...

Verifica la firma en tu servidor comparando el hash del cuerpo de la petición con la clave secreta:

const crypto = require('crypto');

function verificarFirma(cuerpo, firma, claveSecreta) {
  const hash = crypto
    .createHmac('sha256', claveSecreta)
    .update(cuerpo)
    .digest('hex');
  return firma === `sha256=${hash}`;
}

Seguridad

Siempre verifica la firma del webhook antes de procesar la petición. Esto garantiza que la petición proviene de Zelta Chat y no fue alterada.

Autenticación

Todas las peticiones al canal API deben incluir el token de autenticación:

Método	Detalle
Header	api_access_token: TU_TOKEN_DE_CANAL
Ubicación del token	Ajustes > Canales > [Tu canal API] > Token

Formato de la petición (Inbound)

Campos del mensaje

Campo	Tipo	Requerido	Descripción
content	string	Sí	Contenido del mensaje
message_type	string	Sí	incoming para mensajes del cliente
conversation_id	integer	No	ID de conversación existente (omitir para crear nueva)
contact.name	string	Sí (nueva)	Nombre del contacto
contact.email	string	No	Correo electrónico del contacto
contact.phone	string	No	Teléfono del contacto
contact.identifier	string	Recomendado	Identificador único del contacto en tu sistema
additional_attributes	object	No	Atributos personalizados en formato clave-valor

Enviar archivos adjuntos

curl -X POST https://chat.zelta.dev/api/v1/channels/api/messages \
  -H "api_access_token: TU_TOKEN_DE_CANAL" \
  -F "content=Adjunto mi comprobante de pago" \
  -F "message_type=incoming" \
  -F "contact[identifier]=cliente_12345" \
  -F "attachments[]=@/ruta/al/archivo.pdf"

Eventos del webhook

Evento	Descripción
message_created	Un agente envió un mensaje en la conversación
conversation_status_changed	El estado de la conversación cambió (abierta, pendiente, pospuesta, resuelta)
conversation_created	Se creó una nueva conversación

Solución de problemas

Problema	Solución
Error 401	Verifica que el token de acceso sea correcto
Error 422	Revisa que el cuerpo de la petición tenga los campos requeridos
Webhook no recibe eventos	Confirma que la URL de webhook sea accesible públicamente
Conversaciones duplicadas	Usa el campo identifier del contacto de forma consistente
Archivos no se envían	Usa multipart/form-data en lugar de application/json para adjuntos

Consejo

Usa el campo contact.identifier como clave única para vincular contactos entre tu sistema y Zelta Chat. Esto evita la creación de contactos duplicados.