@agentcrafta/chat-next 0.0.10 → 0.0.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +249 -39
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -15,6 +15,7 @@ Este componente utiliza el Web Chat de Bot Framework para comunicarse con Power
|
|
|
15
15
|
- [Hook useChat](#hook-usechat)
|
|
16
16
|
- [Configuración de StyleOptions](#configuración-de-styleoptions)
|
|
17
17
|
- [Tipos y Interfaces](#tipos-y-interfaces)
|
|
18
|
+
- [Styles](#styles)
|
|
18
19
|
|
|
19
20
|
## Instalación y Configuración
|
|
20
21
|
|
|
@@ -24,12 +25,15 @@ Configure las siguientes variables en su archivo `.env.local` para desarrollo lo
|
|
|
24
25
|
|
|
25
26
|
```env
|
|
26
27
|
# URL del endpoint para obtener tokens del agente conversacional
|
|
28
|
+
|
|
27
29
|
TOKEN_AGENTE_URL=https://your-bot-endpoint.com/powervirtualagents/botsbyschema/...
|
|
30
|
+
# o
|
|
31
|
+
NEXT_PUBLIC_TOKEN_AGENTE_URL=https://your-bot-endpoint.com/powervirtualagents/botsbyschema/...
|
|
28
32
|
```
|
|
29
33
|
|
|
30
|
-
Para PRODUCCIÓN
|
|
34
|
+
Para **PRODUCCIÓN**, asegúrese de establecer esta variable en su entorno de despliegue.
|
|
31
35
|
|
|
32
|
-
**Importante**: La variable
|
|
36
|
+
**Importante**: La variable debe apuntar al endpoint completo de Power Virtual Agents que incluye el esquema del bot y la API version.
|
|
33
37
|
|
|
34
38
|
## Uso del Componente
|
|
35
39
|
|
|
@@ -43,25 +47,39 @@ Para PRODUCCIÓN, asegúrese de establecer estas variables en su entorno de desp
|
|
|
43
47
|
|
|
44
48
|
### Props del Componente
|
|
45
49
|
|
|
46
|
-
| Prop | Tipo
|
|
47
|
-
| -------------- |
|
|
48
|
-
| `botName` | `string`
|
|
49
|
-
| `logoUrl` | `string`
|
|
50
|
-
| `show` | `boolean`
|
|
51
|
-
| `styleOptions` | `StyleOptions`
|
|
50
|
+
| Prop | Tipo | Default | Descripción |
|
|
51
|
+
| -------------- | -------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------- |
|
|
52
|
+
| `botName` | `string` | `"Agent"` | Nombre que se mostrará en la cabecera del chat |
|
|
53
|
+
| `logoUrl` | `string` | `undefined` | URL del logo que se mostrará junto al nombre del bot (opcional) |
|
|
54
|
+
| `show` | `boolean` | `true` | Indica si el chat debe mostrarse o no (por defecto es true) |
|
|
55
|
+
| `styleOptions` | `StyleOptions` | `undefined` | Opciones de estilo personalizadas para el chat (opcional) |
|
|
56
|
+
| `entryPoint` | `string` | `undefined` | Punto de entrada para la conversación (opcional) |
|
|
57
|
+
| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"` | Posición del chat en la pantalla (por defecto es "bottom-right") |
|
|
58
|
+
| `chatButton` | `(props: ChatButtonProps) => React.ReactNode` | `undefined` | Elemento de botón personalizado para abrir el chat (opcional) |
|
|
52
59
|
|
|
53
60
|
### Importación y Uso
|
|
54
61
|
|
|
62
|
+
Importante: Componente de tipo Client Component, debe ser utilizado dentro de un componente con `'use client'` en Next.js.
|
|
63
|
+
|
|
64
|
+
En el archivo **layout** o en la página donde desea mostrar el chat, importe los estilos del componente
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
import "@agentcrafta/chat-next/styles.css";
|
|
68
|
+
```
|
|
69
|
+
|
|
55
70
|
#### Básico
|
|
56
71
|
|
|
57
72
|
```tsx
|
|
58
|
-
import { Chat } from "
|
|
73
|
+
import { Chat } from "@agentcrafta/chat-next";
|
|
59
74
|
|
|
60
75
|
export default function HomePage() {
|
|
61
76
|
return (
|
|
62
77
|
<div>
|
|
63
78
|
<h1>Mi Aplicación</h1>
|
|
64
|
-
<Chat
|
|
79
|
+
<Chat
|
|
80
|
+
entryPoint={process.env.NEXT_PUBLIC_TOKEN_AGENTE_URL || ""}
|
|
81
|
+
botName="Asistente Virtual"
|
|
82
|
+
/>
|
|
65
83
|
</div>
|
|
66
84
|
);
|
|
67
85
|
}
|
|
@@ -70,7 +88,8 @@ export default function HomePage() {
|
|
|
70
88
|
#### Avanzado con Personalización de Estilos
|
|
71
89
|
|
|
72
90
|
```tsx
|
|
73
|
-
|
|
91
|
+
"use client";
|
|
92
|
+
import { Chat } from "@agentcrafta/chat-next";
|
|
74
93
|
|
|
75
94
|
export default function HomePage() {
|
|
76
95
|
return (
|
|
@@ -78,26 +97,14 @@ export default function HomePage() {
|
|
|
78
97
|
<h1>Mi Aplicación</h1>
|
|
79
98
|
<Chat
|
|
80
99
|
botName="Asistente Virtual"
|
|
81
|
-
logoUrl="logo.svg"
|
|
100
|
+
logoUrl="/logo.svg"
|
|
101
|
+
entryPoint={process.env.NEXT_PUBLIC_TOKEN_AGENTE_URL || ""}
|
|
82
102
|
styleOptions={{
|
|
83
|
-
|
|
84
|
-
backgroundColor: getCssVariableAsHex("var(--background)"),
|
|
85
|
-
//Respuestas del Bot
|
|
86
|
-
botAvatarBackgroundColor: getCssVariableAsHex("var(--background)"),
|
|
87
|
-
bubbleBackground: getCssVariableAsHex("var(--muted)"),
|
|
88
|
-
bubbleBorderRadius: 10,
|
|
89
|
-
//Mensajes del usuario
|
|
90
|
-
bubbleFromUserBackground: getCssVariableAsHex("var(--secondary)"),
|
|
91
|
-
bubbleFromUserBorderRadius: 10,
|
|
92
|
-
bubbleFromUserTextColor: getCssVariableAsHex("var(--background)"),
|
|
93
|
-
userAvatarBackgroundColor: getCssVariableAsHex("var(--primary)"),
|
|
94
|
-
//Caja de escritura
|
|
95
|
-
sendBoxHeight: 50,
|
|
96
|
-
sendBoxPlaceholderColor: getCssVariableAsHex("var(--muted)"),
|
|
97
|
-
sendBoxBackground: getCssVariableAsHex("var(--background)"),
|
|
98
|
-
sendBoxBorderTop: `solid 1px ${getCssVariableAsHex("var(--border)")}`,
|
|
99
|
-
sendBoxButtonColor: getCssVariableAsHex("var(--primary)"),
|
|
103
|
+
backgroundColor: "#7e0f0f",
|
|
100
104
|
}}
|
|
105
|
+
chatButton={({ isVisible, toggle }) => (
|
|
106
|
+
<button onClick={toggle}>{isVisible ? "Cerrar" : "Abrir"}</button>
|
|
107
|
+
)}
|
|
101
108
|
/>
|
|
102
109
|
</div>
|
|
103
110
|
);
|
|
@@ -106,23 +113,25 @@ export default function HomePage() {
|
|
|
106
113
|
|
|
107
114
|
## Server Actions
|
|
108
115
|
|
|
109
|
-
|
|
116
|
+
De manera informativa, no se expone directamente la API de Server Actions, pero el componente las utiliza internamente para obtener tokens, configuración y registrar errores. A continuación se describen las funciones disponibles:
|
|
117
|
+
|
|
118
|
+
### `getRegionalSettings(tokenEndpoint?: string)`
|
|
110
119
|
|
|
111
120
|
**Propósito**: Obtiene la configuración regional del bot, incluyendo las URLs de los canales disponibles.
|
|
112
121
|
|
|
113
122
|
```typescript
|
|
114
|
-
const data = await getRegionalSettings();
|
|
123
|
+
const data = await getRegionalSettings(tokenEndpoint?: string);
|
|
115
124
|
console.log(data.channelUrlsById.directline); // URL de DirectLine
|
|
116
125
|
```
|
|
117
126
|
|
|
118
127
|
**Retorna**: Configuración regional con URLs de canales disponibles.
|
|
119
128
|
|
|
120
|
-
### `getConversationToken()`
|
|
129
|
+
### `getConversationToken(tokenEndpoint?: string)`
|
|
121
130
|
|
|
122
131
|
**Propósito**: Obtiene el token de autenticación necesario para establecer la conexión con DirectLine.
|
|
123
132
|
|
|
124
133
|
```typescript
|
|
125
|
-
const token = await getConversationToken();
|
|
134
|
+
const token = await getConversationToken(tokenEndpoint?: string);
|
|
126
135
|
```
|
|
127
136
|
|
|
128
137
|
**Retorna**: Token de conversación válido para DirectLine.
|
|
@@ -167,9 +176,10 @@ await logChatError({
|
|
|
167
176
|
|
|
168
177
|
### Props del Hook
|
|
169
178
|
|
|
170
|
-
| Prop
|
|
171
|
-
|
|
|
172
|
-
| `
|
|
179
|
+
| Prop | Tipo | Default | Descripción |
|
|
180
|
+
| ------------------- | -------------- | ------------- | --------------------------------------------------------- |
|
|
181
|
+
| `styleOptionsProps` | `StyleOptions` | `undefined` | Opciones de estilo personalizadas para el chat (opcional) |
|
|
182
|
+
| `entryPoint` | `string` | **Requerido** | Punto de entrada para la conversación |
|
|
173
183
|
|
|
174
184
|
```typescript
|
|
175
185
|
const {
|
|
@@ -177,7 +187,7 @@ const {
|
|
|
177
187
|
isRestarting, // boolean - Estado de reinicio
|
|
178
188
|
chatKey, // number - Key para forzar re-render
|
|
179
189
|
webChatRef, // RefObject - Referencia al DOM del chat
|
|
180
|
-
|
|
190
|
+
styleOptionsMerged, // StyleOptions - Configuración de estilos
|
|
181
191
|
// ... funciones
|
|
182
192
|
} = useChat();
|
|
183
193
|
```
|
|
@@ -304,19 +314,219 @@ Interface para la biblioteca global de Web Chat con métodos de creación y rend
|
|
|
304
314
|
|
|
305
315
|
---
|
|
306
316
|
|
|
317
|
+
## Styles
|
|
318
|
+
|
|
319
|
+
El componente usa su propio css interno.
|
|
320
|
+
|
|
321
|
+
```css
|
|
322
|
+
/* Estilos base para AgentCrafta Chat */
|
|
323
|
+
.agentcrafta-chat-container {
|
|
324
|
+
position: fixed;
|
|
325
|
+
z-index: 999;
|
|
326
|
+
display: flex;
|
|
327
|
+
align-items: flex-end;
|
|
328
|
+
gap: 1rem;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
/* Bottom Right: Chat a la izquierda, botón a la derecha */
|
|
332
|
+
.agentcrafta-chat-container.bottom-right {
|
|
333
|
+
bottom: 2rem;
|
|
334
|
+
right: 2rem;
|
|
335
|
+
flex-direction: row;
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/* Bottom Left: Botón a la izquierda, chat a la derecha */
|
|
339
|
+
.agentcrafta-chat-container.bottom-left {
|
|
340
|
+
bottom: 2rem;
|
|
341
|
+
left: 2rem;
|
|
342
|
+
flex-direction: row-reverse;
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
/* Top Right: Chat a la izquierda, botón a la derecha */
|
|
346
|
+
.agentcrafta-chat-container.top-right {
|
|
347
|
+
top: 2rem;
|
|
348
|
+
right: 2rem;
|
|
349
|
+
flex-direction: row;
|
|
350
|
+
align-items: flex-start;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/* Top Left: Botón a la izquierda, chat a la derecha */
|
|
354
|
+
.agentcrafta-chat-container.top-left {
|
|
355
|
+
top: 2rem;
|
|
356
|
+
left: 2rem;
|
|
357
|
+
flex-direction: row-reverse;
|
|
358
|
+
align-items: flex-start;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
.agentcrafta-chat-window {
|
|
362
|
+
height: 520px;
|
|
363
|
+
width: 450px;
|
|
364
|
+
overflow: hidden;
|
|
365
|
+
border-radius: 1rem;
|
|
366
|
+
background-color: white;
|
|
367
|
+
box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
|
|
368
|
+
transition: all 0.3s ease-in-out;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
.agentcrafta-chat-window.bottom-right,
|
|
372
|
+
.agentcrafta-chat-window.bottom-left {
|
|
373
|
+
transform-origin: bottom;
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
.agentcrafta-chat-window.top-right,
|
|
377
|
+
.agentcrafta-chat-window.top-left {
|
|
378
|
+
transform-origin: top;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
.agentcrafta-chat-window.visible {
|
|
382
|
+
transform: scale(1);
|
|
383
|
+
opacity: 1;
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
.agentcrafta-chat-window.hidden {
|
|
387
|
+
transform: scale(0.95);
|
|
388
|
+
opacity: 0;
|
|
389
|
+
pointer-events: none;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
.agentcrafta-chat-header {
|
|
393
|
+
display: flex;
|
|
394
|
+
height: 3.5rem;
|
|
395
|
+
align-items: center;
|
|
396
|
+
justify-content: space-between;
|
|
397
|
+
padding: 0 1.25rem;
|
|
398
|
+
background-color: var(--primary-color, #0066cc);
|
|
399
|
+
color: white;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
.agentcrafta-chat-header-content {
|
|
403
|
+
display: flex;
|
|
404
|
+
align-items: center;
|
|
405
|
+
gap: 0.75rem;
|
|
406
|
+
font-size: 1rem;
|
|
407
|
+
font-weight: 500;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
.agentcrafta-chat-logo {
|
|
411
|
+
height: 1.75rem;
|
|
412
|
+
width: 1.75rem;
|
|
413
|
+
border-radius: 0.25rem;
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
.agentcrafta-chat-actions {
|
|
417
|
+
display: flex;
|
|
418
|
+
align-items: center;
|
|
419
|
+
gap: 0.75rem;
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
.agentcrafta-chat-button {
|
|
423
|
+
border-radius: 0.5rem;
|
|
424
|
+
padding: 0.5rem;
|
|
425
|
+
transition: background-color 0.2s;
|
|
426
|
+
border: none;
|
|
427
|
+
background: transparent;
|
|
428
|
+
cursor: pointer;
|
|
429
|
+
color: inherit;
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
.agentcrafta-chat-button:hover {
|
|
433
|
+
background-color: rgba(255, 255, 255, 0.1);
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
.agentcrafta-chat-button:disabled {
|
|
437
|
+
cursor: not-allowed;
|
|
438
|
+
opacity: 0.5;
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
.agentcrafta-chat-content {
|
|
442
|
+
position: relative;
|
|
443
|
+
height: calc(100% - 56px);
|
|
444
|
+
width: 100%;
|
|
445
|
+
background-color: #f9fafb;
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
.agentcrafta-chat-loading {
|
|
449
|
+
position: absolute;
|
|
450
|
+
inset: 0;
|
|
451
|
+
z-index: 10;
|
|
452
|
+
display: flex;
|
|
453
|
+
align-items: center;
|
|
454
|
+
justify-content: center;
|
|
455
|
+
background-color: rgba(249, 250, 251, 0.8);
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
.agentcrafta-chat-loading-content {
|
|
459
|
+
display: flex;
|
|
460
|
+
flex-direction: column;
|
|
461
|
+
align-items: center;
|
|
462
|
+
gap: 0.75rem;
|
|
463
|
+
color: #4b5563;
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
.agentcrafta-chat-loading-spinner {
|
|
467
|
+
height: 2rem;
|
|
468
|
+
width: 2rem;
|
|
469
|
+
animation: spin 1s linear infinite;
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
@keyframes spin {
|
|
473
|
+
from {
|
|
474
|
+
transform: rotate(0deg);
|
|
475
|
+
}
|
|
476
|
+
to {
|
|
477
|
+
transform: rotate(360deg);
|
|
478
|
+
}
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
.agentcrafta-chat-loading-text {
|
|
482
|
+
font-size: 0.875rem;
|
|
483
|
+
font-weight: 500;
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
/* Estilos para el botón flotante */
|
|
487
|
+
.agentcrafta-chat-fab {
|
|
488
|
+
height: 3.5rem;
|
|
489
|
+
width: 3.5rem;
|
|
490
|
+
border-radius: 9999px;
|
|
491
|
+
background-color: var(--primary-color, #0066cc);
|
|
492
|
+
color: white;
|
|
493
|
+
border: none;
|
|
494
|
+
cursor: pointer;
|
|
495
|
+
display: flex;
|
|
496
|
+
align-items: center;
|
|
497
|
+
justify-content: center;
|
|
498
|
+
box-shadow:
|
|
499
|
+
0 10px 15px -3px rgba(0, 0, 0, 0.1),
|
|
500
|
+
0 4px 6px -2px rgba(0, 0, 0, 0.05);
|
|
501
|
+
transition: all 0.2s;
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
.agentcrafta-chat-fab:hover {
|
|
505
|
+
transform: scale(1.1);
|
|
506
|
+
box-shadow:
|
|
507
|
+
0 20px 25px -5px rgba(0, 0, 0, 0.1),
|
|
508
|
+
0 10px 10px -5px rgba(0, 0, 0, 0.04);
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
.agentcrafta-chat-fab:active {
|
|
512
|
+
transform: scale(1.05);
|
|
513
|
+
}
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
---
|
|
517
|
+
|
|
307
518
|
## Notas de Implementación
|
|
308
519
|
|
|
309
520
|
1. **Seguridad**: El componente incluye validación de tokens y manejo de errores robusto
|
|
310
521
|
2. **Performance**: Utiliza el patrón React key para reinicializaciones eficientes
|
|
311
522
|
3. **Accesibilidad**: Incluye labels ARIA y soporte para navegación por teclado
|
|
312
523
|
4. **Responsive**: Diseño adaptable para diferentes dispositivos
|
|
313
|
-
5. **Temas**: Integración completa con el sistema de temas de la aplicación
|
|
314
524
|
|
|
315
525
|
## Troubleshooting
|
|
316
526
|
|
|
317
527
|
### Problemas Comunes
|
|
318
528
|
|
|
319
529
|
1. **Chat no se inicializa**: Verificar `TOKEN_AGENTE_URL` en `.env`
|
|
320
|
-
2. **Estilos no se aplican**: Verificar variables CSS disponibles
|
|
530
|
+
2. **Estilos no se aplican**: Verificar variables CSS disponibles e importacion de estilos
|
|
321
531
|
3. **Errores de conexión**: Revisar configuración de CORS y headers de seguridad
|
|
322
532
|
4. **Imágenes no cargan**: Verificar rutas en carpeta `public/`
|