dotly-sdk
v0.3.0
Published
SDK oficial de JavaScript/TypeScript para la API de Dotly (servidor) y Dotly embebido (navegador).
Maintainers
Readme
dotly-sdk — SDK oficial de JavaScript/TypeScript para Dotly
Versión 0.3.0, API 1.3.0. Descarga de esta versión desde Dotly (no depende de su publicación en npm):
dotly.connections administra conectores con integrations:manage: types, list, get, create, update, delete, test, sync, upload (base64) y runs. Los campos de cada proveedor se descubren con types(); los secretos nunca se devuelven.
npm install https://www.dotly.com.py/panel/static/downloads/dotly-sdk-0.3.0.tgzEl widget también se importa sin empaquetador desde https://www.dotly.com.py/api/v1/widget.js (exporta mount y defineElement). Tu backend autenticado emite la sesión y solo entrega su URL al navegador. handle.renew(url) abre una nueva sesión; destroy() retira el iframe, pero tu backend debe revocar la sesión. Las claves nunca van en el navegador.
Novedades: dotly.ai.getProvider/configureProvider/testProvider/removeProvider, dotly.orders, dotly.broadcasts, dotly.scheduledMessages.capacity/update, sugerencias con instruction/messageId y dotly.conversations.update(id, {ai_paused:true}) para coordinar agentes externos. La IA propia requiere suscripción activa y permisos, se configura por aplicación y se factura en el proveedor; no reemplaza el piloto automático ni los programados de Dot AI. testProvider() realiza una consulta que el proveedor puede cobrar.
Guía y capturas reales del entorno de prueba: API & SDK.
Dos partes, con límites claros:
| Importación | Dónde | Para qué |
|---|---|---|
| dotly-sdk | Servidor (Node.js 18+, Deno, Bun, workers) | La API de Dotly con tu clave secreta (dtly_live_...). |
| dotly-sdk/webhooks | Servidor | Verificar la firma de los webhooks. |
| dotly-sdk/embed | Navegador | Mostrar Dotly dentro de tu sistema con una sesión corta que pide tu servidor. Sin claves. |
El cliente de la API se niega a funcionar en un navegador: la clave de API nunca puede llegar al frontend.
npm install dotly-sdkServidor
import { Dotly } from "dotly-sdk";
const dotly = new Dotly(); // lee DOTLY_API_KEY
const contact = await dotly.contacts.create({ phone: "595981123456", name: "Juan Pérez" });
await dotly.integration.contacts.upsert("crm-1042", { name: "Juan Pérez", phone: "595981123456", company: "Acme" });
for await (const conversation of dotly.conversations.iter({ status: "open" })) {
console.log(conversation.contact?.name);
}
const suggestion = await dotly.ai.suggestReply(conversationId);Cada clave actúa en nombre de un integrante de tu equipo (puede, como mucho, lo que esa persona puede en Dotly).
Errores con status, code y requestId: InsufficientCreditsError, PermissionDeniedError, NotFoundError,
RateLimitError, AIUnavailableError... Reintentos seguros: cada escritura lleva una Idempotency-Key (la misma en
sus reintentos), así un reintento nunca duplica un envío ni cobra dos veces Dot AI.
Webhooks
import express from "express";
import { constructEvent } from "dotly-sdk/webhooks";
app.post("/webhooks/dotly", express.raw({ type: "application/json" }), async (req, res) => {
try {
const event = await constructEvent(req.body, req.get("Dotly-Signature"), process.env.DOTLY_WEBHOOK_SECRET!);
// guardá event.id para descartar repetidos (la entrega es "al menos una vez")
res.sendStatus(200);
} catch {
res.sendStatus(400);
}
});Usá el cuerpo crudo (express.raw, no express.json). Se rechazan firmas inválidas y marcas de tiempo de más de 5 minutos.
Dotly dentro de tu sistema
- En Dotly → API & SDK → tu aplicación → Embebido: autorizá tu dominio y los módulos.
- Tu servidor pide la sesión (la clave queda en el servidor):
const { url } = await dotly.embedSessions.create({
origin: "https://crm.tuempresa.com",
modules: ["inbox", "contacts"],
member_email: "[email protected]",
theme: { accent: "#ff6600", radius: 8 },
});- Tu página la muestra:
import { mount } from "dotly-sdk/embed";
const dotly = mount(document.querySelector("#dotly"), {
url, // de un solo uso, vence en 2 minutos
onEvent: (event) => console.log(event.type), // dotly:ready, dotly:navigated, dotly:session.expired...
});
dotly.navigate("inbox", { conversation_id: "..." });O como Web Component: defineElement() y <dotly-embed session-url="..."></dotly-embed>.
Dotly se abre con los permisos de esa persona recortados a los módulos pedidos, solo en tu dominio autorizado
(frame-ancestors), con una cookie particionada (no depende de cookies de terceros). Si el navegador bloquea
incluso esas cookies, recibís dotly:error con code: "cookies_blocked" para ofrecer abrir Dotly en una pestaña.
Licencia MIT.
