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ámetro	Tipo	Descripción
`assignee_type`	string	Tipo de asignación: `assigned`, `unassigned`, `mine`
`status`	string	Estado: `open`, `resolved`, `pending`, `snoozed`
`inbox_id`	integer	Filtrar por bandeja de entrada
`team_id`	integer	Filtrar por equipo
`label`	string	Filtrar por etiqueta
`page`	integer	Nú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",
        "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",
    "labels": ["ventas", "urgente"]
  }'

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:

Estado	Valor numérico	Descripción
`open`	0	Conversación abierta y activa
`resolved`	1	Conversación resuelta
`pending`	2	Conversación pendiente de acción
`snoozed`	3	Conversación pospuesta temporalmente

Cambiar prioridad

http

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

Prioridades disponibles:

Prioridad	Valor numérico
`low`	0
`medium`	1
`high`	2
`urgent`	3

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,
      "sender": {
        "id": 7,
        "name": "María García",
        "type": "contact"
      },
      "attachments": []
    }
  ]
}

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"

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,
  "sender": {
    "id": 5,
    "name": "Carlos López",
    "type": "user"
  },
  "attachments": []
}

Tipos y estados de mensaje

Tipos de mensaje (message_type):

Tipo	Valor numérico	Descripción
`incoming`	0	Mensaje recibido del contacto
`outgoing`	1	Mensaje enviado por un agente
`activity`	2	Mensaje de actividad del sistema
`template`	3	Mensaje de plantilla

Estados de mensaje (status):

Estado	Valor numérico	Descripción
`sent`	0	Mensaje enviado
`delivered`	1	Entregado al dispositivo del contacto
`read`	2	Leído por el contacto
`failed`	3	Error en el envío

Contactos

Listar contactos

http

GET /accounts/{account_id}/contacts

Parámetros de consulta:

Parámetro	Tipo	Descripción
`page`	integer	Número de página
`sort`	string	Campo de ordenamiento
`include_contact_inboxes`	boolean	Incluir 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ódigo	Descripción
`200`	Solicitud exitosa
`201`	Recurso creado exitosamente
`204`	Recurso eliminado exitosamente (sin contenido en la respuesta)
`400`	Solicitud mal formada
`401`	No autenticado o token inválido
`403`	Sin permisos suficientes para esta acción
`404`	Recurso no encontrado
`422`	Error de validación en los datos enviados
`429`	Límite de solicitudes excedido
`500`	Error 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

Ámbito	Límite
General (por IP)	3,000 solicitudes por minuto
Búsqueda	100 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.

Endpoints de la API ​

Conversaciones ​

Listar conversaciones ​

Crear conversación ​

Obtener conversación ​

Actualizar conversación ​

Cambiar estado de conversación ​

Cambiar prioridad ​

Asignar conversación ​

Filtrar conversaciones ​

Buscar conversaciones ​

Mensajes ​

Listar mensajes de una conversación ​

Enviar mensaje ​

Tipos y estados de mensaje ​

Contactos ​

Listar contactos ​

Buscar contactos ​

Crear contacto ​

Obtener contacto ​

Actualizar contacto ​

Eliminar contacto ​

Filtrar contactos ​

Importar contactos ​

Exportar contactos ​

Bandejas de entrada (Inboxes) ​

Listar bandejas de entrada ​

Obtener bandeja de entrada ​

Crear bandeja de entrada ​

Actualizar bandeja de entrada ​

Eliminar bandeja de entrada ​

Agentes ​

Listar agentes ​

Invitar agente ​

Actualizar agente ​

Eliminar agente ​

Equipos ​

Listar equipos ​

Crear equipo ​

Obtener equipo ​

Actualizar equipo ​

Eliminar equipo ​

Etiquetas ​

Listar etiquetas ​

Crear etiqueta ​

Actualizar etiqueta ​

Eliminar etiqueta ​

Endpoints adicionales ​

Búsqueda global ​

Respuestas predefinidas ​

Atributos personalizados ​

Webhooks ​

Reportes ​

Códigos de respuesta ​

Formato de error ​

Límites de tasa ​

Paginación ​

Endpoints de la API

Conversaciones

Listar conversaciones

Crear conversación

Obtener conversación

Actualizar conversación

Cambiar estado de conversación

Cambiar prioridad

Asignar conversación

Filtrar conversaciones

Buscar conversaciones

Mensajes

Listar mensajes de una conversación

Enviar mensaje

Tipos y estados de mensaje

Contactos

Listar contactos

Buscar contactos

Crear contacto

Obtener contacto

Actualizar contacto

Eliminar contacto

Filtrar contactos

Importar contactos

Exportar contactos

Bandejas de entrada (Inboxes)

Listar bandejas de entrada

Obtener bandeja de entrada

Crear bandeja de entrada

Actualizar bandeja de entrada

Eliminar bandeja de entrada

Agentes

Listar agentes

Invitar agente

Actualizar agente

Eliminar agente

Equipos

Listar equipos

Crear equipo

Obtener equipo

Actualizar equipo

Eliminar equipo

Etiquetas

Listar etiquetas

Crear etiqueta

Actualizar etiqueta

Eliminar etiqueta

Endpoints adicionales

Búsqueda global

Respuestas predefinidas

Atributos personalizados

Webhooks

Reportes

Códigos de respuesta

Formato de error

Límites de tasa

Paginación