Ejemplos de integración

¡Hola, {{1}}! Habrá mantenimiento programado en la red de su barrio ({{2}}) el {{3}}.
La conexión puede oscilar durante el período. ¡Gracias por su comprensión!

<?php
// Llamado por la rutina del ERP en el momento del bloqueo, con los datos del contrato.
require 'ChatIspApi.php';
$api = ChatIspApi::doAmbiente();

const DEPARTAMENTO_FINANCEIRO = 2;
const ETIQUETA_BLOQUEADO = 5;          // etiquetas/listar

function avisarBloqueio(ChatIspApi $api, array $contrato): void
{
    $nota = sprintf(
        "Contrato %s bloqueado por deuda. Plan: %s. Pendiente: R$ %s en %d factura(s), vencida desde %s.",
        $contrato['numero'], $contrato['plano'],
        number_format($contrato['valor_aberto'], 2, ',', '.'), $contrato['faturas'], $contrato['vencimento']
    );

    // 1) abre (o reutiliza) la atención en la cola de Financeiro, con la nota interna
    $r = $api->post('atendimentos/abrir', [
        'telefone' => $contrato['celular'],
        'nome' => $contrato['cliente'],
        'departamento_id' => DEPARTAMENTO_FINANCEIRO,
        'nota' => $nota,    // hasta 900 caracteres; solo el equipo la ve
    ]);
    $conversaId = $r['conversa']['id'];

    // 2) etiqueta para que el equipo filtre en el panel
    $api->post('conversas/etiquetas', ['conversa_id' => $conversaId, 'adicionar' => [ETIQUETA_BLOQUEADO]]);

    // 3) mensaje al cliente dentro de la misma atención
    $primeiroNome = explode(' ', $contrato['cliente'])[0];
    try {
        $api->post('mensagens/enviar', [
            'conversa_id' => $conversaId,
            'texto' => "¡Hola, {$primeiroNome}! Identificamos pendientes en su contrato y el acceso fue suspendido. "
                     . "Responda este mensaje y le enviamos el Pix o la segunda vía al instante.",
        ]);
    } catch (ChatIspErro $e) {
        if ($e->codigo !== 'janela_fechada') throw $e;
        // API oficial fuera de la ventana de 24 h: solo plantilla aprobada
        $api->post('mensagens/enviar_modelo', [
            'conversa_id' => $conversaId,
            'modelo' => 'aviso_suspensao',
            'variaveis' => [$primeiroNome],
        ]);
    }
}

avisarBloqueio($api, [
    'numero' => '10234', 'cliente' => 'João Pereira', 'celular' => '44999990002', 'plano' => 'Fibra 500 Mega',
    'valor_aberto' => 239.80, 'faturas' => 2, 'vencimento' => '10/09/2026',
]);

# Conéctelo a su monitoreo: "python noc_alarme.py problema <id_alarma>" y "python noc_alarme.py normalizado <id_alarma>"
import json, sys
from pathlib import Path
from chatisp_api import ChatIspApi

api = ChatIspApi.do_ambiente()
ESTADO = Path("noc_tickets.json")          # id de la alarma -> ticket_id y conversa_id
TIPO_REPARO = 2                            # tickets/tipos: "Reparo de rede" (reparación de red)
DEPARTAMENTO_SUPORTE = 3


def cliente_do_alarme(alarme_id):
    """De su sistema: datos del cliente vinculado al equipo que generó la alarma."""
    return {"nome": "Mercado Bom Preço", "telefone": "44999990003",
            "endereco": "Av. Brasil, 2100, Centro", "equipamento": "ONU ZTE F670L serial ZTEG00000001",
            "sinal": "LOS (sin luz)"}


def etapa_final_resolvido():
    etapas = api.get("tickets/etapas")["etapas"]
    return next(e["id"] for e in etapas if e["natureza"] == "resolvido" and e["ativa"])


def problema(alarme_id):
    estado = json.loads(ESTADO.read_text()) if ESTADO.exists() else {}
    if alarme_id in estado:
        return                                   # alarma repetida: OS ya abierta
    c = cliente_do_alarme(alarme_id)

    # 1) aviso al cliente (sin conversación abierta, nace como aviso cerrado)
    aviso = api.post("mensagens/enviar", telefone=c["telefone"], nome=c["nome"],
                     texto="¡Hola! Nuestro monitoreo detectó una falla en su enlace y el equipo técnico "
                           "ya fue convocado. Le avisaremos por aquí en cuanto se normalice.")

    # 2) OS de reparación, vinculada a la conversación del aviso
    t = api.post("tickets/criar",
                 titulo=f"Enlace caído: {c['nome']}",
                 descricao=f"Alarma {alarme_id}. Equipo: {c['equipamento']}. Señal: {c['sinal']}.",
                 tipo_id=TIPO_REPARO, prioridade="urgente", departamento_id=DEPARTAMENTO_SUPORTE,
                 conversa_id=aviso["conversa_id"], telefone=c["telefone"],
                 nome_cliente=c["nome"], endereco=c["endereco"])["ticket"]

    estado[alarme_id] = {"ticket_id": t["id"], "conversa_id": aviso["conversa_id"]}
    ESTADO.write_text(json.dumps(estado))
    print("OS", t["numero"], "plazo", t["prazo_em"])


def normalizado(alarme_id):
    estado = json.loads(ESTADO.read_text()) if ESTADO.exists() else {}
    registro = estado.pop(alarme_id, None)
    if not registro:
        return
    ticket_id = registro["ticket_id"]
    atual = api.get("tickets/consultar", ticket_id=ticket_id)["ticket"]
    if not atual["concluido"]:
        api.post("tickets/comentar", ticket_id=ticket_id, texto="Monitoreo: alarma normalizada.")
        api.post("tickets/mover", ticket_id=ticket_id, etapa_id=etapa_final_resolvido(),
                 comentario="Cerrado automáticamente por el NOC.")
    api.post("mensagens/enviar", conversa_id=registro["conversa_id"],
             texto="Buena noticia: su enlace se normalizó. Si nota cualquier inestabilidad, solo responda aquí.")
    ESTADO.write_text(json.dumps(estado))


if __name__ == "__main__":
    {"problema": problema, "normalizado": normalizado}[sys.argv[1]](sys.argv[2])

<?php
require 'ChatIspApi.php';
$api = ChatIspApi::doAmbiente();

$assinante = portalAssinanteLogado();          // de su sistema: nombre, celular, contrato
$relato = mb_substr(trim($_POST['relato'] ?? ''), 0, 600);

try {
    $r = $api->post('atendimentos/abrir', [
        'telefone' => $assinante['celular'],
        'nome' => $assinante['nome'],
        'departamento_id' => 3,                  // Suporte técnico (soporte técnico)
        'nota' => "Abierto desde el portal (contrato {$assinante['contrato']}): {$relato}",
    ]);
    $conversa = $r['conversa'];

    // confirmación al cliente dentro de la atención recién abierta
    $api->post('mensagens/enviar', [
        'conversa_id' => $conversa['id'],
        'texto' => "Recibimos su pedido por el portal (protocolo {$conversa['protocolo']}). "
                 . "Un agente hablará con usted por aquí.",
    ]);
} catch (ChatIspErro $e) {
    if ($e->codigo !== 'janela_fechada') {   // API oficial fuera de la ventana: el agente hace el primer contacto
        http_response_code(502);
        exit('No fue posible abrir la atención ahora. Escríbanos por WhatsApp.');
    }
}

portalSalvarPedido($assinante['contrato'], $conversa['id'], $conversa['protocolo']);   // de su sistema
echo "Pedido registrado. Protocolo {$conversa['protocolo']}.";

const express = require('express');
const crypto = require('crypto');
const { pedidoPorConversa, atualizarPedido } = require('./pedidos');   // de su sistema

const app = express();
const SEGREDO = process.env.CHATISP_WEBHOOK_SEGREDO;

function assinaturaValida(corpo, cabecalho) {
  const esperada = Buffer.from('sha256=' + crypto.createHmac('sha256', SEGREDO).update(corpo).digest('hex'));
  const recebida = Buffer.from(cabecalho || '');
  return esperada.length === recebida.length && crypto.timingSafeEqual(esperada, recebida);
}

app.post('/chatisp/webhook', express.raw({ type: 'application/json', limit: '1mb' }), async (req, res) => {
  if (!assinaturaValida(req.body, req.get('X-ChatISP-Assinatura'))) return res.sendStatus(401);
  const { evento, dados } = JSON.parse(req.body.toString('utf8'));
  if (evento === 'teste') return res.sendStatus(200);

  const pedido = await pedidoPorConversa(dados.conversa_id);
  if (!pedido) return res.sendStatus(200);       // conversación que no vino del portal

  switch (evento) {
    case 'conversa_atribuida':
      await atualizarPedido(pedido.id, { situacao: 'En atención', atendente: dados.atendente });
      break;
    case 'mensagem_enviada':
      if (dados.mensagem.autor === 'atendente' || dados.mensagem.autor === 'ia') {
        await atualizarPedido(pedido.id, { ultimaResposta: dados.mensagem.conteudo, em: dados.mensagem.enviada_em });
      }
      break;
    case 'conversa_encerrada':
      await atualizarPedido(pedido.id, { situacao: 'Concluido', motivo: dados.motivo });
      break;
  }
  res.sendStatus(200);
});

app.listen(3000);

# Ejecute cada 5 o 10 minutos (cron, programador de tareas, systemd timer).
import json
from datetime import datetime, timedelta
from pathlib import Path
from chatisp_api import ChatIspApi

api = ChatIspApi.do_ambiente()
MARCO = Path("chatisp_marco.json")
FOLGA = timedelta(minutes=5)       # superposición entre ejecuciones: nada se escapa, la grabación es idempotente


def gravar_conversa(c):             # de su sistema: INSERT ... ON DUPLICATE KEY UPDATE por c["id"]
    ...

def gravar_mensagem(m):             # de su sistema: upsert por m["id"]
    ...

def ultimo_id_mensagem(conversa_id):   # de su sistema: mayor id de mensaje guardado (0 si no hay ninguno)
    return 0


def sincronizar():
    inicio = api.get("chave/info")["servidor"]["agora"]
    estado = json.loads(MARCO.read_text()) if MARCO.exists() else {}
    filtros = {"ordem": "antigas"}
    if "marco" in estado:
        desde = datetime.fromisoformat(estado["marco"]) - FOLGA
        filtros["atualizadas_desde"] = desde.isoformat()
    # primera ejecución sin punto de control: trae el historial completo, página por página

    total = 0
    for conversa in api.todos("conversas/listar", "conversas", **filtros):
        gravar_conversa(conversa)
        cursor = ultimo_id_mensagem(conversa["id"])
        while True:
            r = api.get("conversas/mensagens", conversa_id=conversa["id"], depois_de=cursor, limite=100)
            for m in r["mensagens"]:
                gravar_mensagem(m)
            cursor = r["cursor"]["depois_de"] or cursor
            if not r["tem_mais"]:
                break
        total += 1

    MARCO.write_text(json.dumps({"marco": inicio}))
    print(f"{total} conversación(es) sincronizada(s)")


if __name__ == "__main__":
    sincronizar()

<?php
// Uso: php indicadores_mes.php            (mes anterior)
//      php indicadores_mes.php 2026-09    (mes elegido)
require 'ChatIspApi.php';
$api = ChatIspApi::doAmbiente();

$mes = $argv[1] ?? date('Y-m', strtotime('first day of last month'));
$de = "{$mes}-01";
$ate = date('Y-m-t', strtotime($de));      // último día del mes (vale hasta las 23:59:59)

$minutos = fn(?float $seg): string => $seg === null ? '' : number_format($seg / 60, 1, ',', '');
$pct = fn(int $parte, int $todo): string => $todo > 0 ? number_format(100 * $parte / $todo, 1, ',', '') : '';

$recortes = [['id' => 0, 'nome' => 'Todos los departamentos']];
foreach ($api->get('departamentos/listar')['departamentos'] as $d) {
    if ($d['ativo']) $recortes[] = $d;
}

$csv = fopen("indicadores-{$mes}.csv", 'w');
fwrite($csv, "\xEF\xBB\xBF");               // BOM: Excel lo abre con los acentos correctos
fputcsv($csv, ['Departamento', 'Abiertas', 'Cerradas', 'Resueltas por la IA (%)', 'Mensajes recibidos',
    'Primera respuesta (min)', 'Espera en la cola (min)', 'Duración media (min)', 'Satisfacción', 'Tasa de respuesta (%)'], ';');

foreach ($recortes as $d) {
    $r = $api->get('relatorios/resumo', ['de' => $de, 'ate' => $ate] + ($d['id'] ? ['departamento_id' => $d['id']] : []));
    fputcsv($csv, [
        $d['nome'],
        $r['conversas']['abertas'],
        $r['conversas']['encerradas'],
        $pct($r['conversas']['resolvidas_pela_ia'], $r['conversas']['encerradas']),
        $r['mensagens']['recebidas'],
        $minutos($r['tempos']['primeira_resposta_media_seg']),
        $minutos($r['tempos']['espera_fila_media_seg']),
        $minutos($r['tempos']['duracao_media_seg']),
        $r['satisfacao']['media'] === null ? '' : number_format($r['satisfacao']['media'], 2, ',', ''),
        $pct($r['satisfacao']['respostas'], $r['satisfacao']['pesquisas_enviadas']),
    ], ';');
    sleep(1);
}
fclose($csv);
echo "Generado indicadores-{$mes}.csv\n";

const { ChatIspApi, ChatIspErro } = require('./chatisp-api');
const api = ChatIspApi.doAmbiente();

async function idPorNome(rota, campo, nome) {
  const lista = (await api.get(rota))[campo];
  const item = lista.find((x) => x.nome.toLowerCase() === nome.toLowerCase());
  if (!item) throw new Error(`"${nome}" no existe en ${rota}`);
  return item.id;
}

async function pagamentoConfirmado({ telefone, valor, pagoEm }) {
  // atención abierta de este cliente (la más reciente)
  const { conversas } = await api.get('conversas/listar', { telefone, abertas: 1, limite: 1 });
  if (conversas.length === 0) return 'sin atención abierta';
  const conversa = conversas[0];

  const [pago, aguardando, motivo] = await Promise.all([
    idPorNome('etiquetas/listar', 'etiquetas', 'Pago'),
    idPorNome('etiquetas/listar', 'etiquetas', 'Aguardando pagamento'),
    idPorNome('motivos/listar', 'motivos', 'Pagamento confirmado'),
  ]);

  await api.post('conversas/etiquetas', { conversa_id: conversa.id, adicionar: [pago], remover: [aguardando] });
  await api.post('conversas/nota', {
    conversa_id: conversa.id,
    texto: `Pago de R$ ${valor} confirmado por el ERP el ${pagoEm}. Desbloqueo automático en curso.`,
  });

  try {
    await api.post('conversas/encerrar', {
      conversa_id: conversa.id,
      motivo_id: motivo,
      enviar_mensagem: true,   // false = cierra en silencio, sin mensaje de cierre ni encuesta
    });
  } catch (e) {
    if (!(e instanceof ChatIspErro && e.codigo === 'conversa_encerrada')) throw e;   // alguien la cerró antes
  }
  return conversa.protocolo;
}

pagamentoConfirmado({ telefone: '44999990002', valor: '239,80', pagoEm: '01/10/2026 15:42' })
  .then((r) => console.log('ok:', r))
  .catch((e) => console.error(e));