Skip to content

Endpoints de la API ​

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

Todos los endpoints están bajo el ámbito /accounts/{account_id}/ y requieren autenticación mediante api_access_token. Consulta la para obtener tu token.


Conversaciones ​

Listar conversaciones ​

http
GET /accounts/{account_id}/conversations

Parámetros de consulta:

ParámetroTipoDescripción
assignee_typestringTipo de asignación: assigned, unassigned, mine
statusstringEstado: open, resolved, pending, snoozed
inbox_idintegerFiltrar por bandeja de entrada
team_idintegerFiltrar por equipo
labelstringFiltrar por etiqueta
pageintegerNúmero de página

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/conversations?status=open&assignee_type=mine&page=1" \
  -H "api_access_token: tu_token_aqui"

Respuesta:

json
{
  "data": {
    "meta": {
      "mine_count": 5,
      "assigned_count": 12,
      "unassigned_count": 3,
      "all_count": 15
    },
    "payload": [
      {
        "id": 42,
        "account_id": 1,
        "inbox_id": 3,
        "status": "open",
        "priority": "medium",
        "vip": true,
        "labels": ["ventas", "vip"],
        "custom_attributes": {},
        "meta": {
          "sender": {
            "id": 7,
            "name": "María García",
            "email": "[email protected]",
            "phone_number": "+50761234567"
          },
          "assignee": {
            "id": 5,
            "name": "Carlos López"
          },
          "team": {
            "id": 2,
            "name": "Equipo de Ventas"
          }
        },
        "created_at": 1709145600,
        "updated_at": 1709145600
      }
    ]
  }
}

Crear conversación ​

http
POST /accounts/{account_id}/conversations

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 3,
    "contact_id": 7,
    "status": "open",
    "assignee_id": 5,
    "team_id": 2,
    "message": {
      "content": "Hola, bienvenida a nuestro servicio."
    }
  }'

Obtener conversación ​

http
GET /accounts/{account_id}/conversations/{id}

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/conversations/42" \
  -H "api_access_token: tu_token_aqui"

Actualizar conversación ​

http
PATCH /accounts/{account_id}/conversations/{id}

Ejemplo:

bash
curl -X PATCH "https://chat.zelta.dev/api/v1/accounts/1/conversations/42" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "high",
    "vip": true,
    "labels": ["ventas", "urgente"]
  }'

Campo vip

El campo vip (true o false) marca la conversación como VIP para mantenerla siempre fijada en la parte superior de la bandeja. Puedes actualizarlo desde este endpoint, igual que la prioridad, o desde el endpoint dedicado .

Cambiar estado de conversación ​

http
POST /accounts/{account_id}/conversations/{id}/toggle_status

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/toggle_status" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'

Estados disponibles:

EstadoValor numéricoDescripción
open0Conversación abierta y activa
resolved1Conversación resuelta
pending2Conversación pendiente de acción
snoozed3Conversación pospuesta temporalmente

Cambiar prioridad ​

http
POST /accounts/{account_id}/conversations/{id}/toggle_priority

Prioridades disponibles:

PrioridadValor numérico
low0
medium1
high2
urgent3

Marcar como VIP ​

http
POST /accounts/{account_id}/conversations/{id}/toggle_vip

Marca o desmarca una conversación como VIP. Una conversación VIP se fija automáticamente en la parte superior de la bandeja, sin importar el orden seleccionado, hasta que se quita el estado manualmente.

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/toggle_vip" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "vip": true }'

Envía "vip": false para quitar el estado VIP. El cambio se sincroniza en tiempo real con todos los agentes que están viendo esa bandeja.

Asignar conversación ​

http
POST /accounts/{account_id}/conversations/{id}/assignments

Asigna un agente o equipo a la conversación.

Asignar a un agente:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/assignments" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "assignee_id": 5 }'

Asignar a un equipo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/assignments" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "team_id": 2 }'

Filtrar conversaciones ​

http
POST /accounts/{account_id}/conversations/filter

Permite aplicar filtros avanzados con múltiples condiciones.

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/filter" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": [
      {
        "attribute_key": "status",
        "filter_operator": "equal_to",
        "values": ["open"]
      },
      {
        "attribute_key": "assignee_id",
        "filter_operator": "equal_to",
        "values": [5]
      }
    ]
  }'

Buscar conversaciones ​

http
GET /accounts/{account_id}/conversations/search?q={texto}

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/conversations/search?q=plan+enterprise" \
  -H "api_access_token: tu_token_aqui"

Mensajes ​

Listar mensajes de una conversación ​

http
GET /accounts/{account_id}/conversations/{conversation_id}/messages

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/messages" \
  -H "api_access_token: tu_token_aqui"

Respuesta:

json
{
  "meta": {
    "contact": {
      "id": 7,
      "name": "María García"
    }
  },
  "payload": [
    {
      "id": 101,
      "content": "Hola, me interesa el plan Enterprise",
      "inbox_id": 3,
      "conversation_id": 42,
      "message_type": 0,
      "content_type": "text",
      "status": "sent",
      "private": false,
      "created_at": 1709145600,
      "additional_attributes": {},
      "sender": {
        "id": 7,
        "name": "María García",
        "type": "contact"
      },
      "attachments": []
    }
  ]
}

Campo additional_attributes

Cada mensaje incluye el campo additional_attributes con metadatos propios del mensaje. Cuando el mensaje proviene de una importación o de una integración externa, puede contener el nombre y el avatar del remitente original (por ejemplo senderName y senderAvatarUrl). Si el mensaje no tiene metadatos adicionales, el campo se devuelve vacío.

Enviar mensaje ​

http
POST /accounts/{account_id}/conversations/{conversation_id}/messages

Mensaje de texto:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/messages" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "¡Hola María! Con gusto te comparto la información del plan Enterprise.",
    "message_type": "outgoing",
    "private": false
  }'

Nota interna (solo visible para agentes):

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/messages" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cliente interesada en plan Enterprise. Ya le envié la cotización por email.",
    "private": true
  }'

Notas internas

Cuando private es true, el mensaje se crea como nota interna visible únicamente para agentes y administradores. No se envía al contacto por ningún canal.

Mensaje con archivo adjunto (multipart/form-data):

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/conversations/42/messages" \
  -H "api_access_token: tu_token_aqui" \
  -F "content=Adjunto la cotización del Plan Enterprise" \
  -F "message_type=outgoing" \
  -F "private=false" \
  -F "attachments[]=@/ruta/al/archivo/cotizacion.pdf"

Plantillas de WhatsApp

Las notificaciones de plantilla de WhatsApp (mensajes pre-aprobados enviados con parámetros de plantilla) se entregan siempre, aunque la conversación esté resuelta, asignada a otro agente o el agente que envía esté desconectado. Esta excepción aplica únicamente a las bandejas de WhatsApp y a los mensajes con parámetros de plantilla; los mensajes de texto libre siguen sujetos al control de respuestas habitual.

Respuesta de un mensaje creado:

json
{
  "id": 102,
  "content": "¡Hola María! Con gusto te comparto la información del plan Enterprise.",
  "inbox_id": 3,
  "conversation_id": 42,
  "message_type": 1,
  "content_type": "text",
  "status": "sent",
  "private": false,
  "created_at": 1709145900,
  "additional_attributes": {},
  "sender": {
    "id": 5,
    "name": "Carlos López",
    "type": "user"
  },
  "attachments": []
}

Tipos y estados de mensaje ​

Tipos de mensaje (message_type):

TipoValor numéricoDescripción
incoming0Mensaje recibido del contacto
outgoing1Mensaje enviado por un agente
activity2Mensaje de actividad del sistema
template3Mensaje de plantilla

Estados de mensaje (status):

EstadoValor numéricoDescripción
sent0Mensaje enviado
delivered1Entregado al dispositivo del contacto
read2Leído por el contacto
failed3Error en el envío

Contactos ​

Listar contactos ​

http
GET /accounts/{account_id}/contacts

Parámetros de consulta:

ParámetroTipoDescripción
pageintegerNúmero de página
sortstringCampo de ordenamiento
include_contact_inboxesbooleanIncluir las bandejas asociadas al contacto

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/contacts?page=1" \
  -H "api_access_token: tu_token_aqui"

Respuesta:

json
{
  "meta": {
    "count": 156,
    "current_page": 1
  },
  "payload": [
    {
      "id": 7,
      "name": "María García",
      "email": "[email protected]",
      "phone_number": "+50761234567",
      "availability_status": "online",
      "custom_attributes": {
        "empresa": "Acme Corp"
      },
      "last_activity_at": 1709145600,
      "created_at": 1709145600
    }
  ]
}

Buscar contactos ​

http
GET /accounts/{account_id}/contacts/search?q={texto}

Busca contactos por nombre, correo electrónico o número de teléfono.

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/contacts/search?q=maria" \
  -H "api_access_token: tu_token_aqui"

Crear contacto ​

http
POST /accounts/{account_id}/contacts

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/contacts" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "email": "[email protected]",
    "phone_number": "+50769001234",
    "custom_attributes": {
      "empresa": "Tech Solutions",
      "cargo": "Gerente de TI"
    }
  }'

Obtener contacto ​

http
GET /accounts/{account_id}/contacts/{id}

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/contacts/7" \
  -H "api_access_token: tu_token_aqui"

Actualizar contacto ​

http
PATCH /accounts/{account_id}/contacts/{id}

Ejemplo:

bash
curl -X PATCH "https://chat.zelta.dev/api/v1/accounts/1/contacts/7" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María García de López",
    "custom_attributes": {
      "empresa": "Acme Corp",
      "cargo": "Directora Comercial"
    }
  }'

Eliminar contacto ​

http
DELETE /accounts/{account_id}/contacts/{id}

Ejemplo:

bash
curl -X DELETE "https://chat.zelta.dev/api/v1/accounts/1/contacts/7" \
  -H "api_access_token: tu_token_aqui"

Acción irreversible

Eliminar un contacto también elimina todas sus conversaciones y mensajes asociados. Esta acción no se puede deshacer.

Filtrar contactos ​

http
POST /accounts/{account_id}/contacts/filter

Permite aplicar filtros avanzados con múltiples condiciones, de forma similar al filtro de conversaciones.

Importar contactos ​

http
POST /accounts/{account_id}/contacts/import

Importa contactos desde un archivo CSV. Envía el archivo como multipart/form-data.

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/contacts/import" \
  -H "api_access_token: tu_token_aqui" \
  -F "import_file=@/ruta/al/archivo/contactos.csv"

Exportar contactos ​

http
POST /accounts/{account_id}/contacts/export

Inicia la exportación de contactos. El archivo se envía al correo del solicitante.


Bandejas de entrada (Inboxes) ​

En la API, los canales de comunicación se gestionan como bandejas de entrada (inboxes). Cada bandeja representa un canal conectado: WhatsApp, correo electrónico, chat web, Instagram, entre otros.

Listar bandejas de entrada ​

http
GET /accounts/{account_id}/inboxes

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/inboxes" \
  -H "api_access_token: tu_token_aqui"

Respuesta:

json
{
  "payload": [
    {
      "id": 3,
      "name": "WhatsApp Principal",
      "channel_type": "Channel::Whatsapp",
      "greeting_enabled": false,
      "greeting_message": "",
      "enable_auto_assignment": true,
      "out_of_office_message": "",
      "working_hours_enabled": false
    },
    {
      "id": 4,
      "name": "Soporte Email",
      "channel_type": "Channel::Email",
      "greeting_enabled": true,
      "greeting_message": "¡Gracias por contactarnos! Responderemos a la brevedad.",
      "enable_auto_assignment": true,
      "out_of_office_message": "Nuestro horario es de lunes a viernes, 8am a 5pm.",
      "working_hours_enabled": true
    }
  ]
}

Obtener bandeja de entrada ​

http
GET /accounts/{account_id}/inboxes/{id}

Crear bandeja de entrada ​

http
POST /accounts/{account_id}/inboxes

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/inboxes" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chat del Sitio Web",
    "channel": {
      "type": "web_widget",
      "website_url": "https://miempresa.com"
    }
  }'

Actualizar bandeja de entrada ​

http
PATCH /accounts/{account_id}/inboxes/{id}

Ejemplo:

bash
curl -X PATCH "https://chat.zelta.dev/api/v1/accounts/1/inboxes/3" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_auto_assignment": false,
    "greeting_enabled": true,
    "greeting_message": "¡Hola! Un momento, por favor."
  }'

Eliminar bandeja de entrada ​

http
DELETE /accounts/{account_id}/inboxes/{id}

Precaución

Eliminar una bandeja de entrada desconecta el canal. Las conversaciones existentes se conservan, pero no se podrán recibir ni enviar nuevos mensajes por ese canal.


Agentes ​

Listar agentes ​

http
GET /accounts/{account_id}/agents

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/agents" \
  -H "api_access_token: tu_token_aqui"

Respuesta (arreglo directo):

json
[
  {
    "id": 5,
    "name": "Carlos López",
    "email": "[email protected]",
    "role": "agent",
    "availability_status": "online",
    "confirmed": true
  },
  {
    "id": 8,
    "name": "Ana Rodríguez",
    "email": "[email protected]",
    "role": "administrator",
    "availability_status": "busy",
    "confirmed": true
  }
]

Formato de respuesta

La lista de agentes devuelve un arreglo directo, sin objeto envolvente data ni payload.

Invitar agente ​

http
POST /accounts/{account_id}/agents

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/agents" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Roberto Morales",
    "email": "[email protected]",
    "role": "agent"
  }'

Actualizar agente ​

http
PATCH /accounts/{account_id}/agents/{id}

Ejemplo:

bash
curl -X PATCH "https://chat.zelta.dev/api/v1/accounts/1/agents/5" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "administrator",
    "availability": "online"
  }'

Eliminar agente ​

http
DELETE /accounts/{account_id}/agents/{id}

Equipos ​

Listar equipos ​

http
GET /accounts/{account_id}/teams

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/teams" \
  -H "api_access_token: tu_token_aqui"

Respuesta (arreglo directo):

json
[
  {
    "id": 2,
    "name": "Equipo de Ventas",
    "description": "Equipo dedicado a ventas y prospección",
    "allow_auto_assign": true
  },
  {
    "id": 3,
    "name": "Soporte Técnico",
    "description": "Atención de consultas técnicas y resolución de problemas",
    "allow_auto_assign": true
  }
]

Crear equipo ​

http
POST /accounts/{account_id}/teams

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/teams" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Equipo VIP",
    "description": "Atención exclusiva para clientes premium",
    "allow_auto_assign": true
  }'

Obtener equipo ​

http
GET /accounts/{account_id}/teams/{id}

Actualizar equipo ​

http
PATCH /accounts/{account_id}/teams/{id}

Eliminar equipo ​

http
DELETE /accounts/{account_id}/teams/{id}

Etiquetas ​

Listar etiquetas ​

http
GET /accounts/{account_id}/labels

Ejemplo:

bash
curl -X GET "https://chat.zelta.dev/api/v1/accounts/1/labels" \
  -H "api_access_token: tu_token_aqui"

Crear etiqueta ​

http
POST /accounts/{account_id}/labels

Ejemplo:

bash
curl -X POST "https://chat.zelta.dev/api/v1/accounts/1/labels" \
  -H "api_access_token: tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "vip",
    "description": "Clientes con atención prioritaria",
    "color": "#FF6B00",
    "show_on_sidebar": true
  }'

Actualizar etiqueta ​

http
PATCH /accounts/{account_id}/labels/{id}

Eliminar etiqueta ​

http
DELETE /accounts/{account_id}/labels/{id}

Endpoints adicionales ​

Búsqueda global ​

http
GET /accounts/{account_id}/search?q={texto}

Busca simultáneamente en conversaciones, mensajes y contactos.

Respuestas predefinidas ​

CRUD completo disponible en:

GET    /accounts/{account_id}/canned_responses
POST   /accounts/{account_id}/canned_responses
PATCH  /accounts/{account_id}/canned_responses/{id}
DELETE /accounts/{account_id}/canned_responses/{id}

Las respuestas predefinidas permiten a los agentes insertar textos frecuentes rápidamente usando atajos de teclado.

Atributos personalizados ​

CRUD completo disponible en:

GET    /accounts/{account_id}/custom_attribute_definitions
POST   /accounts/{account_id}/custom_attribute_definitions
PATCH  /accounts/{account_id}/custom_attribute_definitions/{id}
DELETE /accounts/{account_id}/custom_attribute_definitions/{id}

Define atributos personalizados para contactos y conversaciones (por ejemplo: empresa, plan contratado, origen del lead).

Webhooks ​

CRUD completo disponible en:

GET    /accounts/{account_id}/webhooks
POST   /accounts/{account_id}/webhooks
PATCH  /accounts/{account_id}/webhooks/{id}
DELETE /accounts/{account_id}/webhooks/{id}

Configura URLs para recibir notificaciones en tiempo real sobre eventos del sistema. Consulta la sección de para más detalles.

Reportes ​

http
GET /api/v2/accounts/{account_id}/reports

Versión de la API

Los reportes utilizan la versión 2 de la API (/api/v2/). Los sub-endpoints disponibles permiten obtener métricas de conversaciones, agentes, equipos y bandejas de entrada en distintos rangos de tiempo.


Códigos de respuesta ​

CódigoDescripción
200Solicitud exitosa
201Recurso creado exitosamente
204Recurso eliminado exitosamente (sin contenido en la respuesta)
400Solicitud mal formada
401No autenticado o token inválido
403Sin permisos suficientes para esta acción
404Recurso no encontrado
422Error de validación en los datos enviados
429Límite de solicitudes excedido
500Error interno del servidor

Formato de error ​

json
{
  "error": "invalid_params",
  "message": "No se pudo procesar la solicitud",
  "errors": [
    "El campo 'name' es obligatorio"
  ]
}

Límites de tasa ​

ÁmbitoLímite
General (por IP)3,000 solicitudes por minuto
Búsqueda100 solicitudes por minuto
Reportes (por usuario)100 solicitudes por minuto

Cuando se excede el límite, la API responde con código 429 Too Many Requests. Espera el tiempo indicado en el encabezado Retry-After antes de reintentar.


Paginación ​

Los endpoints de listado que devuelven múltiples resultados incluyen metadatos de paginación. El formato varía según el recurso:

  • Conversaciones: el objeto meta dentro de data contiene contadores (mine_count, assigned_count, unassigned_count, all_count) y los resultados están en data.payload.
  • Contactos: el objeto meta contiene count y current_page, y los resultados están en payload.
  • Mensajes: estructura similar con meta y payload.
  • Agentes, equipos: devuelven arreglos directos sin paginación.

Utiliza el parámetro page para navegar entre páginas de resultados.

Documentación oficial de Zelta