Endpoints

URL base: https://api.zelta.dev/chat/v1

Todos los endpoints requieren autenticacion mediante token Bearer. Consulta la para obtener tu token.

Conversaciones

Listar conversaciones

http

GET /conversations

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 25, max: 100)
`status`	string	Filtrar por estado: `new`, `assigned`, `in_progress`, `on_hold`, `resolved`, `archived`
`channel`	string	Filtrar por canal: `whatsapp`, `email`, `instagram`, `web_chat`, `sms`
`agent_id`	string	Filtrar por agente asignado
`team_id`	string	Filtrar por equipo
`label`	string	Filtrar por etiqueta
`priority`	string	Filtrar por prioridad: `critical`, `high`, `medium`, `low`
`search`	string	Buscar por nombre de contacto, telefono o email
`sort_by`	string	Ordenar por: `created_at`, `updated_at`, `last_message_at`
`sort_dir`	string	Direccion: `asc` o `desc`

Ejemplo:

bash

curl -X GET "https://api.zelta.dev/chat/v1/conversations?status=assigned&channel=whatsapp&page=1" \
  -H "Authorization: Bearer {token}"

Respuesta:

json

{
  "data": [
    {
      "id": "conv_abc123",
      "status": "assigned",
      "channel": "whatsapp",
      "priority": "high",
      "labels": ["Venta", "VIP"],
      "contact": {
        "id": "cont_def456",
        "name": "Maria Garcia",
        "phone": "+50761234567",
        "email": "maria@empresa.com"
      },
      "assigned_agent": {
        "id": "agent_ghi789",
        "name": "Carlos Lopez"
      },
      "team": {
        "id": "team_ventas",
        "name": "Equipo de Ventas"
      },
      "last_message": {
        "content": "Hola, me interesa el plan Enterprise",
        "sent_at": "2026-03-11T14:30:00Z",
        "direction": "inbound"
      },
      "messages_count": 5,
      "created_at": "2026-03-11T14:25:00Z",
      "updated_at": "2026-03-11T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 12,
    "total_count": 287
  }
}

Obtener conversacion

http

GET /conversations/{conversation_id}

Scope requerido: chat:read

Crear conversacion

Inicia una nueva conversacion con un contacto en un canal especifico:

http

POST /conversations

Cuerpo de la peticion:

json

{
  "contact_id": "cont_def456",
  "channel": "whatsapp",
  "initial_message": {
    "type": "template",
    "template_name": "saludo_bienvenida",
    "parameters": ["Maria", "Plan Enterprise"]
  },
  "labels": ["Venta"],
  "priority": "high",
  "assign_to": {
    "type": "agent",
    "id": "agent_ghi789"
  }
}

Scope requerido: chat:write

Ventana de 24 horas (WhatsApp)

Para iniciar conversaciones por WhatsApp fuera de la ventana de 24 horas, debes usar una plantilla de mensaje aprobada por Meta. Indica type: "template" en el campo initial_message.

Actualizar conversacion

http

PATCH /conversations/{conversation_id}

json

{
  "status": "resolved",
  "labels": ["Venta", "Cerrada"],
  "priority": "low"
}

Scope requerido: chat:write

Asignar conversacion

http

POST /conversations/{conversation_id}/assign

json

{
  "type": "agent",
  "id": "agent_ghi789",
  "note": "Cliente VIP, requiere atencion prioritaria"
}

Scope requerido: chat:agents

Transferir conversacion

http

POST /conversations/{conversation_id}/transfer

json

{
  "target_type": "team",
  "target_id": "team_soporte",
  "note": "El cliente necesita soporte tecnico para la integracion API"
}

Scope requerido: chat:agents

Mensajes

Listar mensajes de una conversacion

http

GET /conversations/{conversation_id}/messages

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 50, max: 200)
`type`	string	Filtrar por tipo: `text`, `image`, `video`, `document`, `audio`, `location`, `internal_note`
`direction`	string	Filtrar por direccion: `inbound`, `outbound`

Ejemplo:

bash

curl -X GET "https://api.zelta.dev/chat/v1/conversations/conv_abc123/messages?page=1" \
  -H "Authorization: Bearer {token}"

Respuesta:

json

{
  "data": [
    {
      "id": "msg_001",
      "conversation_id": "conv_abc123",
      "direction": "inbound",
      "type": "text",
      "content": {
        "body": "Hola, me interesa el plan Enterprise"
      },
      "contact": {
        "id": "cont_def456",
        "name": "Maria Garcia"
      },
      "channel": "whatsapp",
      "status": "delivered",
      "created_at": "2026-03-11T14:25:00Z"
    },
    {
      "id": "msg_002",
      "conversation_id": "conv_abc123",
      "direction": "outbound",
      "type": "text",
      "content": {
        "body": "¡Hola Maria! Con gusto te comparto la informacion del plan Enterprise."
      },
      "agent": {
        "id": "agent_ghi789",
        "name": "Carlos Lopez"
      },
      "channel": "whatsapp",
      "status": "read",
      "created_at": "2026-03-11T14:27:00Z"
    },
    {
      "id": "msg_003",
      "conversation_id": "conv_abc123",
      "direction": "internal",
      "type": "internal_note",
      "content": {
        "body": "Cliente interesada en plan Enterprise. Ya le envie la cotizacion por email."
      },
      "agent": {
        "id": "agent_ghi789",
        "name": "Carlos Lopez"
      },
      "created_at": "2026-03-11T14:28:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 3
  }
}

Enviar mensaje

http

POST /conversations/{conversation_id}/messages

Mensaje de texto:

json

{
  "type": "text",
  "content": {
    "body": "Gracias por tu consulta. Te envio la informacion solicitada."
  }
}

Mensaje con imagen:

json

{
  "type": "image",
  "content": {
    "url": "https://cdn.miempresa.com/catalogo/producto-001.jpg",
    "caption": "Nuestro producto estrella - Plan Enterprise"
  }
}

Mensaje con documento:

json

{
  "type": "document",
  "content": {
    "url": "https://cdn.miempresa.com/cotizaciones/cot-2026-001.pdf",
    "filename": "Cotizacion_Enterprise_2026.pdf",
    "caption": "Adjunto la cotizacion del Plan Enterprise"
  }
}

Scope requerido: chat:write

Crear nota interna

http

POST /conversations/{conversation_id}/messages

json

{
  "type": "internal_note",
  "content": {
    "body": "Cliente solicito descuento del 15%. Pendiente aprobacion del supervisor."
  }
}

Scope requerido: chat:write

Notas internas

Las notas internas (internal_note) son visibles unicamente para los agentes y supervisores. Nunca se envian al cliente por ningun canal.

Estados de mensaje

Estado	Descripcion
`queued`	Mensaje en cola para envio
`sent`	Enviado al proveedor del canal
`delivered`	Entregado al dispositivo del cliente
`read`	Leido por el cliente
`failed`	Error en el envio

Contactos

Listar contactos

http

GET /contacts

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 25, max: 100)
`search`	string	Buscar por nombre, email o telefono
`channel`	string	Filtrar por canal de origen
`label`	string	Filtrar por etiqueta
`sort_by`	string	Ordenar por: `created_at`, `name`, `last_seen_at`
`sort_dir`	string	Direccion: `asc` o `desc`

Ejemplo:

bash

curl -X GET "https://api.zelta.dev/chat/v1/contacts?search=maria&channel=whatsapp" \
  -H "Authorization: Bearer {token}"

Respuesta:

json

{
  "data": [
    {
      "id": "cont_def456",
      "name": "Maria Garcia",
      "email": "maria@empresa.com",
      "phone": "+50761234567",
      "channels": ["whatsapp", "email"],
      "labels": ["VIP", "Enterprise"],
      "conversations_count": 12,
      "last_seen_at": "2026-03-11T14:30:00Z",
      "created_at": "2026-01-15T10:00:00Z",
      "custom_fields": {
        "empresa": "Acme Corp",
        "cargo": "Directora Comercial"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}

Crear contacto

http

POST /contacts

json

{
  "name": "Juan Perez",
  "email": "juan@ejemplo.com",
  "phone": "+50769001234",
  "labels": ["Lead"],
  "custom_fields": {
    "empresa": "Tech Solutions",
    "cargo": "Gerente de TI",
    "origen": "Sitio web"
  }
}

Scope requerido: chat:write

Obtener contacto

http

GET /contacts/{contact_id}

Actualizar contacto

http

PATCH /contacts/{contact_id}

json

{
  "name": "Juan Perez Rodriguez",
  "labels": ["Lead", "VIP"],
  "custom_fields": {
    "empresa": "Tech Solutions SA",
    "presupuesto": 50000
  }
}

Scope requerido: chat:write

Eliminar contacto

http

DELETE /contacts/{contact_id}

Scope requerido: chat:admin

Atencion

Eliminar un contacto tambien elimina todas sus conversaciones y mensajes asociados. Esta accion no se puede deshacer.

Canales

Listar canales configurados

http

GET /channels

Respuesta:

json

{
  "data": [
    {
      "id": "ch_whatsapp_001",
      "type": "whatsapp",
      "name": "WhatsApp Principal",
      "phone_number": "+50769279551",
      "status": "active",
      "created_at": "2026-01-10T08:00:00Z"
    },
    {
      "id": "ch_email_001",
      "type": "email",
      "name": "Soporte Email",
      "email_address": "soporte@miempresa.com",
      "status": "active",
      "created_at": "2026-01-10T08:30:00Z"
    },
    {
      "id": "ch_instagram_001",
      "type": "instagram",
      "name": "Instagram Business",
      "username": "@miempresa",
      "status": "active",
      "created_at": "2026-01-12T09:00:00Z"
    }
  ]
}

Scope requerido: chat:read

Obtener canal

http

GET /channels/{channel_id}

Crear canal

http

POST /channels

json

{
  "type": "web_chat",
  "name": "Chat Sitio Web Principal",
  "config": {
    "primary_color": "#0AAA79",
    "greeting": "¡Hola! ¿En que podemos ayudarte?",
    "position": "bottom-right",
    "pre_chat_form": {
      "enabled": true,
      "fields": ["name", "email"]
    }
  }
}

Scope requerido: chat:channels

Actualizar canal

http

PATCH /channels/{channel_id}

Scope requerido: chat:channels

Desactivar canal

http

POST /channels/{channel_id}/deactivate

Scope requerido: chat:channels

Agentes y equipos

Listar agentes

http

GET /agents

Parametros de consulta:

Parametro	Tipo	Descripcion
`status`	string	Filtrar por estado: `online`, `offline`, `away`
`team_id`	string	Filtrar por equipo
`role`	string	Filtrar por rol: `admin`, `supervisor`, `agent`

Respuesta:

json

{
  "data": [
    {
      "id": "agent_ghi789",
      "name": "Carlos Lopez",
      "email": "carlos@miempresa.com",
      "role": "agent",
      "status": "online",
      "teams": ["team_ventas", "team_vip"],
      "active_conversations": 7,
      "skills": ["ventas", "ingles", "soporte_tecnico"]
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 15
  }
}

Scope requerido: chat:agents

Obtener agente

http

GET /agents/{agent_id}

Listar equipos

http

GET /teams

Respuesta:

json

{
  "data": [
    {
      "id": "team_ventas",
      "name": "Equipo de Ventas",
      "members_count": 8,
      "active_conversations": 45,
      "routing_type": "round_robin"
    },
    {
      "id": "team_soporte",
      "name": "Equipo de Soporte",
      "members_count": 5,
      "active_conversations": 32,
      "routing_type": "skills_based"
    }
  ]
}

Scope requerido: chat:agents

Crear equipo

http

POST /teams

json

{
  "name": "Equipo VIP",
  "routing_type": "skills_based",
  "member_ids": ["agent_ghi789", "agent_jkl012"],
  "auto_assign": true,
  "max_conversations_per_agent": 10
}

Scope requerido: chat:admin

Codigos de respuesta

Codigo	Descripcion
`200`	Solicitud exitosa
`201`	Recurso creado exitosamente
`204`	Recurso eliminado exitosamente
`400`	Solicitud mal formada
`401`	No autenticado
`403`	Sin permisos suficientes
`404`	Recurso no encontrado
`409`	Conflicto (ej: conversacion ya asignada a otro agente)
`422`	Error de validacion
`429`	Limite de tasa excedido
`500`	Error interno del servidor

Formato de error

json

{
  "error": "validation_error",
  "message": "No se pudo procesar la solicitud",
  "details": [
    {
      "field": "contact_id",
      "message": "El contacto especificado no existe"
    }
  ]
}

Paginacion

Todos los endpoints de listado soportan paginacion. Usa los campos meta.current_page y meta.total_pages de la respuesta para navegar entre paginas. El maximo de per_page es 100 para la mayoria de endpoints (200 para mensajes).

Webhooks de la API

Para recibir notificaciones en tiempo real sobre eventos de Zelta Chat, consulta la seccion de .

Endpoints ​

Conversaciones ​

Listar conversaciones ​

Obtener conversacion ​

Crear conversacion ​

Actualizar conversacion ​

Asignar conversacion ​

Transferir conversacion ​

Mensajes ​

Listar mensajes de una conversacion ​

Enviar mensaje ​

Crear nota interna ​

Estados de mensaje ​

Contactos ​

Listar contactos ​

Crear contacto ​

Obtener contacto ​

Actualizar contacto ​

Eliminar contacto ​

Canales ​

Listar canales configurados ​

Obtener canal ​

Crear canal ​

Actualizar canal ​

Desactivar canal ​

Agentes y equipos ​

Listar agentes ​

Obtener agente ​

Listar equipos ​

Crear equipo ​

Codigos de respuesta ​

Formato de error ​

Webhooks de la API ​

Endpoints

Conversaciones

Listar conversaciones

Obtener conversacion

Crear conversacion

Actualizar conversacion

Asignar conversacion

Transferir conversacion

Mensajes

Listar mensajes de una conversacion

Enviar mensaje

Crear nota interna

Estados de mensaje

Contactos

Listar contactos

Crear contacto

Obtener contacto

Actualizar contacto

Eliminar contacto

Canales

Listar canales configurados

Obtener canal

Crear canal

Actualizar canal

Desactivar canal

Agentes y equipos

Listar agentes

Obtener agente

Listar equipos

Crear equipo

Codigos de respuesta

Formato de error

Webhooks de la API