WEB API

La Web API es un conjunto de funciones HTTP que te permite trabajar con tu cuenta de ZampiBot desde tu propio servidor: crear usuarios, abrir conversaciones, enviar mensajes, leer artículos, enviar mensajes por WhatsApp y mucho más. Está pensada para desarrolladores que quieren conectar ZampiBot con otros sistemas (un CRM, una tienda, un ERP).

Importante: la Web API se llama siempre desde un servidor, nunca desde el navegador de tus visitantes. El token da acceso de administrador a toda tu cuenta. Si quieres actuar desde la página web donde está el chat, usa la API de JavaScript .

Configuración y uso

Dirección de la API

Todas las llamadas son peticiones POST a esta dirección:

https://chatbot.zampisoft.com/script/include/api.php

Tu token de API

Cada llamada debe incluir el token de API de tu cuenta.

Entra en el portal de tu cuenta: https://chatbot.zampisoft.com/app/portal/
Abre Instalación.
En la tarjeta Token de API pulsa Mostrar y copia el token.

Solo el titular de la cuenta ve el token. Si entras al portal como agente, la tarjeta Token de API no aparece.

Guarda el token en secreto. Quien lo tenga puede leer y modificar todos los datos de tu cuenta. No lo pongas nunca en el código de una página web ni en una app que se distribuya.

Las llamadas hechas con este token se ejecutan como el usuario administrador titular de la cuenta.

Cómo enviar los parámetros

token Requerido: tu token de API.
function Requerido: el nombre de la función (por ejemplo get-user). La lista completa está más abajo.
El resto de parámetros de cada función.

Puedes enviarlos como formulario (application/x-www-form-urlencoded) o como JSON (Content-Type: application/json). Te recomendamos JSON: los parámetros que son listas u objetos (por ejemplo attachments, user_ids o extra) llegan tal cual, sin tener que convertirlos a texto.

El token debe ir dentro del cuerpo de la petición (como token). En ZampiBot cloud no se acepta en una cabecera HTTP.

Ejemplo con cURL

curl -X POST https://chatbot.zampisoft.com/script/include/api.php \
  -H "Content-Type: application/json" \
  -d '{"token": "TU-TOKEN", "function": "get-user", "user_id": 123}'

Ejemplo con PHP

function zampibot_api($query) {
    $ch = curl_init('https://chatbot.zampisoft.com/script/include/api.php');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(array_merge(['token' => 'TU-TOKEN'], $query))
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Ejemplo de uso
$user = zampibot_api(['function' => 'get-user', 'user_id' => 123]);

Reemplaza TU-TOKEN por tu token de API.

Respuestas

Si la llamada funciona, la respuesta es un JSON con esta forma:

{
    "success": true,
    "response": "...el resultado de la función..."
}

Si la función rechaza los datos (por ejemplo, un correo duplicado), success vale false y response trae el código del problema:

{
    "success": false,
    "response": "duplicate-email"
}

Si hay un error, la respuesta tiene esta forma:

{
    "status": "error",
    "response": "missing-argument",
    "message": "Missing argument: user_id"
}

Errores más comunes:

Código	Qué significa
`missing-function-name`	Falta el parámetro `function`.
`function-not-found`	La función no existe (HTTP 404). Revisa el nombre.
`token-not-found`	Falta el token (HTTP 401).
`invalid-token`	El token no es válido (HTTP 401).
`missing-argument`	Falta un parámetro obligatorio (HTTP 400). El mensaje dice cuál.
`security-error`	La operación no está permitida.

Códigos que se repiten

Estados de una conversación (status_code):

Código	Estado
`0`	Activa (sin leer)
`1`	Esperando respuesta del usuario
`2`	Esperando respuesta del agente
`3`	Archivada
`4`	Papelera

Canal de origen de una conversación (source): vacío = chat web, em = correo, tk = ticket, wa = WhatsApp, fb = Facebook Messenger, ig = Instagram, tg = Telegram, vb = Viber, ln = LINE, wc = WeChat, za = Zalo, tm = mensaje de texto (SMS).

Adjuntos (attachments): lista de pares nombre + URL, por ejemplo [["factura.pdf", "https://tu-sitio.com/factura.pdf"], ["foto.jpg", "https://tu-sitio.com/foto.jpg"]]. La API no sube archivos: el archivo ya tiene que estar publicado en una URL accesible.

Fechas: se guardan en UTC. Cuando una función pide una fecha, usa el formato AAAA-MM-DD HH:MM:SS (por ejemplo 2026-05-13 13:35:59); también puedes enviar solo la fecha.

👥 Usuarios

Funciones para gestionar usuarios, agentes y administradores.

get-user

Devuelve los datos de un usuario.

user_id Requerido: el ID del usuario.
extra: ponlo en true para incluir también los datos adicionales del usuario (teléfono, ciudad, etc.). Por defecto: false.

{
    "success": true,
    "response": {
        "id": "123456",
        "first_name": "Juan",
        "last_name": "Pérez",
        "email": "juan@example.com",
        "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
        "user_type": "visitor",
        "creation_time": "2026-05-12 14:28:57",
        "last_activity": "2026-05-12 14:28:57",
        "department": null,
        "token": "a521773c5a566a251c3fb00e93162b20ff955b12",
        "password": "",
        "details": [
            {
                "slug": "location",
                "name": "Location",
                "value": "Bogotá, Colombia"
            }
        ]
    }
}

Si el usuario no existe, devuelve {"success": true, "response": false}.

get-user-by

Busca un usuario por uno de sus datos y lo devuelve.

by Requerido: el dato por el que buscar. Valores: email, first_name, last_name, phone o el identificador de cualquier dato adicional del usuario.
value Requerido: el valor a buscar.

{
    "success": true,
    "response": {
        "id": "881",
        "first_name": "Juan",
        "last_name": "Pérez",
        "email": "juan@example.com",
        "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
        "user_type": "user",
        "creation_time": "2026-05-12 14:28:57",
        "last_activity": "2026-05-12 14:28:57",
        "department": null,
        "token": "a521773c5a566a251c3fb00e93162b20ff955b12"
    }
}

Si no lo encuentra, devuelve {"success": true, "response": false}.

get-user-extra

Devuelve los datos adicionales de un usuario.

user_id Requerido: el ID del usuario.
slug: el identificador del dato que quieres. Si no lo envías, devuelve todos. Por defecto: false.
default: el valor a devolver si el dato no existe. Por defecto: false.

{
    "success": true,
    "response": [
        {
            "slug": "phone",
            "name": "Phone",
            "value": "+57 300 1234567"
        }
    ]
}

get-user-language

Devuelve el código del idioma del usuario (por defecto, el idioma de su navegador).

user_id Requerido: el ID del usuario.

get-users

Devuelve la lista de usuarios.

sorting: orden de los resultados, como lista ["columna", "orden"]. Columnas: first_name, last_name, email, profile_image, user_type, creation_time, last_activity, department. Orden: ASC o DESC. Por defecto: ["creation_time", "DESC"].
user_types: lista de tipos de usuario a incluir, por ejemplo ["lead", "user"]. Valores: visitor, lead, user, agent, admin. Por defecto: todos.
search: texto a buscar.
pagination: página de resultados. 0 devuelve los primeros 100, 1 del 101 al 200, etc.
extra: true para incluir todos los datos adicionales, o una lista de identificadores para incluir solo algunos. Por defecto: false.
users_id: lista de IDs; si la envías, solo devuelve esos usuarios. Por defecto: false.
department: devuelve solo usuarios con al menos una conversación en ese departamento (ID). Por defecto: false.
tag: devuelve solo usuarios con al menos una conversación con esa etiqueta. Por defecto: false.
source: devuelve solo usuarios con al menos una conversación de ese canal (ver los códigos de canal arriba). Por defecto: false.

get-new-users

Devuelve los usuarios creados después de una fecha o de un ID de usuario.

datetime Requerido: un ID de usuario o una fecha (AAAA-MM-DD HH:MM:SS, en UTC).

get-online-users

Devuelve los usuarios conectados en este momento, incluidos los agentes.

sorting: orden de los resultados, como lista ["columna", "orden"]. Por defecto: ["last_activity", "DESC"].
agents: true para devolver solo agentes y administradores. Por defecto: false.

get-users-with-details

Devuelve los IDs y los valores de los usuarios que tienen los datos pedidos.

details Requerido: lista de datos, por ejemplo ["email", "phone"].
user_ids: lista o texto separado por comas con los IDs donde buscar. Usa all o false para buscar en todos, o agents para buscar solo agentes y administradores. Por defecto: false.

{
    "success": true,
    "response": {
        "email": [
            { "id": "1", "value": "juan@example.com" },
            { "id": "2", "value": "ana@example.com" }
        ],
        "phone": [
            { "id": "1", "value": "+573001234567" }
        ]
    }
}

get-agent

Devuelve los datos de un agente, administrador o bot.

agent_id Requerido: el ID del agente.

get-agents-ids

Devuelve la lista de IDs de los agentes.

admins: ponlo en false para no incluir a los administradores. Por defecto: true.

get-user-from-conversation

Devuelve el ID y el correo del usuario de una conversación, o del último agente que respondió.

conversation_id Requerido: el ID de la conversación.
agent: true para obtener el último agente que respondió. Por defecto: false.

agents-online

Indica si hay al menos un agente o administrador conectado. Devuelve true o false.

search-users

Devuelve los usuarios que coinciden con la búsqueda (también busca en los datos adicionales).

search Requerido: el texto a buscar.

Si no hay resultados, devuelve {"success": true, "response": []}.

add-user

Crea un usuario nuevo y devuelve su ID.

first_name: nombre. Si no lo envías, se genera un nombre de visitante.
last_name: apellido.
email: correo.
profile_image: URL de la foto de perfil.
password: contraseña.
user_type: tipo de usuario. Valores: visitor, lead, user, agent, admin. Si no lo envías, será user cuando haya correo y visitor cuando no.
department: ID del departamento (para agentes).
extra: datos adicionales, con la forma {"identificador": ["valor", "Nombre visible"]}. Identificadores incluidos: phone, city, language, country, birthday, company, facebook, linkedin, website, ip, country_code, browser, currency, location, os, timezone, current_url. También puedes crear los tuyos.

{
    "token": "TU-TOKEN",
    "function": "add-user",
    "first_name": "Ana",
    "last_name": "Gómez",
    "email": "ana@example.com",
    "extra": {
        "phone": ["+573001234567", "Phone"],
        "city": ["Medellín", "City"]
    }
}

Otras respuestas posibles: duplicate-email, duplicate-phone, invalid-user-type.

update-user

Actualiza los datos de un usuario existente.

user_id Requerido: el ID del usuario.
first_name, last_name, email, profile_image, password, user_type, department: los datos a cambiar.
settings_extra: datos adicionales, con la forma {"identificador": ["valor", "Nombre visible"]}.

Otras respuestas posibles: duplicate-email, invalid-user-type.

delete-user

Elimina un usuario junto con sus conversaciones y mensajes.

user_id Requerido: el ID del usuario.

delete-users

Elimina varios usuarios junto con sus conversaciones y mensajes.

user_ids Requerido: lista de IDs, por ejemplo [123, 124].

delete-leads

Elimina todos los leads de la cuenta, con sus conversaciones y mensajes.

Esta acción no se puede deshacer.

merge-users

Fusiona dos usuarios en uno solo.

user_id_1 Requerido: el ID del primer usuario.
user_id_2 Requerido: el ID del segundo usuario.

update-user-to-lead

Cambia el tipo de un usuario a lead.

user_id Requerido: el ID del usuario.

is-online

Indica si un usuario está conectado. Devuelve true o false.

user_id Requerido: el ID del usuario.

current-url

Devuelve la última página visitada por un usuario, o la guarda.

user_id: el ID del usuario.
url: si la envías, se guarda como página actual del usuario y la función devuelve true en lugar de una URL.

Si no hay ninguna URL guardada, devuelve false.

count-users

Devuelve el número de usuarios agrupados por tipo.

{
    "success": true,
    "response": {
        "all": "1250",
        "lead": "800",
        "user": "400",
        "visitor": "50",
        "agent": "5",
        "online": "12"
    }
}

get-avatar

Genera una imagen de perfil con las iniciales del nombre, la guarda y devuelve su URL.

first_name Requerido: nombre.
last_name: apellido.

get-bot-id

Devuelve el ID del usuario bot de tu cuenta. Úsalo en send-message cuando quieras que un mensaje aparezca como enviado por el bot.

update-bot

Actualiza el nombre y la foto del bot. Si el bot no existe, lo crea.

name: nombre del bot.
profile_image: URL de la foto del bot.

Inicia sesión como un usuario y devuelve sus datos y la cadena de sesión cifrada. Se usa, por ejemplo, para que tu servidor genere la sesión y luego la página la guarde con SBF.loginCookie() (ver API de JavaScript ).

Puedes iniciar sesión de dos formas:

email y password: correo y contraseña del usuario.
user_id y user_token: ID del usuario y su token de usuario (lo devuelve get-user).

En la Web API el parámetro token es tu token de API. Para el token del usuario usa siempre user_token.

{
    "success": true,
    "response": [
        {
            "id": "913",
            "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
            "first_name": "Juan",
            "last_name": "Pérez",
            "email": "juan@example.com",
            "user_type": "user",
            "token": "9b25351047ee758aa97ee4868d130cc1ceb8decf"
        },
        "YXNkWGNSeTdtRTdDYVkxVG8wckN4YWF6V2s0Tk1mczBSVHdQbHBpOWdmejVUTTdOUUxEUENhdUVoYmROWn..."
    ]
}

Si los datos no son correctos, devuelve false.

csv-users

Exporta los usuarios a un archivo CSV y devuelve la URL del archivo.

users_id: lista de IDs para exportar solo esos usuarios. Por defecto: todos.

💬 Conversaciones

Funciones para gestionar conversaciones y mensajes.

get-conversation

Devuelve una conversación con todos sus mensajes.

conversation_id Requerido: el ID de la conversación.
user_id: el ID del usuario de la conversación.

{
    "success": true,
    "response": {
        "messages": [
            {
                "id": "2044",
                "user_id": "802",
                "message": "¡Hola!",
                "creation_time": "2026-05-04 10:06:30",
                "attachments": "",
                "status_code": "0",
                "payload": "",
                "conversation_id": "946",
                "first_name": "Juan",
                "last_name": "Pérez",
                "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
                "user_type": "lead"
            },
            {
                "id": "2045",
                "user_id": "377",
                "message": "Hola, ¿en qué te puedo ayudar?",
                "creation_time": "2026-05-04 10:06:33",
                "attachments": "",
                "status_code": "0",
                "payload": "",
                "conversation_id": "946",
                "first_name": "Laura",
                "last_name": "Ruiz",
                "profile_image": "https://tu-sitio.com/laura.jpg",
                "user_type": "agent"
            }
        ],
        "details": {
            "user_id": "802",
            "first_name": "Juan",
            "last_name": "Pérez",
            "profile_image": "https://chatbot.zampisoft.com/script/media/user.svg",
            "user_type": "lead",
            "id": "946",
            "title": "",
            "creation_time": "2026-05-04 10:06:30",
            "status_code": "3",
            "department": null,
            "agent_id": null,
            "source": "",
            "tags": ""
        }
    }
}

get-conversations

Devuelve las conversaciones de la cuenta. Cada una incluye su último mensaje.

pagination: página de resultados. 0 devuelve las primeras 100, 1 las siguientes 100, etc.
status_code: estado de las conversaciones (ver tabla de estados). Por defecto: las activas.
department: ID del departamento.
source: canal de origen (ver códigos de canal).
tag: etiqueta.
agent_id: ID del agente asignado.

get-new-conversations

Devuelve las conversaciones creadas, o con mensajes nuevos, después de una fecha o de un ID de conversación.

datetime Requerido: un ID de conversación o una fecha (AAAA-MM-DD HH:MM:SS, en UTC).
department, source, tag, agent_id: los mismos filtros que en get-conversations.

Si no hay conversaciones, devuelve {"success": true, "response": []}.

get-user-conversations

Devuelve las conversaciones de un usuario.

user_id Requerido: el ID del usuario.
exclude_id: ID de una conversación a excluir.
agent: ponlo en true si el usuario es un agente o administrador.

get-new-user-conversations

Devuelve las conversaciones de un usuario actualizadas después de una fecha o de un ID de conversación.

user_id Requerido: el ID del usuario.
datetime Requerido: un ID de conversación o una fecha (AAAA-MM-DD HH:MM:SS, en UTC).

search-conversations

Busca en todas las conversaciones (mensajes, nombres de adjuntos, correo y nombre del usuario, etiquetas, título y más).

search Requerido: el texto a buscar.

search-user-conversations

Busca dentro de las conversaciones de un usuario.

search Requerido: el texto a buscar.
user_id Requerido: el ID del usuario.

new-conversation

Crea una conversación nueva y la devuelve con el mismo formato que get-conversation.

user_id Requerido: el ID del usuario de la conversación.
status_code: estado inicial (ver tabla de estados). Por defecto: 2 (esperando respuesta del agente).
title: título de la conversación.
department: ID del departamento.
agent_id: ID del agente asignado.
source: canal de origen (ver códigos de canal).
tags: etiquetas, como lista o texto separado por comas.
extra, extra_2, extra_3: datos internos del canal. No los uses salvo que sepas lo que hacen.

Si tienes activado Ajustes > Chat > Permitir solo una conversación, la función devuelve la conversación abierta que ya tenga el usuario en lugar de crear otra.

Otras respuestas posibles: user-not-found.

update-conversation-status

Cambia el estado de una conversación.

conversation_id Requerido: el ID de la conversación.
status_code Requerido: el nuevo estado (ver tabla de estados).

update-conversation-department

Cambia el departamento de una conversación.

conversation_id Requerido: el ID de la conversación.
department Requerido: ID del departamento. Envía false para quitarlo.
message: mensaje para avisar a los agentes del nuevo departamento.

update-conversation-agent

Asigna una conversación a un agente.

conversation_id Requerido: el ID de la conversación.
agent_id Requerido: ID del agente. Envía false para quitar la asignación.
message: mensaje para avisar al agente.

update-tags

Cambia las etiquetas de una conversación.

conversation_id Requerido: el ID de la conversación.
tags Requerido: lista de etiquetas.
add: true para añadir las etiquetas a las que ya tiene en lugar de reemplazarlas. Por defecto: false.

set-rating

Guarda la valoración de una conversación.

conversation_id Requerido: el ID de la conversación.
user_id Requerido: el ID del usuario que valora.
rating Requerido: 1 para una valoración positiva, 0 para una negativa.
message: comentario del usuario.
agent_id: ID del agente valorado.

get-rating

Devuelve las valoraciones de un agente como [positivas, negativas]. Por ejemplo, [4, 2] son 4 valoraciones positivas y 2 negativas.

user_id Requerido: el ID del agente.

get-new-messages

Devuelve los mensajes de una conversación creados después de una fecha o de un ID de mensaje.

user_id Requerido: el ID del usuario.
conversation_id Requerido: el ID de la conversación.
datetime Requerido: un ID de mensaje o una fecha (AAAA-MM-DD HH:MM:SS, en UTC).
last_id: ID del último mensaje que ya tienes.

get-last-message

Devuelve el último mensaje de una conversación.

conversation_id Requerido: el ID de la conversación.
exclude_message: excluye los mensajes con este texto.
user_id: tiene en cuenta solo los mensajes de este usuario.

send-message

Añade un mensaje a una conversación existente.

user_id Requerido: el ID de quien envía el mensaje. Para enviarlo como el bot, obtén su ID con get-bot-id.
conversation_id Requerido: el ID de la conversación.
message: el texto del mensaje.
attachments: adjuntos (ver formato arriba). Por defecto: [].
conversation_status_code: nuevo estado de la conversación (ver tabla de estados). Envía skip para no cambiarlo.
payload: datos adicionales del mensaje, como objeto JSON.
queue: ponlo en true si usas la cola (Ajustes > Misceláneas > Cola). Por defecto: false.
recipient_id: el ID del usuario que recibe el mensaje. Sirve para aplicar su idioma.

{
    "success": true,
    "response": {
        "id": 123456,
        "queue": false,
        "human_takeover_active": false,
        "notifications": ["email"],
        "message": "Texto del mensaje"
    }
}

id es el ID del mensaje creado y notifications indica las notificaciones que se enviaron.

Este mensaje solo se guarda en ZampiBot. Si la conversación es de WhatsApp, Messenger, Telegram u otro canal y quieres que el mensaje llegue al cliente en ese canal, usa también la función de envío del canal (ver más abajo).

update-message

Modifica un mensaje existente.

message_id Requerido: el ID del mensaje.
message: el nuevo texto.
attachments: adjuntos (ver formato arriba).
payload: datos adicionales del mensaje, como objeto JSON.

delete-message

Elimina un mensaje.

message_id Requerido: el ID del mensaje.

delete-attachments

Elimina los archivos adjuntos de una conversación o de un mensaje.

conversation_id: el ID de la conversación. Por defecto: false.
message_id: el ID del mensaje. Por defecto: false.

update-messages-status

Marca varios mensajes como leídos.

message_ids Requerido: lista de IDs de mensajes, por ejemplo [1, 212].
user_id: el ID del usuario.

get-agents-in-conversation

Devuelve los agentes que han escrito al menos un mensaje en la conversación.

conversation_id Requerido: el ID de la conversación (también acepta una lista de IDs).

get-last-agent-in-conversation

Devuelve el último agente que respondió en una conversación, o false si ningún agente ha respondido.

conversation_id Requerido: el ID de la conversación.

transcript

Exporta una conversación a un archivo y devuelve su URL.

conversation_id Requerido: el ID de la conversación.
type: csv o txt. Si no lo envías, se usa el tipo elegido en Ajustes > Administración > Transcripción > Tipo.

Si la conversación no existe, devuelve false.

direct-message

Envía un mensaje directo a varios usuarios: se añade a su conversación (o se crea una si no tienen).

user_ids Requerido: lista de IDs (por ejemplo [45, 89, 65]), texto con IDs separados por comas, all para todos los usuarios, o el nombre de un canal (whatsapp, messenger, instagram, telegram, viber, line, wechat, zalo) para todos los usuarios de ese canal.
message Requerido: el mensaje.

messaging-platforms-send-message

Procesa un mensaje del usuario igual que cuando llega desde un canal externo: ejecuta el chatbot y las automatizaciones y envía la respuesta al canal de la conversación.

conversation_id Requerido: el ID de la conversación.
message Requerido: el mensaje del usuario.
user Requerido: el ID del usuario, o un objeto con sus datos (como mínimo id).
source Requerido: el código del canal (por ejemplo "wa"), o un objeto con la clave source.
attachments: adjuntos (ver formato arriba).

execute-bot-message

Envía a una conversación uno de los mensajes automáticos del bot y devuelve su contenido.

name Requerido: el mensaje a enviar. Valores: offline (mensaje fuera de horario) y follow_up (mensaje de seguimiento).
conversation_id Requerido: el ID de la conversación.
last_user_message: el último mensaje del usuario. Por defecto: false.
check: ponlo en false para enviarlo aunque ya se haya enviado hace poco. Por defecto: true.

close-message

Envía a una conversación el mensaje de cierre configurado.

conversation_id Requerido: el ID de la conversación.

human-takeover

Pasa una conversación del chatbot a un agente humano (la misma acción que Derivar a humano).

conversation_id Requerido: el ID de la conversación.
auto_messages: true para enviar también los mensajes automáticos (fuera de horario y seguimiento) si están activos. Por defecto: false.

count-conversations

Devuelve el número de conversaciones.

status_code: cuenta solo las de ese estado.

check-conversations-assignment

Comprueba cuáles de una lista de conversaciones están asignadas a un agente o departamento.

conversation_ids Requerido: lista de IDs, por ejemplo [45, 565, 68].
agent_id: el ID del agente. Por defecto: false.
department: el ID del departamento. Por defecto: false.

get-notes

Devuelve las notas internas de una conversación.

conversation_id Requerido: el ID de la conversación.

{
    "success": true,
    "response": [
        {
            "id": 1,
            "user_id": "1",
            "name": "Laura Ruiz",
            "message": "Cliente VIP: dar prioridad.",
            "date": "2026-05-04 10:10:00"
        }
    ]
}

add-note

Añade una nota interna a una conversación y devuelve el ID de la nota.

conversation_id Requerido: el ID de la conversación.
user_id Requerido: el ID del agente o administrador que escribe la nota.
name Requerido: el nombre que aparece como autor de la nota.
message Requerido: el texto de la nota.

update-note

Modifica una nota interna.

conversation_id Requerido: el ID de la conversación.
user_id Requerido: el ID del agente o administrador.
note_id Requerido: el ID de la nota.
message Requerido: el nuevo texto.

delete-note

Elimina una nota interna.

conversation_id Requerido: el ID de la conversación.
note_id Requerido: el ID de la nota.

⚙️ Ajustes, traducciones y respuestas guardadas

get-setting

Devuelve el valor de un ajuste.

setting Requerido: el identificador interno del ajuste. Puedes ver todos los identificadores con get-settings.

get-multi-setting

Devuelve un valor que está dentro de un ajuste compuesto (una tarjeta con varias opciones).

id Requerido: el identificador del ajuste principal.
sub_id Requerido: el identificador de la opción dentro de ese ajuste.
default: el valor a devolver si no existe. Por defecto: false.

get-settings

Devuelve todos los ajustes de la cuenta.

save-settings

Guarda los ajustes de la cuenta.

settings Requerido: los ajustes, con la misma forma que devuelve get-settings.
external_settings: ajustes que se guardan aparte.
external_settings_translations: traducciones de esos ajustes.

Envía siempre el conjunto completo de ajustes que obtuviste con get-settings y modifica solo lo que necesitas. Un envío incompleto puede dejar ajustes vacíos.

get-external-setting

Devuelve un ajuste que se guarda aparte del resto.

setting Requerido: el nombre del ajuste.

save-external-setting

Guarda un ajuste aparte del resto.

name Requerido: el nombre del ajuste.
value Requerido: el valor.

export-settings

Exporta todos los ajustes a un archivo JSON y devuelve la URL del archivo.

import-settings

Importa los ajustes desde un archivo JSON generado con export-settings.

file_url Requerido: la URL del archivo JSON.

get-departments

Devuelve los departamentos de la cuenta.

{
    "success": true,
    "response": {
        "1": {
            "name": "Ventas",
            "color": "red",
            "image": "https://tu-sitio.com/ventas.png"
        },
        "2": {
            "name": "Soporte",
            "color": "blue",
            "image": ""
        }
    }
}

saved-replies

Devuelve todas las respuestas guardadas.

add-saved-reply

Crea una respuesta guardada.

name Requerido: el nombre (atajo) de la respuesta.
text Requerido: el texto de la respuesta.

get-translation

Devuelve las traducciones de un idioma.

language_code Requerido: código del idioma de dos letras, por ejemplo es.

get-translations

Devuelve todas las traducciones (del chat y del panel) de todos los idiomas.

save-translations

Guarda las traducciones de tu cuenta.

translations Requerido: las traducciones completas, con la misma forma que devuelve get-translations.

Envía siempre el conjunto completo que obtuviste con get-translations. Si envías datos incompletos o mal formados puedes perder traducciones.

translate-string

Traduce un texto del chat a un idioma usando las traducciones de ZampiBot.

string Requerido: el texto a traducir.
language_code Requerido: código del idioma de dos letras.

📄 Artículos

get-articles

Devuelve los artículos de la base de conocimiento.

id: ID de un artículo, o lista de IDs, para obtener solo esos.
count: número máximo de artículos.
full: true para incluir el contenido completo. Por defecto solo se incluye un extracto.
categories: ID de una categoría (o lista de IDs) para obtener solo los artículos de esas categorías.
language: código de idioma. Si no hay artículos en ese idioma, se devuelven los del idioma principal. Usa all para obtener todas las traducciones.

{
    "success": true,
    "response": [
        {
            "id": "1",
            "title": "¿Cómo cambio mi contraseña?",
            "content": "Entra en tu perfil y pulsa...",
            "link": "",
            "category": "cuenta",
            "parent_category": "",
            "language": "",
            "parent_id": null,
            "slug": "como-cambio-mi-contrasena"
        }
    ]
}

save-article

Crea, actualiza o elimina un artículo.

article Requerido: objeto con los datos del artículo: id (para actualizar uno existente), title, content, link, category, parent_category, language y parent_id (para traducciones). Para eliminarlo, envía su id y "delete": true.

search-articles

Devuelve los artículos que coinciden con la búsqueda (busca en el título y el contenido).

search Requerido: el texto a buscar.
language: código de idioma. Usa all para buscar en todas las traducciones.

get-articles-categories

Devuelve las categorías de artículos.

category_type: parent para devolver solo las categorías principales, normal para devolver solo las demás. Por defecto: todas.

{
    "success": true,
    "response": [
        {
            "id": "cuenta",
            "title": "Mi cuenta",
            "description": "Preguntas sobre tu cuenta.",
            "image": "https://tu-sitio.com/cuenta.png",
            "parent": true,
            "languages": {}
        }
    ]
}

save-articles-categories

Guarda la lista completa de categorías de artículos.

categories Requerido: la lista de categorías, con la misma forma que devuelve get-articles-categories.

article-ratings

Devuelve las valoraciones de un artículo o añade una nueva.

article_id Requerido: el ID del artículo.
rating: 1 para una valoración positiva o 0 para una negativa. Si lo envías, se guarda la valoración y la función devuelve true; si no, devuelve las valoraciones existentes.

🧠 Inteligencia artificial

Estas funciones usan la inteligencia artificial de tu cuenta (Ajustes > Inteligencia artificial). Las que generan respuestas con OpenAI consumen créditos de IA; puedes ver tu saldo y ampliarlo en Membresía en el portal.

open-ai-message

Envía un mensaje a la IA y devuelve la respuesta. Si indicas una conversación, la respuesta se añade a ella como mensaje del bot.

message Requerido: el texto del mensaje.
conversation_id: el ID de la conversación. Por defecto: false.
model: modelo de OpenAI. Por defecto, el elegido en Ajustes > Inteligencia artificial > OpenAI > Modelo.
max_tokens: longitud máxima de la respuesta. Por defecto, la configurada en Ajustes > Inteligencia artificial > OpenAI > Máximo de tokens (en pantalla: «Fichas máximas»), o un valor automático.
audio: URL de un audio para transcribirlo y responder a su contenido. Por defecto: false.
attachments: adjuntos (ver formato arriba).

{
    "success": true,
    "response": [true, "¡Hola! ¿En qué te puedo ayudar?"]
}

El primer valor es true si todo fue bien o false si hubo un error; el segundo es la respuesta de la IA o el mensaje de error. Si el chatbot está desactivado para el canal de la conversación, el primer valor es true y el segundo false.

open-ai-curl

Llama directamente a la API de OpenAI y devuelve su respuesta.

url_part Requerido: la parte final de la dirección de OpenAI. Por ejemplo, para https://api.openai.com/v1/chat/completions envía chat/completions.
post_fields: los parámetros de la llamada, como objeto JSON.
type: método HTTP: POST (por defecto), GET o UPLOAD.

google-translate

Traduce varios textos con Google Translate.

strings Requerido: lista de textos, por ejemplo ["Hello world", "How are you?"].
language_code Requerido: código del idioma de destino, de dos letras. Para chino tradicional usa zt; para chino simplificado, zh; para portugués de Brasil, pt.

google-get-token

Devuelve un token de acceso temporal (una hora) de la cuenta de Google conectada a ZampiBot.

Este token da acceso a los servicios de Google conectados. Trátalo con el mismo cuidado que tu token de API.

✉️ Correo, SMS y notificaciones

send-email

Envía un correo a un usuario existente usando las plantillas de Ajustes > Notificaciones.

recipient_id Requerido: el ID del usuario que recibe el correo.
message Requerido: el texto del correo.
sender_id: el ID del usuario que aparece como remitente.
attachments: adjuntos (ver formato arriba). Por defecto: [].

Otras respuestas posibles: missing-user-id-or-message, security-error, user-email-not-found, user-or-sender-not-found.

send-custom-email

Envía un correo con asunto y texto libres a un usuario de tu cuenta. El remitente es el configurado en Ajustes > Notificaciones.

to Requerido: el correo del destinatario. Debe coincidir con el correo del usuario indicado en recipient_id.
recipient_id Requerido: el ID del usuario que recibe el correo.
subject Requerido: el asunto.
message Requerido: el texto del correo.
use_template: ponlo en false para enviar el texto sin la plantilla de correo. Por defecto: true.

Si to no coincide con el correo de ese usuario, devuelve el error recipient-not-in-tenant.

send-sms

Envía un mensaje de texto (SMS) con la cuenta de Twilio configurada en Ajustes > Notificaciones > Notificaciones de mensajes de texto.

message Requerido: el texto.
to Requerido: el número de teléfono, con el código de país.
template: ponlo en false para enviar solo el texto, sin la plantilla de mensaje. Por defecto: se usa la plantilla.
conversation_id: el ID de la conversación, si el mensaje usa el campo {conversation_url_parameter}.
attachments: adjuntos (ver formato arriba).
recipient_id: el ID del usuario que recibe el mensaje. Hace falta para traducir el mensaje a su idioma.

push-notification

Envía una notificación push a uno o varios agentes. Las notificaciones push deben estar activas en Ajustes > Notificaciones > Notificaciones push > Activo para agentes, y cada agente debe haberse suscrito en su navegador.

title Requerido: el título.
message Requerido: el texto.
interests Requerido: a quién se envía. Puede ser el ID de un agente, una lista de IDs (por ejemplo [1, 2, 3]), agents para todos los agentes y administradores, o department-ID (cambia ID por el ID del departamento) para los agentes de ese departamento y los que no tienen departamento.
conversation_id: la conversación que se abre al pulsar la notificación.
icon: URL del icono de la notificación.

Devuelve false si las notificaciones push no están activas.

Suscribe un correo al servicio de boletín configurado en Ajustes > Misceláneas > Boletín informativo (la opción Activo debe estar marcada).

email Requerido: el correo del suscriptor.
first_name: nombre.
last_name: apellido.

🤖 Automatizaciones e informes

automations-get

Devuelve todas las automatizaciones y sus traducciones.

automations-save

Guarda todas las automatizaciones.

automations Requerido: la lista completa de automatizaciones, con la misma forma que devuelve automations-get.
translations: las traducciones de las automatizaciones.

automations-validate

Comprueba si una automatización se puede ejecutar. Devuelve las condiciones que solo se pueden comprobar en el navegador o más tarde; si no devuelve ninguna, la automatización es válida. Devuelve false si no es válida.

automation Requerido: la automatización.

automations-run

Ejecuta una automatización guardada.

automation Requerido: objeto con el ID de la automatización, por ejemplo {"id": "123"}.
validate: true para comprobar las condiciones antes de ejecutarla. Por defecto: false.

automations-run-all

Comprueba todas las automatizaciones, ejecuta las válidas y devuelve las que dependen del navegador del visitante (ventanas emergentes, diseño y condiciones que solo se pueden comprobar ahí).

automations-is-sent

Indica si una automatización ya se envió a un usuario.

user_id Requerido: el ID del usuario.
automation_id Requerido: el ID de la automatización.
automation Requerido: envía también este parámetro (puede ser {"id": "123"}); la API lo exige aunque el valor que se usa es automation_id.
repeat_id: solo para automatizaciones que se pueden enviar varias veces al mismo usuario.

reports

Devuelve los datos de un informe.

name Requerido: el informe, o una categoría para obtener todos los de esa categoría:
- conversations: new-conversations, missed-conversations, conversations-time.
- messages: direct-messages, direct-emails, direct-sms, follow-up, message-automations, email-automations.
- users: new-visitors, new-leads, new-users, registrations, countries, languages, browsers, os.
- agents: agents-ratings, agents-response-time, agents-conversations, agents-conversations-time.
- articles: articles-searches, articles-views, articles-views-single, articles-ratings.
- chatbot: chatbot-conversations, chatbot-human-takeovers, chatbot-human-takeovers-percentage, chatbot-no-human-takeovers, chatbot-no-human-takeovers-percentage.
date_start: fecha de inicio, en formato dd/mm/aaaa o aaaa-mm-dd.
date_end: fecha de fin, en el mismo formato.
timezone: zona horaria, por ejemplo America/Bogota.

reports-update

Suma un registro a un informe.

name Requerido: el nombre del informe (ver reports).
value: el valor. Por defecto: false.
external_id: un ID externo. Por defecto: false.
extra: un valor adicional. Por defecto: false.

clean-data

Hace limpieza de datos antiguos: elimina los visitantes creados hace más de 24 horas y borra las conversaciones que llevan en la papelera más de 30 días. Si tienes activado Ajustes > Administración > Archivar conversaciones automáticamente, además archiva las conversaciones (que no sean tickets) cuyo último mensaje tiene más de 24 horas.

Esta acción no se puede deshacer.

🧩 Otras funciones

chat-css

Devuelve el CSS de los colores del chat.

color_1, color_2, color_3: colores en formato RGB o HEX. Por defecto, los colores guardados en tus ajustes.

text-formatting-to-html

Convierte el formato de texto de los mensajes (negrita, cursiva, enlaces…) a HTML.

message Requerido: el texto.

clear-text-formatting

Quita el formato de texto de un mensaje.

message Requerido: el texto.

is-allowed-extension

Indica si se permite subir archivos con esa extensión. Devuelve true o false.

extension Requerido: la extensión, por ejemplo jpg.

pusher-trigger

Envía un evento en tiempo real a un canal.

channel Requerido: el nombre del canal.
event Requerido: el nombre del evento.
data: los datos del evento, como objeto JSON.

📱 WhatsApp

Requieren la aplicación WhatsApp activa y configurada en tu cuenta.

whatsapp-send-message

Envía un mensaje a un número de WhatsApp.

to Requerido: el número del destinatario, con código de país. Por ejemplo +573001234567.
message: el texto.
attachments: adjuntos (ver formato arriba). Por defecto: [].
phone_id: el identificador del número de WhatsApp desde el que se envía. Solo hace falta si conectaste varios números; lo encuentras en Ajustes > WhatsApp > Números de la API de la nube > Identificación del número de teléfono. Por defecto: false.

WhatsApp solo permite mensajes libres durante las 24 horas siguientes al último mensaje del cliente. Fuera de esa ventana, usa whatsapp-send-template.

whatsapp-send-template

Envía una plantilla de WhatsApp a un número.

to Requerido: el número del destinatario, con código de país.
template_name: el nombre de la plantilla. Por defecto, el de Ajustes > WhatsApp > Plantilla de respaldo > Nombre de la plantilla.
template_languages: los códigos de idioma disponibles para la plantilla, separados por comas, por ejemplo es,en_US. Por defecto, los de Ajustes > WhatsApp > Plantilla de respaldo > Idiomas de plantilla.
language: el idioma con el que se elige la versión de la plantilla. Por defecto: vacío.
phone_id: el identificador del número de WhatsApp desde el que se envía. Por defecto: false.
parameters: lista con las variables de la plantilla, por ejemplo ["A", "B,C", "D,E"]. El primer elemento son las variables del encabezado, el segundo las del cuerpo y el tercero las de los botones; dentro de cada elemento, las variables van separadas por comas. Por defecto, las de Ajustes > WhatsApp > Plantilla de respaldo.
conversation_url_parameter: valor del campo {conversation_url_parameter}, si la plantilla lo usa.
user_name: valor del campo {recipient_name}, si la plantilla lo usa.
user_email: valor del campo {recipient_email}, si la plantilla lo usa.
recipient_id: el ID del usuario de ZampiBot que recibe la plantilla. Por defecto: false.

whatsapp-get-templates

Devuelve las plantillas de tu cuenta de WhatsApp Business.

business_account_id: el ID de la cuenta comercial, si tienes varias.
template_name: devuelve solo la plantilla con este nombre.
template_language: devuelve solo la plantilla en este idioma.

💬 Messenger e Instagram

Requieren la aplicación Messenger activa y configurada.

messenger-send-message

Envía un mensaje a un usuario de Facebook Messenger o de Instagram.

psid Requerido: el identificador del usuario en Facebook o Instagram. Existe cuando el usuario te ha escrito antes; lo encuentras en sus datos (get-user con extra en true).
facebook_page_id Requerido: el ID de la página de Facebook. Es el valor extra de la conversación (get-conversation).
message: el texto.
attachments: adjuntos (ver formato arriba). Por defecto: [].
message_id: el ID del mensaje de ZampiBot vinculado a este envío. Si lo envías, debe ser un mensaje de una conversación de Messenger o Instagram.
reply_to: el ID del mensaje al que se responde.

✈️ Telegram

Requiere la aplicación Telegram activa y configurada.

telegram-send-message

Envía un mensaje a Telegram.

chat_id Requerido: el identificador del chat de Telegram. Existe cuando el usuario te ha escrito antes; es el valor extra de la conversación (get-conversation).
message: el texto.
attachments: adjuntos (ver formato arriba). Por defecto: [].
conversation_id: el ID de la conversación. Solo hace falta si conectaste varios bots de Telegram. Por defecto: false.
reply_to: el ID del mensaje al que se responde.

🟣 Viber

Requiere la aplicación Viber activa y configurada.

viber-send-message

Envía un mensaje a Viber.

viber_id Requerido: el identificador del usuario en Viber. Existe cuando el usuario te ha escrito antes; lo encuentras en sus datos (get-user con extra en true).
message: el texto.
attachments: adjuntos (ver formato arriba). Por defecto: [].

🟢 LINE

Requiere la aplicación LINE activa y configurada.

line-send-message

Envía un mensaje a LINE.

line_id Requerido: el identificador del usuario en LINE. Existe cuando el usuario te ha escrito antes; lo encuentras en sus datos (get-user con extra en true).
message: el texto.
attachments: adjuntos (ver formato arriba). Por defecto: [].
conversation_id: el ID de la conversación.

🔵 Zalo

Requiere la aplicación Zalo activa y configurada.

zalo-send-message

Envía un mensaje a Zalo.

zalo_id Requerido: el identificador del usuario en Zalo. Existe cuando el usuario te ha escrito antes; lo encuentras en sus datos (get-user con extra en true).
message: el texto.
attachments: adjuntos (ver formato arriba). Por defecto: [].

🪝 Webhooks

Los webhooks son avisos automáticos que ZampiBot envía a una dirección tuya cuando ocurre algo (un mensaje nuevo, un usuario que se registra, etc.). Sirven para conectar ZampiBot con tus sistemas sin tener que consultar la API cada cierto tiempo.

Cómo activarlos

En el panel, ve a Ajustes > Misceláneas > Webhooks.
En URL, escribe la dirección de tu servidor que recibirá los avisos. Debe aceptar peticiones POST con un cuerpo JSON.
En Llave secreta, escribe una clave que solo tú conozcas. Se envía en cada aviso para que puedas comprobar que viene de ZampiBot.
En Webhooks activos, escribe los nombres de los webhooks que quieres recibir separados por comas (por ejemplo message-sent,new-conversation-created). Déjalo vacío para recibirlos todos.
Marca Activo y guarda.

Qué recibes

Cada aviso es un JSON con esta forma:

{
    "function": "message-sent",
    "key": "TU-LLAVE-SECRETA",
    "sender-url": "https://tu-sitio.com/contacto",
    "data": {}
}

function: el nombre del webhook.
key: tu llave secreta. Compruébala antes de procesar el aviso.
sender-url: la página desde la que se originó el evento, si se conoce.
data: los datos del evento (ver cada webhook).

Ejemplo en PHP para leerlo:

$webhook = json_decode(file_get_contents('php://input'), true);
if ($webhook['key'] !== 'TU-LLAVE-SECRETA') {
    http_response_code(403);
    exit;
}
// $webhook['function'] y $webhook['data'] contienen el evento

message-sent

Se envía cuando un usuario, un agente o el bot envía un mensaje, en cualquier canal.

{
    "function": "message-sent",
    "key": "xxxxxxxx",
    "sender-url": "https://example.com",
    "data": {
        "user_id": "947",
        "conversation_user_id": "947",
        "conversation_id": "1057",
        "conversation_status_code": "2",
        "conversation_source": "wa",
        "message_id": "2574",
        "message": "¡Hola! ¿Cómo estás?",
        "attachments": [["imagen.png", "https://example.com/imagen.png"]]
    }
}

email-sent

Se envía cuando se manda un correo de notificación a un usuario o a un agente.

{
    "function": "email-sent",
    "key": "xxxxxxxx",
    "sender-url": "https://example.com",
    "data": {
        "recipient_id": "957",
        "message": "Hola, ¿en qué te puedo ayudar?",
        "attachments": []
    }
}

sms-sent

Se envía cuando se manda un mensaje de texto (SMS). data incluye el ID del destinatario (recipent_id), el texto y la respuesta de Twilio.

new-messages

Se envía cuando el chat web o el panel reciben mensajes nuevos en la conversación abierta. Para recibir los mensajes que llegan de WhatsApp, Instagram u otros canales, usa message-sent.

message-deleted

Se envía cuando se elimina un mensaje. data es el ID del mensaje eliminado.

rich-message

Se envía cuando el usuario completa un mensaje enriquecido que pide datos (por ejemplo el formulario de seguimiento por correo, el de registro o los botones). data incluye el resultado, los datos enviados y el ID del mensaje enriquecido.

new-conversation

Se envía cuando el chat web de un usuario recibe una conversación nueva.

new-conversation-created

Se envía cuando se crea una conversación nueva. data contiene la conversación completa (mensajes y detalles), con el mismo formato que get-conversation.

conversation-status-updated

Se envía cuando cambia el estado de una conversación.

{
    "function": "conversation-status-updated",
    "key": "xxxxxxxx",
    "sender-url": "https://example.com",
    "data": {
        "conversation_id": "1057",
        "status_code": "0"
    }
}

Se envía cuando un usuario inicia sesión correctamente desde el formulario de inicio de sesión del chat.

registration

Se envía cuando un usuario se registra correctamente desde el formulario de registro del chat, o actualiza su registro desde un mensaje enriquecido de registro. data incluye user (datos principales) y extra (datos adicionales).

user-deleted

Se envía cuando se elimina un usuario. data es el ID del usuario eliminado.

new-email-address

Se envía cuando un usuario deja su correo en el mensaje de seguimiento, en el de suscripción o en un mensaje enriquecido de correo.

{
    "function": "new-email-address",
    "key": "xxxxxxxx",
    "sender-url": "https://example.com",
    "data": {
        "name": "Juan Pérez",
        "email": "juan@example.com"
    }
}

Los webhooks login, registration, user-deleted, new-messages, new-conversation, message-deleted, rich-message y new-email-address se originan en el navegador de quien usa el chat; si esa persona cierra la página justo en ese momento, el aviso puede no llegar.