Agenda
Referencia de las seis rutas de la Agenda en la API de ChatISP: consulte los tipos de compromiso, liste y consulte la agenda del equipo, agende visitas, devoluciones de contacto y reuniones desde otro sistema y registre la conclusión o la cancelación.
Visión general
La Agenda de ChatISP guarda los compromisos del equipo: visita técnica, devolución de contacto, instalación, reunión. Cada compromiso puede tener responsable, equipo, cliente y atención vinculada, y dispara automáticamente las alertas al responsable y los recordatorios al cliente por WhatsApp. Por la API, su sistema agenda y da seguimiento a esos compromisos con las mismas reglas de la pantalla.
Casos típicos de integración:
- ERP y órdenes de servicio: la OS de instalación agendada en el ERP se convierte en compromiso en la agenda del técnico, con recordatorio automático al cliente la víspera.
- Portal del suscriptor: el cliente elige el horario de la visita en el portal y el compromiso nace con la confirmación ya enviada por WhatsApp.
- Aplicación de campo: el técnico ve la agenda del día y marca la visita como concluida, con el resultado.
- Planificación de rutas: un sistema externo lee la agenda de la semana por equipo para planificar rutas.
Rutas
| Ruta | Método | Permiso de la clave | Qué hace |
|---|---|---|---|
agenda/tipos | GET | Consultar agenda | Tipos de compromiso y la duración predeterminada de cada uno. |
agenda/listar | GET | Consultar agenda | Compromisos de un período, con filtros. |
agenda/consultar | GET | Consultar agenda | Un compromiso. |
agenda/criar | POST | Gestionar agenda | Agenda un compromiso. |
agenda/concluir | POST | Gestionar agenda | Lo marca como concluido, con resultado. |
agenda/cancelar | POST | Gestionar agenda | Lo cancela, con motivo. |
Los permisos se marcan en la clave, en Integraciones, tarjeta API de ChatISP. Gestionar agenda no incluye la lectura: para agendar y después consultar, marque los dos. Autenticación, formato de las llamadas, paginación y errores comunes están en la Introducción.
La clave ve la agenda de toda la empresa, de todos los equipos y responsables. Las reglas del panel sobre quién ve qué valen para las personas, no para la API. Los compromisos agendados por la API quedan con origem igual a api y, en las notas de la atención vinculada, la acción aparece como realizada por API: <nombre de la clave>.
El objeto compromiso
Formato usado por todas las rutas que devuelven compromisos. Fechas en ISO 8601 con la zona horaria del servidor.
| Campo | Tipo | Descripción |
|---|---|---|
id | entero | Identificador del compromiso. |
titulo | texto | Título, hasta 160 caracteres. |
tipo | objeto o null | {"id", "nome"} del tipo; null sin tipo. |
descricao | texto | Observaciones; vacío cuando no hay. |
inicio / fim | fecha | Inicio y fin. Siempre en minutos exactos (los segundos quedan en cero). |
dia_inteiro | booleano | true en el compromiso de día completo: inicio a las 00:00 y fim a las 23:59 del mismo día. |
local | texto | Dirección o punto de encuentro. |
link | texto | Enlace de la reunión (por ejemplo, la sala de Google Meet creada para el compromiso). |
estado | texto | agendado, concluido o cancelado. |
origem | texto | manual (agendado en la Agenda), chat (agendado a partir de una atención), copiloto, ia o api. |
responsavel_id / responsavel | entero o null / texto | Persona responsable. |
departamento_id | entero o null | Equipo del compromiso. |
conversa_id | entero o null | Atención vinculada. |
cliente | objeto | {"telefone", "nome"}. Teléfono con código de país, solo dígitos; vacío cuando el compromiso no tiene cliente. |
desfecho | texto | Lo que se registró al concluir o cancelar. |
criado_em / atualizado_em | fecha | Creación y última modificación del registro. |
{
"id": 342,
"titulo": "Visita técnica: cambio de router",
"tipo": {"id": 3, "nome": "Visita técnica"},
"descricao": "Llevar router de doble banda. Portón azul, intercomunicador 2.",
"inicio": "2026-10-02T09:00:00-03:00",
"fim": "2026-10-02T10:00:00-03:00",
"dia_inteiro": false,
"local": "Rua das Palmeiras, 120, Centro",
"link": "",
"estado": "agendado",
"origem": "api",
"responsavel_id": 7,
"responsavel": "Carlos Lima",
"departamento_id": 3,
"conversa_id": 5310,
"cliente": {"telefone": "5544999990000", "nome": "Maria Souza"},
"desfecho": "",
"criado_em": "2026-10-01T14:20:03-03:00",
"atualizado_em": "2026-10-01T14:20:03-03:00"
}Estados
estado | Significado |
|---|---|
agendado | Compromiso vigente. Solo este estado dispara alertas al responsable y recordatorios al cliente. |
concluido | Realizado. Las alertas pendientes se descartan. |
cancelado | No se realizará. Las alertas pendientes se descartan y el evento reflejado en Google Calendar se elimina. |
Tipos de compromiso
/api_publica.php?r=agenda/tiposDevuelve los tipos de compromiso registrados, en el orden de la pantalla, incluidos los desactivados. Sin parámetros. El tipo define la duración predeterminada, las antelaciones de las alertas al responsable y de los recordatorios al cliente, y si el evento en Google Calendar nace con sala de Meet.
Campo de tipos[] | Descripción |
|---|---|
id | Identificador, usado en tipo_id. |
nome | Nombre del tipo. |
ativo | false cuando está desactivado. |
duracao_min | Duración predeterminada en minutos, usada para calcular el fin cuando el agendamiento no informa fim ni duracao_min. |
curl -s -G "https://atendimento.seuprovedor.com.br/api_publica.php" \ -H "Authorization: Bearer $CHATISP_CHAVE" \ --data-urlencode "r=agenda/tipos"
<?php
$url = 'https://atendimento.seuprovedor.com.br/api_publica.php?' . http_build_query([
'r' => 'agenda/tipos',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
]);
$resposta = json_decode(curl_exec($ch), true);import os, requests
resposta = requests.get(
"https://atendimento.seuprovedor.com.br/api_publica.php",
params={"r": "agenda/tipos"},
headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
timeout=30,
).json(){
"ok": true,
"tipos": [
{"id": 1, "nome": "Reunión", "ativo": true, "duracao_min": 60},
{"id": 2, "nome": "Devolución de contacto", "ativo": true, "duracao_min": 15},
{"id": 3, "nome": "Visita técnica", "ativo": true, "duracao_min": 60},
{"id": 4, "nome": "Capacitación", "ativo": true, "duracao_min": 90},
{"id": 5, "nome": "Presentación", "ativo": true, "duracao_min": 60}
]
}Los tipos y las antelaciones de cada uno los configura el proveedor en la Agenda: vea Tipos de compromiso.
Listar compromisos
/api_publica.php?r=agenda/listarCompromisos que tocan el período pedido (empiezan antes del fin del período y terminan después de su inicio), en orden de inicio. Un compromiso de las 23:00 a la 01:00 aparece tanto en el día en que empieza como en el siguiente.
| Parámetro | Tipo | Descripción |
|---|---|---|
de | fecha | Inicio del período. Predeterminado: hoy, 00:00. |
ate | fecha | Fin del período. Predeterminado: 30 días después de de, a las 23:59:59. Una fecha sin hora vale hasta las 23:59:59 del día. El período máximo es de 366 días. |
estado | texto | agendado, concluido o cancelado. Sin él, todos. |
responsavel_id | entero | Solo los de esa persona. |
departamento_id | entero | Solo los de ese equipo. |
tipo_id | entero | Solo los de ese tipo. |
conversa_id | entero | Solo los vinculados a esa atención. |
telefone | texto | Solo los de ese cliente (buscado con y sin el noveno dígito). |
pagina / limite | entero | Paginación numerada: limite de 1 a 100 (predeterminado 50). |
curl -s -G "https://atendimento.seuprovedor.com.br/api_publica.php" \ -H "Authorization: Bearer $CHATISP_CHAVE" \ --data-urlencode "r=agenda/listar" \ --data-urlencode "de=2026-10-02" \ --data-urlencode "ate=2026-10-02" \ --data-urlencode "responsavel_id=7" \ --data-urlencode "estado=agendado"
<?php
$url = 'https://atendimento.seuprovedor.com.br/api_publica.php?' . http_build_query([
'r' => 'agenda/listar',
'de' => '2026-10-02',
'ate' => '2026-10-02',
'responsavel_id' => 7,
'estado' => 'agendado',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
]);
$resposta = json_decode(curl_exec($ch), true);import os, requests
resposta = requests.get(
"https://atendimento.seuprovedor.com.br/api_publica.php",
params={"r": "agenda/listar", "de": "2026-10-02", "ate": "2026-10-02", "responsavel_id": 7, "estado": "agendado"},
headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
timeout=30,
).json(){
"ok": true,
"periodo": {"de": "2026-10-02T00:00:00-03:00", "ate": "2026-10-02T23:59:59-03:00"},
"compromissos": [
{
"id": 342,
"titulo": "Visita técnica: cambio de router",
"tipo": {"id": 3, "nome": "Visita técnica"},
"inicio": "2026-10-02T09:00:00-03:00",
"fim": "2026-10-02T10:00:00-03:00",
"estado": "agendado",
"local": "Rua das Palmeiras, 120, Centro",
"cliente": {"telefone": "5544999990000", "nome": "Maria Souza"},
"...": "demás campos del objeto compromiso"
}
],
"paginacao": {"pagina": 1, "limite": 50, "total": 1, "paginas": 1}
}El bloque periodo devuelve el período efectivamente usado, lo que ayuda a verificar los valores predeterminados cuando se omitieron de o ate.
Consultar un compromiso
/api_publica.php?r=agenda/consultar| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | entero | sí | Id del compromiso. |
curl -s -G "https://atendimento.seuprovedor.com.br/api_publica.php" \ -H "Authorization: Bearer $CHATISP_CHAVE" \ --data-urlencode "r=agenda/consultar" \ --data-urlencode "id=342"
<?php
$url = 'https://atendimento.seuprovedor.com.br/api_publica.php?' . http_build_query([
'r' => 'agenda/consultar',
'id' => 342,
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHATISP_CHAVE')],
]);
$resposta = json_decode(curl_exec($ch), true);import os, requests
resposta = requests.get(
"https://atendimento.seuprovedor.com.br/api_publica.php",
params={"r": "agenda/consultar", "id": 342},
headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
timeout=30,
).json(){
"ok": true,
"compromisso": {"id": 342, "titulo": "Visita técnica: cambio de router", "...": "objeto compromiso completo"}
}Agendar un compromiso
/api_publica.php?r=agenda/criarAgenda un compromiso en el estado agendado. Título e inicio son obligatorios; el fin puede venir explícito, por duración o por el tipo.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
titulo | texto | sí | De 1 a 160 caracteres. |
inicio | fecha | sí | Fecha y hora de inicio (ISO 8601 o AAAA-MM-DD HH:MM:SS en la zona horaria del servidor). |
fim | fecha | no | Fecha y hora de término. Debe ser posterior al inicio. |
duracao_min | entero | no | Duración en minutos, usada cuando no viene fim. |
dia_inteiro | booleano | no | Compromiso de día completo: ocupa el día de inicio de las 00:00 a las 23:59, y fim y duracao_min se ignoran. |
tipo_id | entero | no | Tipo del compromiso (agenda/tipos). Un tipo inexistente o desactivado devuelve tipo_invalido. |
descricao | texto | no | Observaciones, hasta 5.000 caracteres. |
local | texto | no | Dirección o punto de encuentro, hasta 255 caracteres. |
link | texto | no | Enlace de la reunión, que empiece con http:// o https://, hasta 500 caracteres. |
responsavel_id | entero | no | Persona responsable (activa). |
departamento_id | entero | no | Equipo del compromiso. |
conversa_id | entero | no | Atención vinculada. Completa el teléfono y el nombre del cliente cuando no se informan. |
telefone | texto | no | WhatsApp del cliente, para la confirmación y los recordatorios. Misma regla de teléfono del resto de la API. |
nome_cliente | texto | no | Nombre del cliente, hasta 190 caracteres. Va en la variable {nome} de los textos al cliente. |
confirmar_cliente | booleano | no | Envía de inmediato la confirmación al cliente por WhatsApp. Sin el parámetro, rige el valor predeterminado del tipo (como en el formulario de la pantalla); sin tipo, no envía. Envíe false para no enviarla incluso en un tipo que pide confirmación. |
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=agenda/criar" \
-H "Authorization: Bearer $CHATISP_CHAVE" \
-H "Content-Type: application/json" \
-d '{"titulo": "Visita técnica: cambio de router", "tipo_id": 3, "inicio": "2026-10-02T09:00:00-03:00", "local": "Rua das Palmeiras, 120, Centro", "responsavel_id": 7, "departamento_id": 3, "telefone": "44999990000", "nome_cliente": "Maria Souza", "confirmar_cliente": true}'<?php
$dados = [
'titulo' => 'Visita técnica: cambio de router',
'tipo_id' => 3,
'inicio' => '2026-10-02T09:00:00-03:00',
'local' => 'Rua das Palmeiras, 120, Centro',
'responsavel_id' => 7,
'departamento_id' => 3,
'telefone' => '44999990000',
'nome_cliente' => 'Maria Souza',
'confirmar_cliente' => true,
];
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?r=agenda/criar');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CHATISP_CHAVE'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($dados, JSON_UNESCAPED_UNICODE),
]);
$resposta = json_decode(curl_exec($ch), true);import os, requests
resposta = requests.post(
"https://atendimento.seuprovedor.com.br/api_publica.php",
params={"r": "agenda/criar"},
headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
json={"titulo": "Visita técnica: cambio de router", "tipo_id": 3, "inicio": "2026-10-02T09:00:00-03:00", "local": "Rua das Palmeiras, 120, Centro", "responsavel_id": 7, "departamento_id": 3, "telefone": "44999990000", "nome_cliente": "Maria Souza", "confirmar_cliente": True},
timeout=30,
).json(){
"ok": true,
"compromisso": {
"id": 342,
"titulo": "Visita técnica: cambio de router",
"inicio": "2026-10-02T09:00:00-03:00",
"fim": "2026-10-02T10:00:00-03:00",
"estado": "agendado",
"origem": "api",
"...": "demás campos del objeto compromiso"
}
}Cómo se calcula el fin
- Con
dia_inteiro: del inicio al fin del día deinicio. - Con
fim: rige el valor informado. Un fin igual o anterior al inicio devuelveperiodo_invalido. - Con
duracao_min: inicio más la duración. - Sin ninguno de los tres: inicio más la duración predeterminada del tipo (como mínimo 15 minutos); sin tipo, 60 minutos.
Un compromiso puede durar como máximo 30 días.
Qué sucede al agendar
- Alertas programadas: las antelaciones de la alerta al responsable y del recordatorio al cliente vienen del tipo. Sin tipo, el responsable recibe la alerta 15 minutos antes y el cliente no recibe recordatorio. Solo se programan las alertas cuyo horario todavía está en el futuro. Detalles en Alertas y recordatorios.
- Alerta al responsable: la persona responsable recibe por WhatsApp "Compromiso agendado para usted", con fecha, hora, cliente, lugar y enlace. Sin responsable, la alerta va al equipo del departamento. Rige para quien tiene el WhatsApp verificado y las alertas activadas en Mi cuenta.
- Confirmación al cliente: con
confirmar_cliente(o, sin el parámetro, cuando el tipo pide confirmación), el cliente recibe de inmediato el texto de confirmación configurado en Configuración (con las variables{nome},{data},{hora},{detalhes}y las demás). El mensaje sale por la atención vinculada, por la conversación más reciente con el número o, sin ninguna conversación, como mensaje suelto por el número conectado. Con el texto de confirmación vacío en Configuración, no se envía nada. Vea Textos al cliente. - Google Calendar: si la persona responsable conectó su cuenta de Google en Mi cuenta, el compromiso se refleja en su calendario de Google; si el tipo pide sala de Google Meet y el
linkvino vacío, la sala se crea y su dirección entra en el campolinkantes de que salgan la confirmación y la alerta. Una falla en Google nunca impide el agendamiento: el sistema lo intenta de nuevo en segundo plano. - Atención vinculada: con
conversa_id, la línea de tiempo de la atención registra el compromiso y, si la atención está abierta, recibe una nota interna con título, fecha y hora. El cliente no ve la nota.
Como en la pantalla, donde el interruptor Enviar confirmación al cliente ahora ya viene activado en los tipos que piden confirmación, la API sigue el tipo cuando no se envía confirmar_cliente. Los recordatorios programados por el tipo salen normalmente, con o sin confirmación.
La Agenda no tiene eventos de webhook. Para mantener un sistema externo al día, consulte agenda/listar periódicamente por el período que le interese.
Concluir
/api_publica.php?r=agenda/concluirMarca el compromiso como realizado y registra el resultado. Solo vale para un compromiso agendado; en otro estado, la respuesta es 409 estado_invalido con el estado actual.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | entero | sí | Id del compromiso. |
desfecho | texto | no | Lo que sucedió, hasta 2.000 caracteres. |
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=agenda/concluir" \
-H "Authorization: Bearer $CHATISP_CHAVE" \
-H "Content-Type: application/json" \
-d '{"id": 342, "desfecho": "Router cambiado, Wi-Fi probado con la clienta."}'<?php
$dados = [
'id' => 342,
'desfecho' => 'Router cambiado, Wi-Fi probado con la clienta.',
];
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?r=agenda/concluir');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CHATISP_CHAVE'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($dados, JSON_UNESCAPED_UNICODE),
]);
$resposta = json_decode(curl_exec($ch), true);import os, requests
resposta = requests.post(
"https://atendimento.seuprovedor.com.br/api_publica.php",
params={"r": "agenda/concluir"},
headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
json={"id": 342, "desfecho": "Router cambiado, Wi-Fi probado con la clienta."},
timeout=30,
).json(){
"ok": true,
"compromisso": {
"id": 342,
"estado": "concluido",
"desfecho": "Router cambiado, Wi-Fi probado con la clienta.",
"...": "demás campos del objeto compromiso"
}
}Las alertas aún no enviadas se descartan. La atención vinculada registra la conclusión en la línea de tiempo y, si está abierta, recibe una nota interna. El reflejo en Google Calendar, cuando existe, se sincroniza.
Cancelar
/api_publica.php?r=agenda/cancelarCancela el compromiso y registra el motivo. Solo vale para un compromiso agendado; en otro estado, la respuesta es 409 estado_invalido con el estado actual.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | entero | sí | Id del compromiso. |
desfecho | texto | no | Motivo de la cancelación, hasta 2.000 caracteres. |
curl -s -X POST "https://atendimento.seuprovedor.com.br/api_publica.php?r=agenda/cancelar" \
-H "Authorization: Bearer $CHATISP_CHAVE" \
-H "Content-Type: application/json" \
-d '{"id": 342, "desfecho": "El cliente pidió reprogramar para la próxima semana."}'<?php
$dados = [
'id' => 342,
'desfecho' => 'El cliente pidió reprogramar para la próxima semana.',
];
$ch = curl_init('https://atendimento.seuprovedor.com.br/api_publica.php?r=agenda/cancelar');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CHATISP_CHAVE'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($dados, JSON_UNESCAPED_UNICODE),
]);
$resposta = json_decode(curl_exec($ch), true);import os, requests
resposta = requests.post(
"https://atendimento.seuprovedor.com.br/api_publica.php",
params={"r": "agenda/cancelar"},
headers={"Authorization": "Bearer " + os.environ["CHATISP_CHAVE"]},
json={"id": 342, "desfecho": "El cliente pidió reprogramar para la próxima semana."},
timeout=30,
).json(){
"ok": true,
"compromisso": {
"id": 342,
"estado": "cancelado",
"desfecho": "El cliente pidió reprogramar para la próxima semana.",
"...": "demás campos del objeto compromiso"
}
}Las alertas pendientes se descartan, el evento reflejado en Google Calendar se elimina (y con él la sala de Meet) y la atención vinculada registra la cancelación. El cliente no recibe un mensaje automático de cancelación: si quiere avisarle, envíelo por la ruta mensagens/enviar.
La API no reprograma ni reabre compromisos. Para reprogramar, cancele el actual y agende uno nuevo con el horario correcto; si la confirmación está activada, el cliente recibe la nueva fecha.
Errores de las rutas de la Agenda
Además de los errores comunes a toda la API, descritos en Errores:
error | HTTP | Rutas | Causa |
|---|---|---|---|
permissao | 403 | todas | La clave no tiene Consultar agenda (lectura) o Gestionar agenda (escritura). El campo escopo indica cuál falta. |
parametro_obrigatorio | 400 | consultar, criar, concluir, cancelar | Faltó id o inicio (vea campo). |
nao_encontrado | 404 | consultar, concluir, cancelar | Ningún compromiso con ese id. |
tipo_invalido | 400 | criar | Tipo inexistente o desactivado. |
estado_invalido | 409 | concluir, cancelar | El compromiso no está agendado (ya fue concluido o cancelado). El campo estado trae el estado actual. |
titulo_invalido | 400 | criar | Título vacío o con más de 160 caracteres. |
data_invalida | 400 | listar, criar | Fecha que no se pudo interpretar (vea campo). Use ISO 8601 o AAAA-MM-DD HH:MM:SS; palabras como "mañana" no se aceptan. |
periodo_invalido | 400 | listar, criar | En el listado: ate antes de de, o período mayor que 366 días (con maximo_dias). En el agendamiento: fin igual o anterior al inicio. |
link_invalido | 400 | criar | Enlace que no empieza con http:// o https://, tiene espacios o supera los 500 caracteres. |
telefone_invalido | 400 | listar, criar | El teléfono no es un número de WhatsApp válido. |
parametro_invalido | 400 | listar, criar | estado desconocido (lista en aceitos), responsable o departamento inexistente, responsable inactivo, descripción de más de 5.000 caracteres, duración de más de 30 días, número con letras, limite mayor que 100. |
{"ok": false, "error": "periodo_invalido", "maximo_dias": 366}