> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Definición de Campos

> Definición de Campos del Agente

### Campos Principales.

En esta sección se verá todos los campos correspondientes al agente de IA, a nivel de configruacion. En esta sección no se verán los campos de `services`, `channels` y `actions`.

<Accordion title="Archivo de Configuración - agent.config.json">
  Información global del archivo de configuración del Agente de IA

  ```json theme={null}
  {
    "name": "Sales Clinic",
    "description": "Virtual Agent IA assistant of the Dental Clinic Smiles",
    "prompt": "You are Máximo, a professional virtual assistant for Smiles Dental Clinic. Help patients with appointments, general information, and guide them through our services. Always maintain a professional yet friendly tone.",
    "zone": "LA",
    "buffer": 15,
    "color": "blue",
    "question": "How can I help you today?",
    "timezone": "America/Lima",
    "enable": true,
    "tags": [
      "health",
      "dentistry",
      "ia",
      "plazbot"
    ],
    "showInChat": false,
    "useToolCalling": true,
    "responseMode": "direct",
    "batchWaitSeconds": 3,
    "customAIConfig": false,
    "aiProviders": [
      {
        "provider": "openai",
        "model": "gpt-4o",
        "apiToken": "sk-...",
        "temperature": 0.7,
        "maxTokens": 1024,
        "isDefault": true
      }
    ],
    "version": "v2.0",
    "enableWidget": true,
    "darkWidget": true,
    "nameWidget": "Dental Assistant",
    "initialShowWidget": true,
    "examples": [
      { "value": "How to schedule an appointment?", "color": "green" },
      { "value": "What are your office hours?", "color": "blue" },
      { "value": "Do you accept insurance?", "color": "orange" },
      { "value": "Emergency contact information", "color": "gray" },
      { "value": "Location and directions", "color": "white" }
    ],
    "instructions": {
      "tone": "professional",
      "style": "short answers",
      "personality": "friendly",
      "objective": "help with clarity",
      "language": "es-419",
      "emojis": false,
      "preferredFormat": "plain text",
      "maxWords": 80,
      "avoidTopics": [
        "laboratory costs",
        "external claims",
        "specific medical diagnoses"
      ],
      "respondOnlyIfKnows": true,
      "maintainToneBetweenMessages": true,
      "greeting": "Hello, I am Máximo, your virtual assistant from Smiles Dental Clinic. How can I help you today?"
    },
    "person": {
      "name": "Máximo",
      "role": "Virtual customer service assistant",
      "speaksInFirstPerson": true,
      "isHuman": false
    },
    "fallbacks": {
      "noAnswer": "Sorry, I don't have information on that topic. Let me connect you with one of our specialists.",
      "serviceError": "There was a problem processing your request. Please try again later or contact us directly.",
      "doNotUnderstand": "Could you please repeat it in another way? I want to make sure I help you correctly."
    },
    "rules": {
      "doNotMentionPrices": false,
      "doNotDiagnose": true,
      "doNotRespondOutsideHours": "Our office hours are Monday to Saturday, from 8am to 6pm. For emergencies, please call our emergency line."
    },
    "channels": [
      {
        "channel": "whatsapp",
        "key": "+51987654321",
        "multianswer": false
      },
      {
        "channel": "telegram",
        "key": "smiles_clinic_bot",
        "multianswer": true
      }
    ],
    "services": [
      {
        "intent": "schedule_appointment",
        "reference": "Service for scheduling patient appointments at the dental clinic",
        "enabled": true,
        "method": "POST",
        "tags": ["appointment", "scheduling"],
        "endpoint": "https://api.smilesclinic.com/v1/appointments/schedule",
        "requiredFields": [
          {
            "name": "patient_name",
            "description": "Full name of the patient who wants to schedule the appointment",
            "promptHint": "Could you please provide your full name?",
            "type": "string"
          },
          {
            "name": "email",
            "description": "Patient's email address for appointment confirmation",
            "promptHint": "What's your email address for the appointment confirmation?",
            "type": "email"
          },
          {
            "name": "phone",
            "description": "Patient's phone number for contact",
            "promptHint": "Could you provide your phone number?",
            "type": "phone"
          },
          {
            "name": "preferred_date",
            "description": "Preferred date and time for the appointment",
            "promptHint": "What date and time would work best for your appointment?",
            "type": "datetime"
          },
          {
            "name": "service_type",
            "description": "Type of dental service needed",
            "promptHint": "What type of dental service do you need? (cleaning, consultation, etc.)",
            "type": "string"
          }
        ],
        "headers": {
          "Authorization": "Bearer {{clinic_api_key}}",
          "Content-Type": "application/json",
          "X-Clinic-ID": "smiles_001"
        },
        "bodyTemplate": {
          "patient": {
            "name": "{{patient_name}}",
            "email": "{{email}}",
            "phone": "{{phone}}"
          },
          "appointment": {
            "datetime": "{{preferred_date|format('yyyy-MM-dd HH:mm')}}",
            "service": "{{service_type}}",
            "timezone": "America/Lima"
          }
        },
        "bodySchema": {
          "patient_name": "string",
          "email": "string",
          "preferred_date": "date",
          "service_type": "string"
        },
        "responseMapping": {
          "confirmation_id": "$.data.appointment.id",
          "scheduled_date": "$.data.appointment.datetime",
          "status": "$.status",
          "doctor_name": "$.data.appointment.doctor.name",
          "conflict_reason": "$.error.reason"
        },
        "responseMessage": "Your appointment has been successfully scheduled for {{scheduled_date}} with Dr. {{doctor_name}}",
        "responseConditions": [
          {
            "condition": "$.status == 'confirmed'",
            "message": "¡Perfect! Your appointment has been confirmed for {{scheduled_date}} with Dr. {{doctor_name}}. We'll send you a reminder 24 hours before. Confirmation ID: {{confirmation_id}}",
            "nextService": "send_appointment_reminder"
          },
          {
            "condition": "$.status == 'conflict'",
            "message": "Sorry, that time slot is not available. {{conflict_reason}}. Would you like me to suggest other available times?",
            "nextService": "suggest_alternative_times"
          },
          {
            "condition": "$.status == 'error' && $.error.code == 'invalid_email'",
            "message": "The email address provided seems invalid. Could you please verify your email address?",
            "nextService": "verify_contact_info"
          },
          {
            "condition": "$.status == 'error' && $.error.code == 'past_date'",
            "message": "I cannot schedule appointments for past dates. Could you please choose a future date?"
          },
          {
            "condition": "$.status == 'pending'",
            "message": "Your appointment request is being reviewed. We'll contact you within 24 hours to confirm availability and finalize the details."
          }
        ],
        "action": "conversar_humano"
      },
      {
        "intent": "check_insurance",
        "reference": "Service to verify patient insurance coverage and benefits",
        "enabled": true,
        "method": "GET",
        "tags": ["insurance", "verification"],
        "endpoint": "https://api.smilesclinic.com/v1/insurance/verify",
        "requiredFields": [
          {
            "name": "insurance_provider",
            "description": "Name of the insurance company",
            "promptHint": "What's your insurance provider name?",
            "type": "string"
          },
          {
            "name": "policy_number",
            "description": "Insurance policy or member ID number",
            "promptHint": "Could you provide your policy or member ID number?",
            "type": "string"
          }
        ],
        "headers": {
          "Authorization": "Bearer {{insurance_api_key}}",
          "Content-Type": "application/json"
        },
        "responseMapping": {
          "coverage_status": "$.data.coverage.status",
          "deductible": "$.data.coverage.deductible",
          "copay": "$.data.coverage.copay",
          "covered_services": "$.data.coverage.services"
        },
        "responseMessage": "Your insurance verification is complete. Coverage status: {{coverage_status}}",
        "responseConditions": [
          {
            "condition": "$.data.coverage.status == 'active'",
            "message": "Great news! Your insurance is active. Your copay is ${{copay}} and your remaining deductible is ${{deductible}}. Covered services include: {{covered_services}}."
          },
          {
            "condition": "$.data.coverage.status == 'inactive'",
            "message": "It appears your insurance policy is not currently active. Please contact your insurance provider or we can discuss our self-pay options."
          },
          {
            "condition": "$.data.coverage.status == 'not_found'",
            "message": "I couldn't find your policy in our system. Please verify your insurance information or contact us directly for assistance."
          }
        ]
      }
    ],
    "actions": [
      {
        "intent": "assign_urgent_tag",
        "reference": "Tags patients as urgent when they mention emergency dental situations",
        "tags": ["emergency", "urgent"],
        "enabled": true,
        "responseMessage": "I've marked your case as urgent and notified our emergency team.",
        "responseJson": false,
        "responseExact": true,
        "action": [
          {
            "type": "action.tag",
            "value": "urgent_case"
          },
          {
            "type": "action.asign",
            "value": "emergency@smilesclinic.com"
          }
        ]
      },
      {
        "intent": "schedule_follow_up",
        "reference": "Automatically schedules follow-up appointments and assigns appropriate case management",
        "tags": ["follow-up", "scheduling"],
        "enabled": true,
        "responseMessage": "Your follow-up has been scheduled and assigned to our treatment coordinator.",
        "responseJson": false,
        "responseExact": false,
        "action": [
          {
            "type": "action.stage",
            "value": "follow_up_scheduled"
          },
          {
            "type": "action.segmentation",
            "value": "post_treatment_care"
          }
        ]
      },
      {
        "intent": "end_consultation",
        "reference": "Ends the AI consultation when the patient no longer needs assistance",
        "tags": ["consultation", "end"],
        "enabled": true,
        "responseMessage": "Thank you for contacting Smiles Dental Clinic. Have a great day!",
        "responseJson": false,
        "responseExact": true,
        "action": [
          {
            "type": "action.agentShutDown",
            "value": "true"
          }
        ]
      }
    ]
  }
  ```
</Accordion>

### **General** (`general`)

| Campo       | Descripción                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| **name**    | Nombre del agente. Visible en el panel. `Requerido`                                                                     |
| **prompt**  | Instrucciones base para el comportamiento del agente. `Requerido`                                                       |
| **buffer**  | Cantidad de mensajes que se mantienen como contexto. Rango: 3 a 20. `Requerido`                                         |
| color       | Color de presentación. Valores: `blue`, `orange`, `gray`, `green`, `white`.                                             |
| question    | Pregunta principal que se muestra en el portal.                                                                         |
| description | Descripción general del agente.                                                                                         |
| **zone**    | Zona donde opera el agente: `LA` (Latinoamérica) o `EU` (Europa). `Requerido`                                           |
| timezone    | Zona horaria. Ejemplo: `America/Lima`. [TimeZone Formats](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |
| tags        | Etiquetas internas para clasificar agentes.                                                                             |
| examples    | Preguntas sugeridas. Hasta 5.                                                                                           |
| showInChat  | Si el agente se muestra en el widget/chat. (boolean)                                                                    |
| enable      | Si el agente esta habilitado o no. (boolean)                                                                            |
| version     | Version del agente (auto-incrementado). Formato: `v2.0`, `v2.1`, etc.                                                   |

### **Configuracion de IA** (`AI Config`)

| Campo            | Tipo    | Descripcion                                                                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| useToolCalling   | boolean | Si es `true`, usa el orquestador de Tool Calling para conversaciones mas naturales. Si es `false`, usa el orquestador clasico. Default: `false`. |
| responseMode     | string  | Modo de respuesta: `direct` (inmediato) o `batched` (espera mensajes consecutivos). Default: `direct`.                                           |
| batchWaitSeconds | integer | Segundos de espera para acumular mensajes consecutivos (solo si `responseMode=batched`). Rango: 2-10. Default: 3.                                |
| customAIConfig   | boolean | Si es `true`, usa los `aiProviders` configurados en el agente. Si es `false`, usa el token de OpenAI de la empresa. Default: `false`.            |

### **Proveedores de IA** (`aiProviders`)

Solo se usa cuando `customAIConfig` es `true`. Permite configurar multiples proveedores de IA.

| Campo       | Tipo    | Descripcion                                                                                      |
| ----------- | ------- | ------------------------------------------------------------------------------------------------ |
| provider    | string  | Proveedor de IA: `openai`, `claude` (Anthropic), o `gemini` (Google).                            |
| model       | string  | Nombre del modelo: `gpt-4o`, `gpt-5`, `claude-3-5-sonnet-20241022`, `gemini-2.0-flash-exp`, etc. |
| apiToken    | string  | Token API del proveedor.                                                                         |
| temperature | number  | Controla la aleatoriedad en las respuestas (0-2). Default: 0.7.                                  |
| maxTokens   | integer | Maximo de tokens en la respuesta.                                                                |
| isDefault   | boolean | Si hay multiples proveedores, cual usar por defecto.                                             |

### **Instrucciones** (`instructions`)

Las instrucciones se las puede colocar en español o en ingles, no hay ningun problema, la IA respetará el idioma que se le configura.

| Campo                       | Tipo    | Descripción                                            |
| --------------------------- | ------- | ------------------------------------------------------ |
| tone                        | string  | Tono de comunicación: `professional`, `friendly`, etc. |
| style                       | string  | Estilo de respuestas: `short answers`, `detailed`.     |
| personality                 | string  | Personalidad del agente.                               |
| objective                   | string  | Objetivo principal del agente.                         |
| language                    | string  | Idioma en que debe responder. Ver tabla de idiomas.    |
| emojis                      | boolean | Si puede usar emojis.                                  |
| preferredFormat             | string  | `plain text` o `markdown`.                             |
| maxWords                    | number  | Máximo de palabras por respuesta.                      |
| avoidTopics                 | array   | Lista de temas prohibidos.                             |
| respondOnlyIfKnows          | boolean | Si debe evitar responder sin información confiable.    |
| maintainToneBetweenMessages | boolean | Mantiene el mismo tono entre mensajes.                 |
| greeting                    | string  | Mensaje de bienvenida.                                 |

**Opciones Objetive**
"help with clarity"	Enfocado en brindar respuestas claras
"sell more"	Promociona productos o servicios
"support users"	Ayuda a resolver problemas
"guide actions"	Brinda pasos concretos o instrucciones

**Opciones Personalidad**
"friendly"	Agradable y empático
"serious"	Reservado y directo
"funny"	Con toques de humor sutil
"robotic"	Más neutral, tipo IA técnica

**Opciones preferredFormat**
"plain text"	Texto simple
"markdown"	Permite negritas, listas, enlaces
"html"	Usado si se integrará en un entorno web

**Opciones Style**
"short answers"	Respuestas breves y directas
"detailed"	Respuestas explicativas, útiles para asistencia técnica
"bullet points"	Instrucciones u opciones en lista (ideal para pasos o listas)
"conversational"	Estilo fluido y natural, más humano

**Opciones Tono**
"professional"	Tono formal, educado, propio para empresas
"friendly"	Tono amigable, cercano, ideal para atención al cliente
"casual"	Informal, con lenguaje relajado y natural
"neutral"	Objetivo, sin inclinación emocional

### **Persona del Agente** (`person`)

| Campo               | Tipo    | Descripción                  |
| ------------------- | ------- | ---------------------------- |
| name                | string  | Nombre que usará el agente.  |
| role                | string  | Rol representado.            |
| speaksInFirstPerson | boolean | Habla en primera persona.    |
| isHuman             | boolean | Simula ser una persona real. |

### **Fallbacks**

| Campo           | Tipo   | Descripción                         |
| --------------- | ------ | ----------------------------------- |
| noAnswer        | string | Mensaje si no tiene respuesta.      |
| serviceError    | string | Mensaje de error de servicio.       |
| doNotUnderstand | string | Mensaje si no entiende la consulta. |

### **Reglas**

| Campo                    | Tipo    | Descripción                                                                |
| ------------------------ | ------- | -------------------------------------------------------------------------- |
| doNotMentionPrices       | boolean | No hablar de precios.                                                      |
| doNotDiagnose            | boolean | No hacer diagnósticos médicos.                                             |
| doNotRespondOutsideHours | string  | Mensaje fuera del horario definido. Trabaja junto con el campo de Timezone |

### **Listados**

**Códigos de Idioma**

| Valor  | Descripción                     |
| ------ | ------------------------------- |
| es     | Español general                 |
| es-419 | Español latinoamericano neutral |
| es-ES  | Español de España               |
| en     | Inglés general                  |
| en-US  | Inglés estadounidense           |
| en-GB  | Inglés británico                |
| fr     | Francés general                 |
| fr-FR  | Francés de Francia              |
| pt-BR  | Portugués brasileño             |
| de     | Alemán                          |

**Códigos de Timezone**

| Valor                | Descripción                  |
| -------------------- | ---------------------------- |
| America/Los\_Angeles | Los Ángeles (UTC-08:00)      |
| America/Mexico\_City | Ciudad de México (UTC-06:00) |
| America/New\_York    | Nueva York (UTC-05:00)       |
| America/Bogota       | Bogotá (UTC-05:00)           |
| America/Lima         | Lima (UTC-05:00)             |
| America/Sao\_Paulo   | São Paulo (UTC-03:00)        |
| Europe/London        | Londres (UTC+00:00)          |
| Europe/Madrid        | Madrid (UTC+01:00)           |
| Europe/Paris         | París (UTC+01:00)            |
| Europe/Berlin        | Berlín (UTC+01:00)           |
| Europe/Moscow        | Moscú (UTC+03:00)            |
| Asia/Dubai           | Dubái (UTC+04:00)            |
| Asia/Kolkata         | Nueva Delhi (UTC+05:30)      |
| Asia/Shanghai        | Pekín (UTC+08:00)            |
| Asia/Tokio           | Tokio (UTC+09:00)            |